spexcode 0.2.3 → 0.2.5

package/spec-cli/src/materialize.ts

@@ -1,27 +1,33 @@
-import { writeFileSync, mkdirSync, readFileSync, existsSync } from 'node:fs'
+import { writeFileSync, mkdirSync, readFileSync, existsSync, readdirSync, rmSync, rmdirSync } from 'node:fs'
 import { join, dirname, relative } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { execFileSync } from 'node:child_process'
 import { loadSystemConfig, loadSkillConfig, loadAgentConfig, loadConfig } from './specs.js'
 import { compileManifest } from './hooks.js'
-import { writeManagedBlock, removeManagedBlock, type HarnessArtifacts } from './harness.js'
+import { writeManagedBlock, removeManagedBlock, HARNESSES, type HarnessArtifacts } from './harness.js'
 import { git } from './git.js'
 import { runtimeRoot, mainCheckout, readConfig } from './layout.js'
 import { resolveHarnessTargets, partitionHarnesses } from './harness-select.js'
 import { emitPlugin, cleanPlugin, pluginBundleDir, pluginVersion } from './plugin-harness.js'
+import { plantContractFilter, removeContractFilter, settleIndexStat } from './contract-filter.js'
 
 // @@@ materialize - the "pay-per-change" node step (≈0.85s) the cheap shell gate invokes ONLY when the
-// .config content-hash moved. It renders the spec tree's surface nodes into the flat artifacts each
-// consumer reads cheaply, so a USER-self-launched claude/codex (no SpexCode process in the launch) gets the
-// whole system via harness-auto-discovered files: (1) the hook MANIFEST (our dispatcher reads it),
-// (2) the CONTRACT — the tracked docs guide (docs/AGENT_GUIDE.md) FOLLOWED BY the surface:system bodies —
-// written WHOLE into each harness's contract file(s), which are GENERATED, gitignored artifacts (like the
-// shims + skills): regenerated per clone/launch, never committed, so a self-launched agent still discovers
-// guide + contract while the repo tracks only the guide source, (3) the thin SHIMS (every event → dispatch.sh),
-// (4) the per-harness TRUST (Codex's deterministic trusted_hash; Claude none) so the self-launch is zero-prompt.
-// EVERY harness-specific fact is owned by the [[harness-adapter]] (harness.ts) — this file just loops over
-// HARNESSES, so adding a harness adds an adapter, not a branch here. All writes are idempotent + scoped. The
-// content-hash marker is stamped last.
+// content-hash moved. It renders the spec tree's surface nodes into the flat artifacts each consumer reads
+// cheaply, so a USER-self-launched claude/codex (no SpexCode process in the launch) gets the whole system via
+// harness-auto-discovered files: (1) the hook MANIFEST (our dispatcher reads it), (2) the CONTRACT — the
+// tracked docs guide (docs/AGENT_GUIDE.md) FOLLOWED BY the surface:system bodies — written WHOLE into each
+// harness's contract file(s), (3) the thin SHIMS (every event → dispatch.sh), (4) the per-harness TRUST
+// (Codex's deterministic trusted_hash; Claude none). EVERY harness-specific fact is owned by the
+// [[harness-adapter]] (harness.ts) — this file just loops over HARNESSES.
+//
+// THE FORGETTING LAW ([[harness-delivery]]): materialize(P₂) ∘ materialize(P₁) = materialize(P₂) — a render
+// under the current policy fully forgets every prior policy's artifacts; idempotence is the special case
+// P₂ = P₁, and dematerialize (= materialize(∅), what `spex uninstall` builds on) is the empty policy. The
+// implementation is ERASE-THEN-ASSERT over a CLOSED set of landing points: each is first erased
+// unconditionally by its IDENTITY STAMP (sentinel blocks, the shim's dispatch.sh command line, the generated
+// mark on skills/agents, the filter config namespace, the skip-worktree bit), then rewritten per the current
+// policy (possibly to nothing). No ledger of past states, no pairwise migration branches — the erase IS the
+// migration, whatever the previous state was.
 
 const PKG = fileURLToPath(new URL('..', import.meta.url))                 // installed spec-cli root
 const DISPATCH = join(PKG, 'hooks', 'dispatch.sh')
@@ -33,9 +39,11 @@ const SPEX = join(PKG, 'bin', 'spex.mjs')
 // worktree — the worktree keeps zero SpexCode-rendered runtime; only the harness-discovered contract files +
 // shims (which the harness must find in-tree) are written under proj below.
 
