spexcode 0.6.2 → 0.6.5

package/spec-cli/src/localIssues.ts

@@ -1,538 +0,0 @@
-// @@@ the local issue store - the LOCAL store of the one Issue object ([[issues]] / [[local-issues]] /
-// [[mentions]]). A thread IS an Issue whose `store` is 'local' — membership implied by WHERE the file lives,
-// never written into it. One thread = one PLAIN markdown file at <main>/.spec/.issues/<id>.md; there is
-// deliberately no content-kind taxonomy (a change suggestion, an annotation, a Q&A are the same mechanism —
-// the prose says what it is). Others reply/discuss like an async chatroom; a supervisor drains it via
-// `spex issue ls` (reading is the port's job, issues.ts — this module owns only the store + its write verbs).
-// Because a thread file is NOT named spec.md, the spec walk never nodes it and isSpecMd ignores it —
-// invisible to lint / drift / deriveStatus / board with ZERO exemption. The store lives on the TRUNK, not
-// per-branch: reads and writes target the main checkout and commit STRAIGHT to it (--no-verify, provably
-// store-only), so a post-merge thread lands durably even though the author's own branch already merged.
-// A committing write is allowed ONLY from the trunk checkout itself (isPrimaryCheckout) — a linked-worktree
-// backend sharing that main is refused loud, never left to fabricate a stray commit on a main it doesn't own;
-// SPEXCODE_ISSUES_DIR routes an e2e/test rig to a disposable plain-file store (see localStoreDir below).
-// The on-disk dir was historically `.spec/.forum`; a one-shot self-migration ([[issues-store-rename]])
-// renames any legacy `.spec/.forum` to `.spec/.issues` on the first store touch after a toolchain update.
-import { readdirSync, existsSync, mkdirSync, writeFileSync, readFileSync, rmdirSync, statSync } from 'node:fs'
-import { join, dirname, resolve as resolvePath } from 'node:path'
-import { git, headSha, repoRoot } from './git.js'
-import { mainCheckout, envSessionId, readConfig } from './layout.js'
-import { parseMentions } from './mentions.js'
-import type { Issue, Reply } from './issues.js'
-
-const LOCAL_STORE_REL = '.spec/.issues'
-// the pre-rename dir ([[issues-store-rename]]); ensureStoreMigrated() renames it to LOCAL_STORE_REL once.
-const LEGACY_STORE_REL = '.spec/.forum'
-
-// @@@ the on/off switch - the issues workflow is an OPT-OUTABLE feature (default ON). The single source of
-// truth is `spexcode.json`'s `issues.enabled` (the same settings file that carries every other toggle),
-// read via readConfig so a machine-local `spexcode.local.json` can override it. OFF silences the post-merge
-// nudge (and, in the dashboard, hides the issues view); the raw write verbs stay usable, since running one
-// is explicit consent. There is deliberately NO CLI toggle verb (v0.3.0 — "no `spex config set`" is this
-// project's standing rule): flip the key by editing the JSON, effective immediately because readConfig
-// reads the working tree. A legacy pre-rename `proposals.enabled` key is NOT read (no fallback — fail
-// toward the default); `spex doctor` reports it so an old settings file gets repaired, not silently obeyed.
-export const issuesEnabled = (): boolean =>
-  readConfig(mainCheckout()).issues?.enabled ?? true
-
-const list = (v: string | undefined): string[] =>
-  v ? v.split(',').map((s) => s.trim()).filter(Boolean) : []
-
-// @@@ where a store write lands — ONE deterministic rule ([[local-issues]] "only the trunk checkout may
-// commit"). Every backend resolves the store to `mainCheckout()` (dirname of the shared git-common-dir), so a
-// backend serving a LINKED WORKTREE would git-commit a stray issue onto the REAL, live main — dirtying it and
-// racing its index.lock. The rule:
-//   1. SPEXCODE_ISSUES_DIR override → a DISPOSABLE store of plain files (no git, no shared main); the e2e/test
-//      seam. Both reads and writes target it, so a test rig throws its whole store away.
-//   2. else the trunk `.spec/.issues/` — but a *committing* write is allowed ONLY from the trunk checkout
-//      itself (repoRoot === mainCheckout: the primary backend, or a throwaway clone owning its own main). A
-//      linked-worktree backend is refused loud (requirePrimaryStore) rather than silently writing someone
-//      else's main. Reads always resolve to the trunk (visibility never hostages on being primary).
-const overrideStoreDir = (): string | null => {
-  const p = process.env.SPEXCODE_ISSUES_DIR?.trim()
-  return p ? p : null
-}
-// is THIS process rooted in the trunk checkout itself? True for the primary backend and for a clone (its own
-// .git → its own disposable main); false for a linked-worktree backend, the store-write footgun.
-const isPrimaryCheckout = (): boolean => {
-  try { return resolvePath(repoRoot()) === resolvePath(mainCheckout()) } catch { return false }
-}
-// fail LOUD before a committing write from a non-trunk checkout: never fabricate a commit on a shared main
-// this process does not own. (The disposable override bypasses this — it commits to nothing.)
-function requirePrimaryStore(action: string): void {
-  if (isPrimaryCheckout()) return
-  throw new Error(
-    `refusing to ${action}: this backend serves a linked worktree (${resolvePath(repoRoot())}), not the trunk ` +
-    `checkout (${resolvePath(mainCheckout())}) — committing here would land a stray issue on the REAL main and ` +
-    `race its index. Run the write from the trunk checkout (or its backend), or, for a throwaway/e2e run, set ` +
-    `SPEXCODE_ISSUES_DIR=<disposable-dir> to write plain files nowhere near the real store.`)
-}
-
-// the local issue store dir — a fixed path directly under the trunk's .spec (name-independent, unlike the
-// .plugins system which nests under the named root node), OR the disposable override. Every read and write goes here.
-const localStoreDir = (): string => overrideStoreDir() ?? join(mainCheckout(), LOCAL_STORE_REL)
-// the author's signature: the effective governed session id (envSessionId handles the claude/codex split).
-export const currentSession = (): string => envSessionId() || 'unknown'
-// a synchronous sleep for the commit-retry backoff (Date/timers-free, safe in any runtime).
-const sleep = (ms: number) => Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms)
-
-// ── file format ──────────────────────────────────────────────────────────────────────────────────────
-// frontmatter (concern/by/status/nodes/evidence/created) + a prose body, then any replies — each
-// preceded by a `<!-- reply: <by> @ <iso> -->` sentinel: invisible in rendered markdown, unambiguous to
-// parse. Only the store writes these files, so a fixed shape is safe.
-//
-// A REMARK ([[remark-substrate]]) is a reply carrying extra state, appended to the SAME sentinel as a
-// ` :: <space-joined k=v attrs>` tail (a plain reply has no tail → parses unchanged, backward compatible):
-//   rid=<id>            stable per-remark id — its presence marks the reply a remark
-//   sha=<targetCodeSha> the reading the remark was authored against
-//   resolved=<by>@<at>  present only once resolved (absent ⟹ resolved:false)
-const REPLY_RE = /^<!-- reply: (.+?) @ (.+?)(?: :: (.+))? -->$/
-
-function parse(id: string, text: string): Issue {
-  const m = text.match(/^---\n([\s\S]*?)\n---\n?([\s\S]*)$/)
-  const fm: Record<string, string> = {}
-  for (const line of (m ? m[1] : '').split('\n')) {
-    const mm = line.match(/^([a-zA-Z]+):\s*(.*)$/)
-    if (mm) fm[mm[1]] = mm[2].trim()
-  }
-  const body: string[] = []
-  const replies: Reply[] = []
-  let cur: Reply | null = null
-  for (const line of (m ? m[2] : text).replace(/^\n+/, '').split('\n')) {
-    const rm = line.match(REPLY_RE)
-    if (rm) { cur = { by: rm[1], at: rm[2], body: '', ...parseRemarkAttrs(rm[3]) }; replies.push(cur); continue }
-    if (cur) cur.body += (cur.body ? '\n' : '') + line
-    else body.push(line)
-  }
-  return {
-    id,
-    store: 'local',
-    concern: fm.concern || id,
-    by: fm.by || 'unknown',
-    status: fm.status === 'landed' ? 'landed' : 'open',
-    nodes: list(fm.nodes),
-    created: fm.created || '',
-    body: body.join('\n').trim(),
-    replies: replies.map((r) => ({ ...r, body: r.body.trim() })),
-    evidence: list(fm.evidence),
-  }
-}
-
-// user body text must never FORGE a reply sentinel: a line matching `<!-- reply: … -->` in a body would be
-// re-read as a thread boundary, splitting the thread and truncating the body. Neutralize the marker in user
-// content (a zero-width space breaks the `<!-- reply:` prefix — invisible on render, idempotent), so only
-// serialize's OWN sentinels parse as boundaries. Frontmatter scalars are single-line-stripped for the same
-// reason (a newline/`---` in a concern can't break the block).
-const safeBody = (t: string): string => t.trim().replace(/<!-- reply:/g, '<!--​reply:')
-const safeScalar = (t: string): string => t.replace(/[\r\n]+/g, ' ').trim()
-
-// the ` :: k=v k=v` remark tail on a reply sentinel ↔ the reply's remark fields. `undefined` attrs (a plain
-// reply) → no remark fields; `rid` present → the reply IS a remark ([[remark-substrate]]). Values are
-// space-free (ids, a codeSha, a session id, an ISO instant), so a space-split is unambiguous.
-function parseRemarkAttrs(attrs: string | undefined): Partial<Reply> {
-  if (!attrs) return {}
-  const kv = new Map<string, string>()
-  for (const tok of attrs.trim().split(/\s+/)) { const i = tok.indexOf('='); if (i > 0) kv.set(tok.slice(0, i), tok.slice(i + 1)) }
-  if (!kv.has('rid')) return {}
-  const out: Partial<Reply> = { rid: kv.get('rid'), targetCodeSha: kv.get('sha') ?? '', resolved: false }
-  const r = kv.get('resolved')
-  if (r) { const at = r.indexOf('@'); out.resolved = true; out.resolvedBy = r.slice(0, at); out.resolvedAt = r.slice(at + 1) }
-  return out
-}
-function serializeRemarkAttrs(r: Reply): string {
-  if (r.rid === undefined) return ''
-  const parts = [`rid=${r.rid}`, `sha=${r.targetCodeSha ?? ''}`]
-  if (r.resolved) parts.push(`resolved=${r.resolvedBy ?? ''}@${r.resolvedAt ?? ''}`)
-  return ` :: ${parts.join(' ')}`
-}
-
-function serialize(p: Issue): string {
-  const fm = [
-    `concern: ${safeScalar(p.concern)}`,
-    `by: ${safeScalar(p.by)}`,
-    `status: ${safeScalar(p.status)}`,
-    p.nodes.length ? `nodes: ${p.nodes.join(', ')}` : '',
-    p.evidence.length ? `evidence: ${p.evidence.join(', ')}` : '',
-    `created: ${p.created}`,
-  ].filter(Boolean)
-  let out = `---\n${fm.join('\n')}\n---\n\n${safeBody(p.body)}\n`
-  for (const r of p.replies) out += `\n<!-- reply: ${safeScalar(r.by)} @ ${safeScalar(r.at)}${serializeRemarkAttrs(r)} -->\n${safeBody(r.body)}\n`
-  return out
-}
-
-export function loadLocalIssues(): Issue[] {
-  ensureStoreMigrated()   // read path: a pre-rename deployment migrates on first read, so no thread is lost
-  const dir = localStoreDir()
-  if (!existsSync(dir)) return []
-  return readdirSync(dir, { withFileTypes: true })
-    .filter((e) => e.isFile() && e.name.endsWith('.md'))
-    .map((e) => parse(e.name.replace(/\.md$/, ''), readFileSync(join(dir, e.name), 'utf8')))
-    .sort((a, b) => a.created.localeCompare(b.created))
-}
-
-export function loadOne(id: string): Issue {
-  ensureStoreMigrated()
-  const f = join(localStoreDir(), `${id}.md`)
-  if (!existsSync(f)) throw new Error(`no local issue '${id}' (see \`spex issue ls --all --store local\`)`)
-  return parse(id, readFileSync(f, 'utf8'))
-}
-
-// a filesystem-safe, readable, collision-free id from the concern (slug + numeric suffix if taken).
-// RESERVED_IDS are the words an issue address gives its own meaning — `new` is the compose PAGE
-// ([[issues-view]]), so an issue owning that id would be unreachable at its own detail address. The slug
-// steps around them with the same numeric suffix a taken id gets: a collision, not a silent shadow.
-const RESERVED_IDS = new Set(['new'])
-function uniqueId(concern: string): string {
-  const base = concern.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 48) || 'issue'
-  const dir = localStoreDir()
-  let id = base
-  for (let n = 2; RESERVED_IDS.has(id) || existsSync(join(dir, `${id}.md`)); n++) id = `${base}-${n}`
-  return id
-}
-
-// @@@ store lock - local-issue writes contend two ways: git commits share the repo index.lock, and a
-// reply's read-modify-write of one thread file loses an update if two race (both read the base, last write
-// wins). A single cross-process lock serializes the WHOLE prepare→write→commit, killing both. It is an
-// atomic `mkdir` (in .git, never committed); a lock whose holder crashed is stolen after it goes stale.
-// Because the commit is `--no-verify` fast (below), serialized writes stay quick even under a burst. The
-// lock FILE keeps its historical `spexcode-forum.lock` name ON PURPOSE: during the one-shot store-dir
-// migration ([[issues-store-rename]]) an old and a new toolchain can run against the SAME checkout at once,
-// and they mutually exclude only while contending on the SAME lock name — renaming it would open exactly
-// the migration race the lock exists to close.
-let lockHeld = false   // re-entrancy guard so ensureStoreMigrated() no-ops when reached from inside a hold
-function withStoreLock<T>(fn: () => T): T {
-  // the disposable store locks inside its own dir; the trunk store locks in the shared `.git` (one lock name
-  // across every worktree of the clone, so all writers of the SAME real store mutually exclude).
-  const override = overrideStoreDir()
-  const lock = override ? join(override, '.spexcode-issues.lock') : join(mainCheckout(), '.git', 'spexcode-forum.lock')
-  mkdirSync(dirname(lock), { recursive: true })   // parent must exist for the atomic mkdir-acquire (a no-op for .git)
-  for (let i = 0; ; i++) {
-    try { mkdirSync(lock); break }                                   // atomic acquire
-    catch {
-      try { if (Date.now() - statSync(lock).mtimeMs > 20000) rmdirSync(lock) } catch { /* released meanwhile */ }
-      sleep(40 + Math.floor(Math.random() * 80))                     // spin with jitter until free / stolen
-    }
-  }
-  lockHeld = true
-  try { return fn() } finally { lockHeld = false; try { rmdirSync(lock) } catch { /* already gone */ } }
-}
-
-// @@@ one-shot store-dir migration ([[issues-store-rename]]) - the local issue store's on-disk dir was
-// historically `.spec/.forum`; it is now `.spec/.issues`. Any pre-rename deployment migrates ITSELF on the
-// first store touch after its toolchain updates: a single committed `git mv` on the trunk, so a thread's
-// whole reply history reads identically afterwards (`git log --follow` traces through the rename — the data
-// is git, and a rename preserves it). Called at every store entrypoint BEFORE the lock is taken; it takes
-// the lock itself to do the mv, so the whole find→check→mv is atomic against a concurrent first-touch burst:
-// exactly ONE mv commit, because a racer that waited on the lock re-checks under it and finds nothing to do.
-// Fast path: no legacy dir → instant, no lock (the common case after migration / on a fresh repo). Both
-// dirs present (pathological) → fail LOUD with the repair, never a silent merge.
-function ensureStoreMigrated(): void {
-  if (lockHeld) return                                     // inside a hold: an outer entrypoint already ran this
-  if (overrideStoreDir()) return                           // disposable store: no legacy trunk dir to migrate
-  if (!isPrimaryCheckout()) return                         // a git-committing migration is trunk-only; the primary migrates on its next touch
-  const root = mainCheckout()
-  if (!existsSync(join(root, LEGACY_STORE_REL))) return    // fresh or already-migrated: nothing to do (no lock)
-  withStoreLock(() => {
-    const r = mainCheckout()
-    const legacy = join(r, LEGACY_STORE_REL), current = join(r, LOCAL_STORE_REL)
-    if (!existsSync(legacy)) return                        // a racer migrated it while we waited on the lock
-    if (existsSync(current)) throw new Error(
-      `both ${LEGACY_STORE_REL} and ${LOCAL_STORE_REL} exist in ${r} — refusing to auto-merge the local ` +
-      `issue store. Reconcile by hand: move any threads from ${LEGACY_STORE_REL} into ${LOCAL_STORE_REL}, ` +
-      `then \`git rm -r ${LEGACY_STORE_REL} && git commit\`, and re-run.`)
-    git(['-C', r, 'mv', LEGACY_STORE_REL, LOCAL_STORE_REL])
-    git(['-C', r, 'commit', '--no-verify', '-m', `issues: store dir ${LEGACY_STORE_REL} → ${LOCAL_STORE_REL}`,
-      '--', LEGACY_STORE_REL, LOCAL_STORE_REL])
-  })
-}
-
-// write + commit ONE store file STRAIGHT to the trunk. The commit is `--no-verify`: the file is DATA,
-// structurally invisible to spec-lint, and the commit is provably store-only (one .spec/.issues/ path), so the
-// pre-commit gate would only pass anyway — running it just burns seconds (tsx cold-start) holding the lock.
-// A NO-CHANGE write is idempotent SUCCESS, never a failure: when the serialized bytes already equal the
-// stored state (a duplicate close — the store IS the requested state), `git commit` would exit 1
-// 'nothing to commit', so we detect the no-op after `add` (the staged path equals HEAD → status is silent)
-// and skip the commit. Returns whether the store actually changed, so a caller can say 'already <state>'.
-// MUST run while holding withStoreLock — it is the write half of a locked read-modify-write; its callers
-// (commitStore, findOrCreateEvalThread) own the lock, so it never acquires one itself (mkdir is not re-entrant).
-function writeStoreFile(p: Issue, message: string): boolean {
-  const override = overrideStoreDir()
-  if (override) {                                          // disposable store: a plain file, never a commit, never a shared main
-    mkdirSync(override, { recursive: true })
-    const f = join(override, `${p.id}.md`)
-    const data = serialize(p)
-    if (existsSync(f) && readFileSync(f, 'utf8') === data) return false
-    writeFileSync(f, data)
-    return true
-  }
-  requirePrimaryStore('write a local issue')              // a linked-worktree backend must NOT commit onto the real main
-  const root = mainCheckout()
-  const rel = `${LOCAL_STORE_REL}/${p.id}.md`
-  mkdirSync(join(root, LOCAL_STORE_REL), { recursive: true })
-  writeFileSync(join(root, rel), serialize(p))
-  git(['-C', root, 'add', '--', rel])
-  if (!git(['-C', root, 'status', '--porcelain', '--', rel]).trim()) return false   // staged == HEAD: the no-op
-  git(['-C', root, 'commit', '--no-verify', '-m', message, '--', rel])
-  return true
-}
-
-// @@@ the shared trunk-data commit — the committing half of the store discipline, exported for OTHER
-// git-tracked data writes that need a durable landing with no worktree ritual behind them (the eval
-// sidecar's human-ok, [[human-ok]]). Same rules as the issue store's own write: only the trunk checkout
-// itself commits (a linked-worktree caller gets 'not-primary' back and leaves its append for its own
-// session's ritual commit — the sidecar, unlike the issue store, legitimately lives per-branch and
-// merges); the commit is `--no-verify` and provably scoped to the one data path; the shared store lock
-// serializes it against every other trunk data write so racing writers never fight over the git index.
-export function commitTrunkData(relPath: string, message: string): 'committed' | 'no-op' | 'not-primary' {
-  if (overrideStoreDir()) return 'not-primary'   // a disposable-store test rig commits nothing, ever
-  if (!isPrimaryCheckout()) return 'not-primary'
-  return withStoreLock(() => {
-    const root = mainCheckout()
-    git(['-C', root, 'add', '--', relPath])
-    if (!git(['-C', root, 'status', '--porcelain', '--', relPath]).trim()) return 'no-op'
-    git(['-C', root, 'commit', '--no-verify', '-m', message, '--', relPath])
-    return 'committed'
-  })
-}
-
-// prepare (a FRESH read-modify or a new thread) + write + commit a single store file, all under the store
-// lock so the read-modify-write is atomic. prepare() runs INSIDE the lock, so a reply/close reads the
-// current thread, never a stale copy. A pre-rename store migrates first (before the lock — ensure takes it).
-// `changed: false` = the store already held exactly this state (see writeStoreFile) — success, nothing committed.
-function commitStore(message: string, prepare: () => Issue): { issue: Issue; changed: boolean } {
-  ensureStoreMigrated()
-  return withStoreLock(() => {
-    const p = prepare()
-    const changed = writeStoreFile(p, message)
-    return { issue: p, changed }
-  })
-}
-
-// `author` defaults to the effective session id, but a caller (the dashboard's human write path) may pass
-// `'human'` — the write mechanism is identical either way, only the signature differs.
-// The thread's `nodes:` are INFERRED from the text's `[[node]]` topic links ([[mentions]] — the one in-text
-// reference primitive every input already carries), unioned with any explicitly-passed ids (`--node`): a
-// writer links nodes by writing them, never by re-typing ids into a separate field.
-export function openIssue(concern: string, opts: { nodes?: string[]; body?: string; evidence?: string[]; author?: string } = {}): Issue {
-  const nodes = [...new Set([...(opts.nodes || []), ...parseMentions(`${concern}\n${opts.body || ''}`).nodes])]
-  return commitStore(`issue: ${concern}`, () => ({
-    id: uniqueId(concern),   // minted INSIDE the lock, so two racing posts can't pick the same id
-    store: 'local',
-    concern,
-    by: opts.author || currentSession(),
-    status: 'open',
-    nodes,
-    created: new Date().toISOString(),
-    body: (opts.body || `(no detail given — ${concern})`).trim(),
-    replies: [],
-    evidence: opts.evidence || [],
-  })).issue
-}
-
-// mint a per-thread-unique remark id (retry on the rare collision within one thread). Short + readable so a
-// `<thread-id>#<rid>` ref is typeable; stable, so a resolve/retract never lands on the wrong remark.
-function mintRid(existing: Set<string>): string {
-  let rid: string
-  do { rid = 'r' + Math.random().toString(36).slice(2, 6) } while (existing.has(rid))
-  return rid
-}
-
-// a REMARK ([[remark-substrate]]) rides the SAME committed reply write, just stamping the remark fields: a
-// fresh unresolved bit + a minted stable rid + the codeSha it was authored against. Absent `remark` this is
-// an ordinary reply, unchanged. Returns the thread; the new reply is its last, so a caller reads back its rid.
-export function reply(id: string, body: string, author?: string, evidence?: string[], remark?: { targetCodeSha: string }): Issue {
-  const by = author || currentSession()
-  return commitStore(remark ? `remark(${id}): by ${by}` : `issue(${id}): reply by ${by}`, () => {
-    const p = loadOne(id)   // fresh read under the lock → no lost-update when replies race
-    const post: Reply = { by, at: new Date().toISOString(), body: body.trim() }
-    if (remark) { post.rid = mintRid(new Set(p.replies.map((r) => r.rid).filter((x): x is string => !!x))); post.targetCodeSha = remark.targetCodeSha; post.resolved = false }
-    p.replies.push(post)
-    // an anchored annotation carries its frame blob: the reply's evidence hashes accrue onto the THREAD's
-    // typed evidence[] (deduped), so the thread stays the one place a video finding's blobs are indexed.
-    if (evidence?.length) p.evidence = [...new Set([...p.evidence, ...evidence])]
-    return p
-  }).issue
-}
-
-// @@@ the PROGRAMMATIC store write surface — the dashboard's human write path calls these (author `'human'`).
-// The store is git-native data, so a human's write goes through the SAME open/reply the CLI uses (committed
-// straight to the trunk). @session remains text in that committed discussion; it never summons an agent.
-// Originator courtesy is composed above this store because it needs eval-aware candidate resolution.
-export async function replyLocalIssue(id: string, body: string, author: string, evidence?: string[], remark?: { targetCodeSha: string }): Promise<{ thread: Issue }> {
-  const thread = reply(id, body, author, evidence, remark)
-  return { thread }
-}
-
-
-
-export async function postLocalIssue(
-  concern: string,
-  opts: { nodes?: string[]; body?: string; evidence?: string[]; author: string },
-): Promise<{ thread: Issue }> {
-  const thread = openIssue(concern, { nodes: opts.nodes, body: opts.body, evidence: opts.evidence, author: opts.author })
-  return { thread }
-}
-
-export function closeLocalIssue(id: string): { status: 'landed'; already: boolean } {
-  const { changed } = commitStore(`issue(${id}): close`, () => {
-    const p = loadOne(id)
-    p.status = 'landed'
-    return p
-  })
-  return { status: 'landed', already: !changed }
-}
-
-// ── remarks ([[remark-substrate]]) ──────────────────────────────────────────────────────────────────
-// A remark is a reply carrying a resolvable bit, attached to a HOST: a local issue, or a scenario keyed by
-// (node, scenario). The scenario track is NOT a new store — it is the annotator's lazy eval thread, keyed by
-// its `eval: <node> · <scenario>` concern; a remark reuses it, creating it on first remark as a stub
-// container (every remark is a reply, never the thread body, so the resolved bit always lives in one place).
-// @@@ the eval-concern format, once - composer and parser side by side. The parser existed in two copies while
-// a CLI surface down here had to recognise the format without being able to import the module that composes it;
-// [[issues-cli]] removed that constraint, so the format is one pair now. `node` is matched non-greedily because
-// it can never contain ' · ' while a scenario name may.
-const evalConcernKey = (node: string, scenario: string): string => `eval: ${node} · ${scenario}`
-const EVAL_CONCERN_RE = /^eval: (.+?) · (.+)$/
-export const parseEvalConcern = (concern: string): { node: string; scenario: string } | null => {
-  const m = EVAL_CONCERN_RE.exec(concern)
-  return m ? { node: m[1].trim(), scenario: m[2].trim() } : null
-}
-
-// find-or-create the ONE scenario thread for (node, scenario), keyed by its eval concern, ATOMICALLY under
-// the store lock. R4 says a scenario's remark track lives ONCE — but a concurrent first-remark burst is a
-// normal dogfood situation (SpexCode runs parallel workers), and if the not-found read sat OUTSIDE the lock
-// two racers could both read "absent" and both create, minting a second thread whose remarks are invisible
-// to the concern key (a silent teeth blind spot). Holding one lock across both the find AND the create closes
-// that window: a racer either sees the thread the first created, or is the first. The stub is a pure
-// container (its body carries a [[wiki-link]], never an @-reference), so it needs no async notification — a
-// synchronous create suffices, and staying sync is exactly what lets it share the lock hold.
-function findOrCreateEvalThread(node: string, scenario: string, author: string): Issue {
-  ensureStoreMigrated()   // migrate before the lock (ensure takes it itself; never nest a store-lock hold)
-  const concern = evalConcernKey(node, scenario)
-  return withStoreLock(() => {
-    const existing = loadLocalIssues().find((t) => t.store === 'local' && t.concern === concern)
-    if (existing) return existing
-    const p: Issue = {
-      id: uniqueId(concern), store: 'local', concern, by: author, status: 'open',
-      nodes: [node], created: new Date().toISOString(),
-      body: `Remarks on the \`${scenario}\` eval of [[${node}]].`, replies: [], evidence: [],
-    }
-    writeStoreFile(p, `issue: ${concern}`)
-    return p
-  })
-}
-
-function resolveRemarkHost(host: { issue?: string; node?: string; scenario?: string }, author: string): string {
-  if (host.scenario) {
-    const node = host.node
-    if (!node) throw new Error('a scenario remark needs a node plus --scenario <name>')
-    return findOrCreateEvalThread(node, host.scenario, author).id
-  }
-  if (!host.issue) throw new Error('a remark needs a host: an issue id, or a node with --scenario <name>')
-  return loadOne(host.issue).id   // throws loudly if the issue doesn't exist
-}
-
-// author a remark on a host — the ONE write both the CLI (`spex remark add`) and the server call. Stamps the
-// codeSha it was authored against (the worktree HEAD by default — R2). Returns the `<thread-id>#<rid>` ref.
-export async function remarkOnHost(
-  host: { issue?: string; node?: string; scenario?: string },
-  body: string,
-  opts: { codeSha?: string; author?: string; evidence?: string[] } = {},
-): Promise<{ ref: string; rid: string; codeSha: string; thread: Issue; author: string }> {
-  const author = opts.author || currentSession()
-  const codeSha = opts.codeSha || headSha(repoRoot())
-  const id = resolveRemarkHost(host, author)
-  const { thread } = await replyLocalIssue(id, body, author, opts.evidence, { targetCodeSha: codeSha })
-  const rid = thread.replies[thread.replies.length - 1].rid!
-  return { ref: `${id}#${rid}`, rid, codeSha, thread, author }
-}
-
-// a remark ref is `<thread-id>#<rid>`; the thread id (a store slug) never contains '#', so split on the last.
-function parseRemarkRef(ref: string): { id: string; rid: string } {
-  const i = ref.lastIndexOf('#')
-  if (i <= 0 || i === ref.length - 1) throw new Error(`bad remark ref '${ref}' — expected <thread-id>#<rid> (the id \`spex remark add\` printed)`)
-  return { id: ref.slice(0, i), rid: ref.slice(i + 1) }
-}
-
-// resolve a remark (R3): a DELIBERATE call by a SECOND PARTY — never the author (no self-resolve: an
-// identity comparison, so the dashboard's `human` cannot resolve a human-authored remark either), and
-// MONOTONIC (no un-resolve — a regression is a NEW remark). The resolver's identity is derived by the
-// SURFACE ([[remark-substrate]] LAW L): a governed session id from the CLI, the `human` sentinel from the
-// dashboard — both are real second parties, so the same rule runs on both. `by` is the resolving party.
-export function resolveRemark(ref: string, by: string): { thread: Issue; rid: string } {
-  const { id, rid } = parseRemarkRef(ref)
-  const { issue: thread } = commitStore(`remark(${id}#${rid}): resolved by ${by}`, () => {
-    const p = loadOne(id)
-    const r = p.replies.find((x) => x.rid === rid)
-    if (!r) throw new Error(`no remark '${ref}' in that thread`)
-    if (!by || by === 'unknown') throw new Error(`resolve needs a real identity (got '${by || 'none'}'): run it under a governed session, or from the dashboard (its actor is 'human')`)
-    if (r.resolved) throw new Error(`remark '${ref}' is already resolved — monotonic: a regression is a NEW remark, never an un-resolve`)
-    if (r.by === by) throw new Error(`refusing to self-resolve '${ref}': the author (${by}) may not resolve their own remark — resolve is a second party's deliberate judgment`)
-    r.resolved = true; r.resolvedBy = by; r.resolvedAt = new Date().toISOString()
-    return p
-  })
-  return { thread, rid }
-}
-
-// retract a remark (R3): the AUTHOR withdraws their OWN remark, removing it — but ONLY while it is
-// unresolved. Only the author may retract; and once a SECOND party has deliberately resolved it, the remark
-// (and that recorded judgment) is part of the record — retract may not erase it. This makes R3's
-// monotonicity two-sided: resolve can't be undone, and retract can't back-door an un-resolve by deleting the
-// resolved remark. A regression after a resolve is a NEW remark, never a retract-and-reraise.
-export function retractRemark(ref: string, by: string): { thread: Issue; rid: string } {
-  const { id, rid } = parseRemarkRef(ref)
-  const { issue: thread } = commitStore(`remark(${id}#${rid}): retracted by ${by}`, () => {
-    const p = loadOne(id)
-    const idx = p.replies.findIndex((x) => x.rid === rid)
-    if (idx < 0) throw new Error(`no remark '${ref}' in that thread`)
-    if (p.replies[idx].by !== by) throw new Error(`only the author (${p.replies[idx].by}) may retract '${ref}' — you are '${by}'`)
-    if (p.replies[idx].resolved) throw new Error(`refusing to retract '${ref}': it was resolved by ${p.replies[idx].resolvedBy} — a resolved remark is part of the record (monotonic), retract only withdraws an UNRESOLVED remark; a regression is a NEW remark`)
-    p.replies.splice(idx, 1)
-    return p
-  })
-  return { thread, rid }
-}
-
-// the post-merge nudge TEXT ([[local-issues]]) — produced HERE so the toggle and the wording live in one
-// place; the post-merge git hook is a thin caller that just echoes this. Returns '' when the feature is OFF,
-// so the hook prints nothing.
-export function nudge(node: string): string {
-  if (!issuesEnabled()) return ''
-  return [
-    '── issues ─────────────────────────────────────────────────────────',
-    `Your work (${node || 'this node'}) just landed. Two issue checks before you close:`,
-    '',
-    '1. CLOSE what you finished. An issue whose work just landed is closed, not',
-    '   left open — the open set is the OUTSTANDING work, so a stale open reads as a',
-    '   lie:  spex issue ls --store local     then   spex issue close <id>',
-    '',
-    '2. RECORD only what OUTLIVES this task — a concern you are NOT acting on now:',
-    '   an off-mainline smell / awkward boundary / wish, or a trivial-but-must-not-',
-    "   forget to-do that doesn't earn a spec node. NOT a bug tracker (that is the",
-    '   spec graph + the forge), NOT your assigned task or a fix you are about to',
-    '   make — those need no issue. Only the taste that would otherwise evaporate:',
-    '     spex issue ls                            # read first — reply if already raised',
-    '     spex issue open "<concern>" [--node <id>]   # else open one',
-    'A supervisor drains the store later. (Advisory — skip if nothing is owed.)',
-    '───────────────────────────────────────────────────────────────────',
-  ].join('\n')
-}
-
-// @@@ close-time issue closeout ([[local-issues]] / [[state]]) — the DATA half of the propose-close nudge:
-// appended to the `done --propose close` declaration BESIDE the resource-cleanup reminder (cli.ts, same
-// insertion point, same semantics — a nudge, never a gate). Data-driven so it earns its line: it lists the
-// still-open local threads THIS session touched (authored or replied; eval `eval: <node> · <scenario>`
-// containers excluded — they host remarks and outlive every session by design) and prints NOTHING when the
-// session owes nothing, when the feature is OFF, or when there is no session identity. Some issues rightly
-// outlive their session (a taste concern waiting for the drain), so the ask is close OR say why it stays
-// open — never a forced close.
-export function closeoutNudge(sessionId: string | null | undefined): string {
-  if (!sessionId || sessionId === 'unknown' || !issuesEnabled()) return ''
-  const mine = loadLocalIssues().filter((t) =>
-    t.status === 'open' && !parseEvalConcern(t.concern) &&
-    (t.by === sessionId || t.replies.some((r) => r.by === sessionId)))
-  if (!mine.length) return ''
-  return `\n\nIssue closeout — ${mine.length} still-open local issue(s) you touched (opened or replied): ${mine.map((t) => t.id).join(', ')}. For each, close it now if its work is finished (\`spex issue close <id>\`), or reply why it should stay open past this session (\`spex issue reply <id> --body "<why>"\`). Some issues rightly outlive their session — this is a reminder to sweep, not a gate.`
-}
-
-// ───────────────────────── CLI ─────────────────────────