-// the deterministic content fingerprint of the config roots. ONE definition — `hp_config_hash` in the shell
-// mirror (harness.sh) — which the dispatch.sh gate ALSO calls, so the gate and this renderer can never disagree
-// on "changed" (they used to inline the identical find-pipeline in two places, each commenting the other "MUST match").
+// the deterministic content fingerprint of the config roots + THE RENDERER ITSELF. ONE definition —
+// `hp_config_hash` in the shell mirror (harness.sh) — which the dispatch.sh gate ALSO calls, so the gate and
+// this renderer can never disagree on "changed". It folds in hp_renderer_version (the toolchain-side content
+// hash), so a TOOLCHAIN update moves the key and the next gate self-heals the rendered artifacts — closing
+// the "toolchain updated but nothing re-materialized" hole ([[harness-delivery]]).
 export function contentHash(proj: string): string {
   try {
     const harnessSh = join(PKG, 'hooks', 'harness.sh')
@@ -43,15 +51,45 @@ export function contentHash(proj: string): string {
   } catch { return '' }
 }
 
-// @@@ private overlay ([[private-overlay]]) - the DEFAULT render commits .spec + spexcode.json and ignores its
-// generated wiring through a managed block in the TRACKED <repo>/.gitignore; that only truly hides a file that
-// is wholly ours, so on a host that ALREADY tracks CLAUDE.md/AGENTS.md/.gitignore the folded-in block still
-// lands in a tracked file and leaks. Private mode (spexcode.local.json `private:true`) closes that: it moves the
-// ignore block to the per-clone `.git/info/exclude` (never committed), widens it to hide .spec + spexcode.json
-// too, and `skip-worktree`s any TRACKED contract file so the block sits in the working copy (the harness still
-// discovers it) yet never stages. Every step has an inverse the DEFAULT mode re-asserts, so the toggle is
-// reversible and idempotent. It hides UNTRACKED paths; a pre-existing tracked .spec must be `git rm --cached`d
-// once (the render can't untrack for you — reported, not silently ignored).
+// @@@ render policy ([[render-policy]]) - ONE share axis, voted only for the machine-independent RENDERS.
+// `.spec` + `spexcode.json` are ALWAYS tracked (git is the database — no knob can untrack them); machine
+// facts (shims, spexcode.local.json) are ALWAYS ignored; run residue (.worktrees/) is always ignored. The
+// vote decides where the renders (contract blocks, skills, agents) sit — and, recursively, where their
+// ignore rules live: `committed` drops the render entries from the ignore block (the renders are ordinary
+// committed files), `ignored` (default) keeps the block in the TRACKED .gitignore, `hidden` moves the whole
+// block to the per-clone .git/info/exclude and covers a HOST-TRACKED contract file with the clean/smudge
+// content filter ([[content-filter]]) instead of the retired skip-worktree bit.
+export type RenderPolicy = 'committed' | 'ignored' | 'hidden'
+export function resolveRenderPolicy(cfg: { render?: string; private?: boolean }, proj?: string): RenderPolicy {
+  const r = cfg.render?.trim()
+  if (r) {
+    if (r !== 'committed' && r !== 'ignored' && r !== 'hidden') {
+      const err = new Error(`invalid render policy '${r}' — the render axis has three words: committed | ignored | hidden (see \`spex guide footprint\`)`)
+      err.name = 'ConfigError'
+      throw err
+    }
+    return r
+  }
+  if (cfg.private) {
+    // LEGACY private:true — the retired untrack-private mode. Its render half maps to 'hidden'; its
+    // data-untrack half is GONE (the spec sources are always tracked now). Loud, non-fatal: the deployment
+    // keeps working while the notice names the two migration moves.
+    let untracked: string[] = []
+    if (proj) untracked = ['.spec', 'spexcode.json'].filter((p) => existsSync(join(proj, p)) && !isTracked(proj, p))
+    console.error(
+      `spexcode: \`private: true\` is retired — reading it as \`"render": "hidden"\`.\n` +
+      `  → migrate spexcode.local.json: replace "private": true with "render": "hidden".` +
+      (untracked.length
+        ? `\n  → your spec sources are still untracked (${untracked.join(' + ')}); the untrack-private mode is gone, so track them once:\n` +
+          `      git add ${untracked.join(' ')}   (then commit on your branch)\n` +
+          `    WARNING: tracking is not retroactive secrecy — history already pushed elsewhere cannot be recalled.`
+        : ''),
+    )
+    return 'hidden'
+  }
+  return 'ignored'
+}
+
 function gitCommonDirOf(proj: string): string {
   return git(['-C', proj, 'rev-parse', '--path-format=absolute', '--git-common-dir']).trim()
 }
@@ -61,11 +99,97 @@ function infoExcludePath(proj: string): string {
 function isTracked(proj: string, file: string): boolean {
   try { git(['-C', proj, 'ls-files', '--error-unmatch', file]); return true } catch { return false }
 }
-// mark/unmark a TRACKED file skip-worktree (a no-op on an untracked path — info/exclude hides those instead).
-// Best-effort: an index race or a non-repo must not fail the render.
-function setSkipWorktree(proj: string, file: string, on: boolean): void {
+
+// @@@ adoption vote hint ([[render-policy]] story 4 + 21) - the one-time decision guidance for the "mystery M"
+// moment: under the DEFAULT policy a host-TRACKED contract file (a team's own CLAUDE.md/AGENTS.md) carries the
+// generated block and shows honestly dirty in status — deliberate, but a first-minute adopter just sees an
+// unexplained modification. So the HUMAN surfaces (spex init + the manual `spex materialize` verb — never the
+// silent gate/bootstrap renders) print this guidance exactly while the vote is still open: only when (a) no
+// explicit `render` is set (the default `ignored` is in effect by omission, not by choice — an explicit vote,
+// any word, retires the hint) and (b) a SELECTED harness's contract file is actually host-tracked. Mechanism,
+// not interaction: plain stdout naming the three words, their consequences, and where the vote lives — init is
+// routinely run by agents, so there is no TUI prompt to hang on.
+export function renderVoteHint(proj = process.cwd()): string | null {
+  const cfg = readConfig(mainCheckout(proj))
+  if (cfg.render?.trim() || cfg.private) return null            // an explicit vote (or the legacy mapping) — decided
+  const { selected } = partitionHarnesses(resolveHarnessTargets(cfg.harnesses))
+  const tracked = selected.flatMap((h) => h.contractFiles(proj)).filter((f) => isTracked(proj, f))
+  if (!tracked.length) return null
+  const names = tracked.map((f) => relative(proj, f)).join(' + ')
+  const [be, carry] = tracked.length > 1 ? ['are', 'carry'] : ['is', 'carries']
+  return [
+    `note: ${names} ${be} tracked by this repo and now ${carry} the generated <!-- spexcode --> block — the`,
+    `modification you see in git status. That dirtiness is HONEST under the current default (render: ignored),`,
+    `kept visible on purpose until you vote where the generated renders should live:`,
+    `  committed   renders become ordinary committed files — teammates/CI get the contract natively`,
+    `  ignored     (current default) renders stay generated+gitignored; a tracked contract file stays dirty`,
+    `  hidden      zero repo footprint — ignore rules live in .git/info/exclude and the tracked file is`,
+    `              covered by the clean/smudge filter (index stays pristine, status clean)`,
+    `Vote once and this note retires: "render": "committed" | "ignored" in spexcode.json (a project fact) or`,
+    `"render": "hidden" in spexcode.local.json (a host fact) — or adopt in one step: spex init --render <word>.`,
+    `Full model: spex guide footprint.`,
+  ].join('\n')
+}
+// clear a legacy skip-worktree bit (the retired private-overlay mechanism; erase-only now — nothing asserts
+// it). Best-effort: an index race or a non-repo must not fail the render.
+function clearSkipWorktree(proj: string, file: string): void {
   if (!isTracked(proj, file)) return
-  try { git(['-C', proj, 'update-index', on ? '--skip-worktree' : '--no-skip-worktree', file]) } catch { /* best-effort */ }
+  try { git(['-C', proj, 'update-index', '--no-skip-worktree', file]) } catch { /* best-effort */ }
+}
+
+// the identity stamp on every generated skill/agent file — what lets the erase phase forget a product whose
+// NODE was renamed or deleted (the name-scoped sweep can only reconstruct paths the LIVE config still names).
+const GENERATED_MARK = '<!-- spexcode:generated -->'
+function sweepGeneratedSkills(dir: string | null): void {
+  if (!dir || !existsSync(dir)) return
+  for (const e of readdirSync(dir, { withFileTypes: true })) {
+    if (!e.isDirectory()) continue
+    const f = join(dir, e.name, 'SKILL.md')
+    try { if (existsSync(f) && readFileSync(f, 'utf8').includes(GENERATED_MARK)) rmSync(join(dir, e.name), { recursive: true, force: true }) } catch { /* unreadable → not provably ours */ }
+  }
+}
+function sweepGeneratedAgents(dir: string | null): void {
+  if (!dir || !existsSync(dir)) return
+  for (const e of readdirSync(dir, { withFileTypes: true })) {
+    if (!e.isFile() || !e.name.endsWith('.md')) continue
+    const f = join(dir, e.name)
+    try { if (readFileSync(f, 'utf8').includes(GENERATED_MARK)) rmSync(f, { force: true }) } catch { /* unreadable → not provably ours */ }
+  }
+}
+
+// @@@ dematerialize - materialize(∅): the ERASE phase, also the whole of a backout ([[spex-uninstall]] adds
+// only the global store + plugin sweep + optional git hooks on top). Every removal is gated on an identity
+// stamp, so it deletes ONLY what a render wrote — never the user's prose, settings, or any .spec data. Order
+// matters once: the managed blocks leave the WORKING contract files before the content filter's config goes
+// (edge ③ in [[content-filter]] — a block outliving its clean filter surfaces as an uncommitted change).
+// `arts` (live skill/agent node names) widens the sweep to pre-stamp legacy files; the GENERATED_MARK sweep
+// covers everything rendered since, including products of renamed/deleted nodes.
+export function dematerialize(proj = process.cwd(), arts: HarnessArtifacts = { skills: [], agents: [] }): void {
+  for (const h of HARNESSES) {
+    // h.clean = the adapter's surgical inverse: contract block (sentinels, deleteIfEmpty), the dispatch.sh-
+    // stamped shim + worktree anchor, the trust block, and the arts-named skill/agent files.
+    h.clean(proj, arts)
+    for (const f of h.contractFiles(proj)) clearSkipWorktree(proj, f)   // legacy private-overlay bit — erase-only
+    sweepGeneratedSkills(h.skillDir(proj))
+    sweepGeneratedAgents(h.agentDir(proj))
+  }
+  // same authorship rule as the contract files: deleteIfEmpty only when .gitignore is UNTRACKED (wholly-ours
+  // generated file); a HOST-TRACKED .gitignore that carried nothing but our block is stripped, never deleted.
+  removeManagedBlock(join(proj, '.gitignore'), ['# ', ''], !isTracked(proj, '.gitignore'))
+  try { removeManagedBlock(infoExcludePath(proj), ['# ', ''], false) } catch { /* not a git repo */ }
+  removeContractFilter(proj)                                            // AFTER the blocks left the working files
+  // the block-strip left tracked contract files stat-dirty (under a filter git NEVER content-verifies them,
+  // and even unfiltered the phantom-`M` lingers) — settle the index stat, content-guarded so a user's real
+  // unstaged edit is never staged ([[content-filter]] edge 2).
+  try { settleIndexStat(proj, HARNESSES.flatMap((h) => h.contractFiles(proj))) } catch { /* not a git repo */ }
+  // leaving nothing behind: drop the now-EMPTY dirs the assert phase mkdir'ed (.claude/.codex and their
+  // skills/agents subdirs — children listed before parents). rmdirSync is NON-recursive, so a dir holding
+  // any user file survives untouched; `.git/spexcode/` is deliberately NOT swept (shared per-clone home).
+  for (const h of HARNESSES) {
+    const anchor = h.worktreeHookAnchor(proj)
+    for (const d of [h.skillDir(proj), h.agentDir(proj), dirname(h.shimFile(proj)), anchor ? dirname(anchor) : null])
+      if (d) { try { rmdirSync(d) } catch { /* non-empty or absent — keep */ } }
+  }
 }
 
 // the whole pay-per-change render. proj defaults to cwd. Returns the new content-hash it stamped.
@@ -77,93 +201,85 @@ export function materialize(proj = process.cwd()): string {
   // (2) the contract = the tracked docs guide (the hand-written agent/contributor notes — the ONE piece of
   //     in-tree prose) FOLLOWED BY the surface:system bodies (in name order), written WHOLE into EACH harness's
   //     contract file(s) + (3) each harness's thin shim → dispatch.sh + (4) its trust. All owned by the adapter.
-  //     The contract files are generated artifacts (gitignored below), so the guide is the single source a
-  //     self-launched agent reads from — assembling it in keeps guide + contract reaching the agent together.
   const guidePath = join(proj, 'docs', 'AGENT_GUIDE.md')
   const guide = existsSync(guidePath) ? readFileSync(guidePath, 'utf8').trim() : ''
   const systemBodies = loadSystemConfig().map((c) => c.body.trim()).filter(Boolean)
   const contract = [guide, ...systemBodies].filter(Boolean).join('\n\n')
   // WHICH harnesses to deliver into ([[harness-select]]): the spexcode.json `harnesses` set (default = every
   // native harness). resolveHarnessTargets FAILS LOUD on an illegal set (plugin+native, plugin w/o folder).
-  // selected harnesses are write()n below; unselected ones are clean()ed (pruned) after — so dropping a harness
-  // from the config removes its products on the next re-materialize. The plugin EMITTER is a later node.
   const cfg = readConfig(mainCheckout(proj))
   const targets = resolveHarnessTargets(cfg.harnesses)
-  const priv = !!cfg.private                                              // [[private-overlay]] — hide in .git/info/exclude + skip-worktree, not the tracked .gitignore
-  const { selected, unselected, plugins } = partitionHarnesses(targets)
+  const policy = resolveRenderPolicy(cfg, proj)                           // [[render-policy]] — committed | ignored | hidden
+  const { selected, plugins } = partitionHarnesses(targets)
   const skillNodes = loadSkillConfig()
   const agentNodes = loadAgentConfig()
   const commandNodes = loadConfig()
+  const arts: HarnessArtifacts = { skills: skillNodes.map((s) => s.name), agents: agentNodes.map((a) => a.name) }
+
+  // ---- ERASE (the forgetting law): every landing point cleared by identity stamp, whatever policy — or
+  // legacy mode — wrote it last. Unselected harnesses need no separate prune branch: the erase already
+  // forgot them, and only the selected ones are asserted below.
+  dematerialize(proj, arts)
+
+  // ---- ASSERT: rewrite each landing point per the CURRENT policy.
   // a skill node → the agentskills.io SKILL.md primitive: `name`+`description` frontmatter (the load-trigger)
-  // over the body instructions. One pure render shared by every harness — divergence is only its skillDir.
+  // over the body instructions, closed by the GENERATED_MARK identity stamp (what the erase phase keys on).
+  // One pure render shared by every harness — divergence is only its skillDir.
   const renderSkill = (sk: { name: string; desc: string; body: string }) =>
-    `---\nname: ${sk.name}\ndescription: ${JSON.stringify(sk.desc)}\n---\n\n${sk.body}\n`
+    `---\nname: ${sk.name}\ndescription: ${JSON.stringify(sk.desc)}\n---\n\n${sk.body}\n\n${GENERATED_MARK}\n`
   // an agent node → a coding-agent sub-agent definition (the same primitive .claude/agents/*.md ships): the
   // node's `desc` is the on-demand load-trigger, its `tools` the harness tool allowlist, its body the agent's
-  // system prompt. One pure render shared by every harness — divergence is only its agentDir.
+  // system prompt. Same stamp, same reason.
   const renderAgent = (ag: { name: string; desc: string; tools: string[]; body: string }) =>
-    `---\nname: ${ag.name}\ndescription: ${ag.desc}\ntools: ${ag.tools.join(', ')}\n---\n\n${ag.body}\n`
-  // a command node → a host `/`-menu command file: the node's `desc` as the dropdown description over its body
-  // (the preset prompt). Only the PLUGIN bundle ships these as files; the native path serves command presets via
-  // the dashboard /api/slash-commands instead, so this render is plugin-only.
+    `---\nname: ${ag.name}\ndescription: ${ag.desc}\ntools: ${ag.tools.join(', ')}\n---\n\n${ag.body}\n\n${GENERATED_MARK}\n`
+  // a command node → a host `/`-menu command file: plugin-only (the native path serves command presets via
+  // the dashboard /api/slash-commands instead).
   const renderCommand = (cm: { desc: string; body: string }) =>
     (cm.desc ? `---\ndescription: ${JSON.stringify(cm.desc)}\n---\n\n` : '') + `${cm.body}\n`
-  // shim ABSOLUTE paths; relativized into the managed .gitignore block below (checkout-invariant — see there).
-  const shimPaths: string[] = []
+  // two ignore classes, split because only `committed` treats them differently: RENDERS are machine-
+  // independent products the team may choose to commit; MACHINE paths (shims bake this install's abs path,
+  // bundles too) are never committable under any policy.
+  const renderPaths: string[] = []
+  const machinePaths: string[] = []
   for (const h of selected) {
-    if (contract) for (const f of h.contractFiles(proj)) { writeManagedBlock(f, contract); shimPaths.push(f); setSkipWorktree(proj, f, priv) }
+    if (contract) for (const f of h.contractFiles(proj)) { writeManagedBlock(f, contract); renderPaths.push(f) }
     const shimFile = h.shimFile(proj)
     mkdirSync(dirname(shimFile), { recursive: true })
     const shim = h.shim(DISPATCH, SPEX)
     writeFileSync(shimFile, shim.json)
     h.writeTrust(proj, shim.cmd)
-    shimPaths.push(shimFile)
+    machinePaths.push(shimFile)
     // a linked-worktree ANCHOR copy of the shim, when the harness needs one (codex: the shim lives at the main
-    // checkout, so the worktree gets no `.codex/` unless we place one — and codex only discovers a worktree
-    // thread's hooks if a `.codex/` under the worktree root anchors the project layer). One adapter line; null
-    // for a harness whose shim already sits in the worktree (claude) or on the main checkout itself.
+    // checkout, so the worktree gets no `.codex/` unless we place one). One adapter line; null otherwise.
     const anchor = h.worktreeHookAnchor(proj)
-    if (anchor) { mkdirSync(dirname(anchor), { recursive: true }); writeFileSync(anchor, shim.json); shimPaths.push(anchor) }
+    if (anchor) { mkdirSync(dirname(anchor), { recursive: true }); writeFileSync(anchor, shim.json); machinePaths.push(anchor) }
   }
-  // (6) skills - each `surface: skill` node → a SKILL.md the harness auto-discovers, written into every
-  //     harness's own skillDir (Claude .claude/skills, Codex .codex/skills). Generated wiring, so the paths
-  //     join the same managed .gitignore block below. A harness with no skill primitive (skillDir null) is skipped.
+  // (6) skills + (7) sub-agents — each surface node → the file the harness auto-discovers, one per selected
+  //     harness that has the primitive (skillDir/agentDir null skips — the divergence is the adapter's line).
   for (const sk of skillNodes) {
     for (const h of selected) {
       const dir = h.skillDir(proj); if (!dir) continue
       const f = join(dir, sk.name, 'SKILL.md')
       mkdirSync(dirname(f), { recursive: true })
       writeFileSync(f, renderSkill(sk))
-      shimPaths.push(f)   // reuse the same managed .gitignore block (absolute; relativized below)
+      renderPaths.push(f)
     }
   }
-  // (7) sub-agents - each `surface: agent` node → a <name>.md the harness auto-discovers, written into every
-  //     harness's own agentDir (Claude .claude/agents). The SAME pattern as skills: generated wiring, so the
-  //     paths join the same managed .gitignore block below. A harness with no agent primitive (agentDir null,
-  //     e.g. Codex) is skipped — no `if (codex)`, the divergence is the adapter's agentDir line.
   for (const ag of agentNodes) {
     for (const h of selected) {
       const dir = h.agentDir(proj); if (!dir) continue
       const f = join(dir, `${ag.name}.md`)
       mkdirSync(dirname(f), { recursive: true })
       writeFileSync(f, renderAgent(ag))
-      shimPaths.push(f)   // reuse the same managed .gitignore block (absolute; relativized below)
+      renderPaths.push(f)
     }
   }
-  // (8) PRUNE every UNSELECTED harness — clean() is the surgical inverse of the write above, removing ONLY this
-  //     harness's own managed block + generated shim + trust + named skill/agent files. So narrowing the
-  //     spexcode.json `harnesses` set (or switching to a plugin, which excludes all natives) removes the
-  //     dropped harness's products here, the user's own prose/data untouched. The names tell clean exactly
-  //     which on-demand artifacts were its to remove ([[harness-select]] / [[harness-adapter]]).
-  const arts: HarnessArtifacts = { skills: skillNodes.map((s) => s.name), agents: agentNodes.map((a) => a.name) }
-  for (const h of unselected) h.clean(proj, arts)
-  // (8b) the PLUGIN target ([[plugin-harness]]): render the whole system into one self-contained Claude-plugin
-  //      bundle per selected folder. A plugin is EXCLUSIVE (so `selected` is already empty — every native was
-  //      pruned above). Pruning a DESELECTED plugin folder (plugin→native, or folder A→B) needs the PREVIOUS
-  //      folder set, which the live config no longer names — so a tiny ledger in the global store records the
-  //      folders emitted last run; any prev folder absent from the current set is clean()ed (the bundle's
-  //      inverse), then the current folders are emitted and the ledger rewritten. Bounded + surgical: cleanPlugin
-  //      is identity-gated on the bundle's own plugin.json.
+  // (8) the PLUGIN target ([[plugin-harness]]): render the whole system into one self-contained Claude-plugin
+  //     bundle per selected folder. A plugin is EXCLUSIVE (`selected` is empty then). Pruning a DESELECTED
+  //     folder needs the PREVIOUS folder set, which the live config no longer names — the one landing point
+  //     the identity-stamped erase cannot enumerate (a folder is an arbitrary path) — so a tiny ledger in the
+  //     global store records the folders emitted last run; any prev folder absent from the current set is
+  //     clean()ed, then the current folders are emitted and the ledger rewritten.
   const ledger = join(rt, 'plugin-folders')
   const prevFolders = existsSync(ledger) ? readFileSync(ledger, 'utf8').split('\n').map((l) => l.trim()).filter(Boolean) : []
   const curFolders = plugins.map((p) => p.folder)
@@ -180,65 +296,43 @@ export function materialize(proj = process.cwd()): string {
     for (const p of plugins) emitPlugin(proj, p.folder, render)
   }
   writeFileSync(ledger, curFolders.join('\n'))
-  // (4b) every artifact this render writes IN-TREE is generated wiring, so gitignore it — regenerated per
-  // clone/launch by this same gate, never committed. That now includes the CONTRACT files (CLAUDE.md/AGENTS.md):
-  // their whole content is the generated guide+system block, so they are artifacts exactly like the shims +
-  // skills + sub-agents — the only tracked prose is the guide SOURCE (docs/AGENT_GUIDE.md), which this render
-  // reads. Derived from the adapters' own contractFiles()/shimFile()/skillDir/agentDir, not hardcoded; written
-  // as a managed `#` block so the user's own .gitignore is preserved.
-  // The managed block must be CHECKOUT-INVARIANT: `.gitignore` is ONE tracked, committed file shared by the
-  // main checkout and every worktree, so if the block differed by where materialize ran, whichever flavor got
-  // committed would leave the OTHER checkout dirtying it on every render. The only artifact that varies is the
-  // codex hooks shim, which materializes at the MAIN checkout (a linked worktree's codex reads the root's
-  // hooks — see harness.ts): from main it is `.codex/hooks.json` (inside proj), from a worktree it is `../…`
-  // (escapes proj). So an ignore entry is anchored to the checkout it LIVES under — proj-relative when inside
-  // proj, else MAIN-checkout-relative — which resolves the codex shim to `.codex/hooks.json` from any checkout
-  // (a pattern naming a main-only path is a harmless no-op in a worktree). Every checkout now emits the same
-  // set → the committed `.gitignore` is stable, never re-dirtied. A path under neither root is not ignorable
-  // here (dropped).
+  // (9) the ignore rules — themselves an artifact whose HOME the same axis decides ([[render-policy]]):
+  //     committed/ignored → a managed `#` block in the TRACKED .gitignore (the team sees the rule);
+  //     hidden → the identical block in the per-clone .git/info/exclude (zero repo footprint).
+  // Entries must be CHECKOUT-INVARIANT: `.gitignore` is ONE tracked file shared by the main checkout and
+  // every worktree, so each entry is anchored to the checkout it LIVES under — proj-relative when inside
+  // proj, else MAIN-checkout-relative (the codex shim resolves to `.codex/hooks.json` from any checkout; a
+  // pattern naming a main-only path is a harmless no-op in a worktree). A path under neither root is dropped.
   const mc = mainCheckout(proj)
   const anchor = (abs: string): string | null => {
     const p = relative(proj, abs); if (!p.startsWith('..')) return p
     const m = relative(mc, abs); if (!m.startsWith('..')) return m
     return null
   }
-  // spexcode.local.json — the machine-local config overlay (host-specific values, e.g. an absolute worker
-  // launcher path; see portable-layout) — joins the SAME block on the same rationale: machine-specific, must
-  // never be committed. Without it an adopter who follows our own guidance to put a host path there would
-  // `git add -A` and leak it — the exact thing the overlay exists to prevent.
-  // each emitted plugin bundle is a generated, machine-local artifact too (its hooks.json bakes THIS install's
-  // SPEX path), so its dir joins the same managed block — regenerated per clone/launch, never committed.
+  // machine facts + run residue, ignored under EVERY policy: the shims/anchors/bundles (bake this install's
+  // abs path), spexcode.local.json (the host overlay — a `git add -A` must never leak it), and the session
+  // residue (`.worktrees/` where launches plant worktrees; `.session` is the legacy per-worktree state file
+  // an old backend wrote). Static strings stay checkout-invariant.
   const bundlePaths = curFolders.map((f) => pluginBundleDir(proj, f))
-  // SpexCode's own SESSION artifacts also join the managed block: a launch creates a worktree under
-  // `.worktrees/` (hardcoded in sessions.ts) plus a per-worktree `.session` state file the layout linker
-  // reads. Neither is the adopter's code, both are per-clone/never-committed — but until now materialize
-  // never ignored them, so an ADOPTED project leaked its session worktrees into `git status` (a `git add -A`
-  // would commit them). Static strings, so they stay checkout-invariant. The dogfood hand-lists these; every
-  // other repo gets them here, in the default `.gitignore` block AND (widened) the private `.git/info/exclude`.
-  const sessionIgnores = ['.worktrees/', '.session']
-  const ignorable = [...[...shimPaths, ...bundlePaths].map(anchor).filter((p): p is string => p !== null), 'spexcode.local.json', ...sessionIgnores]
-  const gitignore = join(proj, '.gitignore')
-  if (priv) {
-    // PRIVATE ([[private-overlay]]): hide EVERYTHING — including the .spec tree + spexcode.json the DEFAULT
-    // mode commits ("git is the database") — in the per-clone `.git/info/exclude` (never committed, never
-    // shared), and strip any managed block a prior DEFAULT render left in the tracked .gitignore so switching
-    // INTO private mode leaves the host's shared history clean.
-    const entries = [...new Set([...ignorable, '.spec/', 'spexcode.json'])].sort().join('\n')
-    writeManagedBlock(infoExcludePath(proj), entries, ['# ', ''])
-    removeManagedBlock(gitignore, ['# ', ''], true)
-    // the ONE manual step private mode can't do for you: .git/info/exclude hides UNTRACKED paths only, so a
-    // .spec/spexcode.json ALREADY committed (a repo that adopted DEFAULT mode first) stays visible until
-    // un-tracked. Surface it loudly rather than leaving a silent leak — the agent doing setup acts on this.
-    const stillTracked = ['.spec', 'spexcode.json'].filter((p) => isTracked(proj, p))
-    if (stillTracked.length) console.error(
-      `spexcode private: ${stillTracked.join(' + ')} still git-tracked — private mode hides UNTRACKED paths only.\n` +
-      `  → run once:  git rm -r --cached ${stillTracked.join(' ')}   (keeps the files on disk, stops tracking them; then commit on your branch)`,
-    )
+  const machineEntries = [
+    ...[...machinePaths, ...bundlePaths].map(anchor).filter((p): p is string => p !== null),
+    'spexcode.local.json', '.worktrees/', '.session',
+  ]
+  const renderEntries = renderPaths.map(anchor).filter((p): p is string => p !== null)
+  const entries = (list: string[]) => [...new Set(list)].sort().join('\n')
+  if (policy === 'hidden') {
+    writeManagedBlock(infoExcludePath(proj), entries([...machineEntries, ...renderEntries]), ['# ', ''])
+    // a HOST-TRACKED contract file cannot be ignored — cover it with the clean/smudge content filter
+    // ([[content-filter]]) so the block lives in the working tree while the index keeps the pristine prose.
+    // Untracked contract files are wholly ours: generate + exclude suffices, no filter (weakest tool).
+    const trackedContracts = selected
+      .flatMap((h) => h.contractFiles(proj))
+      .filter((f) => contract && isTracked(proj, f))
+    if (trackedContracts.length) plantContractFilter(proj, trackedContracts, contract)
   } else {
-    // DEFAULT: the checkout-invariant managed block in the TRACKED .gitignore (rationale above); strip any
-    // private exclude block so switching OUT of private mode is equally clean.
-    if (ignorable.length) writeManagedBlock(gitignore, [...new Set(ignorable)].sort().join('\n'), ['# ', ''])
-    removeManagedBlock(infoExcludePath(proj), ['# ', ''], false)
+    // committed: the renders become ordinary committed files — ONLY their entries leave the block.
+    const list = policy === 'committed' ? machineEntries : [...machineEntries, ...renderEntries]
+    if (list.length) writeManagedBlock(join(proj, '.gitignore'), entries(list), ['# ', ''])
   }
   // (5) stamp the content-hash marker LAST (so a crash mid-render leaves it stale → re-renders next gate).
   const h = contentHash(proj)

package/spec-cli/src/ranker.ts

@@ -5,7 +5,7 @@
 // is why they sit in flat plateaus rather than being fitted to any case.
 const W_NAME_PREFIX = 8
 const W_NAME_SUBSTR = 5
-const W_DESC = 3
+const W_DESC = 2
 const W_BODY = 1
 
 // a tiny stoplist of question scaffolding + length-1 tokens, dropped so "how does the … is it …" can't drown
@@ -19,19 +19,34 @@ const STOP = new Set([
   'be', 'can', 'just', 'them', 'they', 'their', 'so', 'if', 'not', 'no', 'but', 'vs', 'us', 'we', 'you',
 ])
 
-// split on non-alphanumeric, lowercase, drop stopwords + length-1 tokens, de-dup.
+// The corpus is mostly English but not only — some nodes carry CJK prose (the root spexcode node is a whole
+// Chinese paragraph), and the dashboard palette ([[shared-ranker]]) ranks session/issue titles that are
+// frequently Chinese. CJK has no spaces, so a whitespace/`[^a-z0-9]` split silently discards ALL of it. We
+// tokenize the SAME way on both sides: an ASCII alphanumeric run is one token; each CJK character is its own
+// token (a unigram). Unigrams — not bigrams — keep the shared prefix-match/IDF/BM25 machinery untouched (a
+// single-char query still matches, no bigram edge cases) and stay BLUNT & ROBUST, the floor's whole stance.
+// Han (incl. Ext-A + compat) plus Japanese kana; enough to cover the CJK a spec body or a session title carries.
+const CJK = '\\u3400-\\u4dbf\\u4e00-\\u9fff\\uf900-\\ufaff\\u3040-\\u30ff' // Ext-A · Unified · Compat · kana
+const TOKEN_RE = new RegExp(`[a-z0-9]+|[${CJK}]`, 'g')
+const CJK_RE = new RegExp(`[${CJK}]`)
+function isCjk(t: string): boolean { return CJK_RE.test(t) }
+function tokenize(text: string): string[] {
+  return text.toLowerCase().match(TOKEN_RE) ?? []
+}
+
+// tokenize, lowercase, drop stopwords + length-1 ASCII tokens (a length-1 CJK token is a real word — keep it), de-dup.
 export function terms(query: string): string[] {
   const seen = new Set<string>()
-  for (const w of query.toLowerCase().split(/[^a-z0-9]+/)) {
-    if (w.length > 1 && !STOP.has(w)) seen.add(w)
+  for (const w of tokenize(query)) {
+    if (isCjk(w) || (w.length > 1 && !STOP.has(w))) seen.add(w)
   }
   return [...seen]
 }
 
 // the words of a field, lowercased — used for word-boundary (prefix-of-a-word) matching, which kills
-// short-token pollution (`main` must not match inside `domain`).
+// short-token pollution (`main` must not match inside `domain`); CJK chars are single-char words.
 function words(text: string): string[] {
-  return text.toLowerCase().split(/[^a-z0-9]+/).filter(Boolean)
+  return tokenize(text)
 }
 
 // light query-side stem for prefix matching: drop a trailing plural 's' (len≥4, not 'ss') then a mute 'e'
@@ -87,8 +102,10 @@ function snippetFor(text: string, desc: string, qterms: string[], window = 140):
   const lower = flat.toLowerCase()
   let at = -1
   for (const t of qterms) {
-    const m = lower.match(new RegExp('\\b' + t.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')))
-    if (m && m.index !== undefined && (at < 0 || m.index < at)) at = m.index
+    // ASCII terms locate at a word boundary (so `main` doesn't hit inside `domain`); a CJK term has no
+    // `\b` around it (JS `\b` is ASCII-only), so locate it by plain substring.
+    const i = isCjk(t) ? lower.indexOf(t) : lower.search(new RegExp('\\b' + t.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')))
+    if (i >= 0 && (at < 0 || i < at)) at = i
   }
   if (at < 0) {
     const fb = (desc || flat).replace(/\s+/g, ' ').trim()

package/spec-cli/src/runtime-guard.ts

@@ -0,0 +1,44 @@
+import { spawnSync } from 'node:child_process'
+
+// @@@ session-runtime guard ([[platform-support]]) - SpexCode's session orchestration rests on POSIX
+// primitives with no native-Windows analog: tmux (the durable detached PTY + capture-pane scrollback +
+// multi-client reattach fabric), hand-written bash launch scripts, and filesystem-path AF_UNIX control
+// sockets. The supported runtime is POSIX — Linux, macOS, or Windows *via WSL2* (a real Linux kernel where
+// tmux/bash/unix-sockets all work). This is the honest gate at the entry to the session runtime: detect the
+// load-bearing primitive (tmux) missing and print ONE actionable line naming the fix, instead of letting a
+// cryptic downstream ENOENT be the user's first signal. Read-only CLI (init/lint/board) never calls this,
+// so it still runs anywhere the launcher does — only the session-launch path (`spex serve`) is gated.
+
+// tmux presence is the primitive we actually depend on, so probe THAT rather than assuming by platform:
+// this also catches a bare POSIX box that simply hasn't installed tmux, not only native Windows.
+export function hasTmux(): boolean {
+  try {
+    return spawnSync('tmux', ['-V'], { stdio: 'ignore' }).status === 0
+  } catch {
+    return false
+  }
+}
+
+// Pure so it is unit-testable without spawning or exiting: null = runtime OK; otherwise the stderr lines.
+// The pointer branches on platform because the honest repair differs — WSL2 on Windows (no POSIX analog at
+// all), install-tmux on a POSIX host that merely lacks it.
+export function sessionRuntimeBlock(env: { hasTmux: boolean; platform: string }): string[] | null {
+  if (env.hasTmux) return null
+  const lines = ['spex: the session runtime needs a POSIX host (tmux, bash, and unix-domain sockets).']
+  if (env.platform === 'win32') {
+    lines.push('Native Windows has no analog for these — run SpexCode under WSL2 (a real Linux kernel):')
+    lines.push('  wsl --install   # then, in the Ubuntu shell: nvm install 22 && npm i -g spexcode')
+  } else {
+    lines.push('tmux is not on PATH — install it and retry (e.g. `apt install tmux`, `brew install tmux`).')
+  }
+  return lines
+}
+
+// Called at the top of the session-launching command path (`spex serve`). Exits 69 (EX_UNAVAILABLE: a
+// required support program does not exist) — a distinct, honest code, not a swallowed error or a stacktrace.
+export function assertSessionRuntime(): void {
+  const block = sessionRuntimeBlock({ hasTmux: hasTmux(), platform: process.platform })
+  if (!block) return
+  for (const line of block) console.error(line)
+  process.exit(69)
+}