spexcode 0.2.4 → 0.2.6

package/spec-cli/src/materialize.ts

@@ -1,27 +1,35 @@
-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 { runtimeRoot, treeSlotDir, 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.
+// @@@ materialize - the materialize step (≈0.85s), anchored on GIT-NATIVE events only ([[commit-surgery]]):
+// spex verbs (init/materialize), session-worktree creation, and the planted git hooks (pre-commit,
+// post-checkout, post-merge) — never a harness event; the harness is a READER of the materialized files, not
+// a trigger. It turns 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₂) — one pass
+// 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')
@@ -29,13 +37,17 @@ const DISPATCH = join(PKG, 'hooks', 'dispatch.sh')
 // resolution AND the mid-merge guard (a conflicted source tree degrades to one line + exit 75, not an
 // esbuild stacktrace), so every hook-baked callback inherits both.
 const SPEX = join(PKG, 'bin', 'spex.mjs')
-// the manifest + content-hash marker render into the GLOBAL per-project store (layout.runtimeRoot), NOT the
-// 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 manifest + content-hash marker + plugin-folder ledger land in the materialized TREE's own slot of the
+// GLOBAL per-project store (layout.treeSlotDir — trees/<enc-worktree>), NOT the worktree and NOT one shared
+// per-project file: each is a pure function of ONE tree's .config, and the old single slot let the last-
+// materialized tree's hook set reach every other tree's dispatch ([[hook-dispatch]]). The worktree keeps
+// zero SpexCode-materialized 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 TOOLCHAIN ITSELF (`hp_config_hash` in the
+// shell mirror, harness.sh). Stamped as a freshness record after every materialize; it folds in
+// hp_toolchain_version (the toolchain-side content hash), so a stale stamp is diagnosable after a toolchain
+// update ([[harness-delivery]]).
 export function contentHash(proj: string): string {
   try {
     const harnessSh = join(PKG, 'hooks', 'harness.sh')
@@ -43,15 +55,25 @@ 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).
+// @@@ footprint kinds ([[residence]]) - the vote axis is RETIRED: materialized artifacts carry no facts, so
+// they are NEVER tracked — there is exactly ONE residence behavior, not three. `.spec` + `spexcode.json` are ALWAYS
+// tracked (git is the database — no knob can untrack them); machine facts (shims, spexcode.local.json),
+// run residue (.worktrees/), and wholly-ours artifacts are hidden by the per-clone .git/info/exclude (the
+// host's tracked .gitignore is never touched); a contract file the host TRACKS — or one the user has begun
+// writing THEIR OWN prose into — is covered by the clean/smudge content filter ([[content-filter]]). An
+// environment without the generator (a teammate's clone, CI, a cloud agent) runs `spex materialize` in its
+// setup step — there is no committed-artifact delivery mode.
+export function retiredAxisNotice(cfg: { render?: string; private?: boolean }): void {
+  if (!cfg.render?.trim() && !cfg.private) return
+  const field = cfg.render?.trim() ? `"render": "${cfg.render.trim()}"` : '"private": true'
+  console.error(
+    `spexcode: the render vote is retired — ${field} is ignored. Materialized artifacts are never tracked:\n` +
+    `  ignore rules live in the per-clone .git/info/exclude, a host-tracked contract file is covered by the\n` +
+    `  clean/smudge filter, and a clone without spex runs \`spex materialize\` in its setup step. Remove the\n` +
+    `  field from spexcode.json / spexcode.local.json to retire this notice (see \`spex guide footprint\`).`,
+  )
+}
+
 function gitCommonDirOf(proj: string): string {
   return git(['-C', proj, 'rev-parse', '--path-format=absolute', '--git-common-dir']).trim()
 }
@@ -61,186 +83,234 @@ 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 {
+
+// @@@ contract kind detection ([[residence]]) - a contract file's residence is a LIVE CONTENT FACT, not
+// an install-time choice, re-judged on every materialize: TRACKED → filter domain; untracked + wholly ours
+// (nothing left after stripping our sentinel block) → exclude domain; untracked + HOST CONTENT present (the
+// user began writing their own prose into it) → neither hidden nor tracked-for-them: the exclude entry is
+// withheld (hiding user content would make their prose invisible to git — data-loss shaped) and the clean
+// filter is pre-armed so their eventual, entirely-their-own `git add` strips our block automatically.
+const SENTINEL_RE = /\n*<!-- spexcode:start -->[\s\S]*?<!-- spexcode:end -->\n*/
+export function stripSpexcodeBlock(text: string): string {
+  const m = SENTINEL_RE.exec(text)
+  if (!m) return text
+  // mirror removeManagedBlock exactly: our block + its surrounding blanks collapse to one '\n', and only a
+  // block sitting at the TOP of the file drops the leading newline (a host file beginning with its own
+  // blank lines keeps them — clean(smudge(x)) == x).
+  const replaced = text.replace(SENTINEL_RE, '\n')
+  return m.index === 0 ? replaced.replace(/^\n+/, '') : replaced
+}
+function hostContentOf(file: string): string {
+  if (!existsSync(file)) return ''
+  return stripSpexcodeBlock(readFileSync(file, 'utf8'))
+}
+// 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 materialize.
+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).
+export 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 */ }
+  }
 }
 
-// the whole pay-per-change render. proj defaults to cwd. Returns the new content-hash it stamped.
+// @@@ 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 materialize 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 materialized 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 materialize. proj defaults to cwd. Returns the new content-hash it stamped.
 export function materialize(proj = process.cwd()): string {
-  const rt = runtimeRoot(proj)                                            // global per-project store, not the worktree
+  const rt = treeSlotDir(proj)                                            // this tree's slot in the global store, not the worktree
   mkdirSync(rt, { recursive: true })
   // (1) hook manifest (persistent — the dispatcher reads it; regenerated only here, on change).
   writeFileSync(join(rt, 'hooks-manifest'), compileManifest())
   // (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)
+  retiredAxisNotice(cfg)                                                  // [[residence]] — the vote axis is retired
+  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.
-  const renderSkill = (sk: { name: string; desc: string; body: string }) =>
-    `---\nname: ${sk.name}\ndescription: ${JSON.stringify(sk.desc)}\n---\n\n${sk.body}\n`
+  // over the body instructions, closed by the GENERATED_MARK identity stamp (what the erase phase keys on).
+  // One pure artifact builder shared by every harness — divergence is only its skillDir.
+  const skillArtifact = (sk: { name: string; desc: string; body: string }) =>
+    `---\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.
-  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.
-  const renderCommand = (cm: { desc: string; body: string }) =>
+  // system prompt. Same stamp, same reason.
+  const agentArtifact = (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\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 commandArtifact = (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[] = []
+  // materialized artifacts and machine facts both land in the same per-clone exclude; contract files are kept separate
+  // because their residence is the live three-state kind detection below, not a static entry.
+  const artifactPaths: string[] = []
+  const machinePaths: string[] = []
+  const contractPaths: 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); contractPaths.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)
+      writeFileSync(f, skillArtifact(sk))
+      artifactPaths.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)
+      writeFileSync(f, agentArtifact(ag))
+      artifactPaths.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]]): materialize 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) : []
+  // migration: a tree last materialized pre-slot left its ledger as the project-global file — read it once as
+  // the prev set so a deselected folder is still pruned; every write lands in the slot from here on.
+  const legacyLedger = join(runtimeRoot(proj), 'plugin-folders')
+  const ledgerSrc = existsSync(ledger) ? ledger : legacyLedger
+  const prevFolders = existsSync(ledgerSrc) ? readFileSync(ledgerSrc, 'utf8').split('\n').map((l) => l.trim()).filter(Boolean) : []
   const curFolders = plugins.map((p) => p.folder)
   for (const f of prevFolders) if (!curFolders.includes(f)) cleanPlugin(proj, f)
   if (plugins.length) {
-    const render = {
+    const bundle = {
       contract,
-      skills: skillNodes.map((s) => ({ name: s.name, content: renderSkill(s) })),
-      agents: agentNodes.map((a) => ({ name: a.name, content: renderAgent(a) })),
-      commands: commandNodes.map((c) => ({ name: c.name, content: renderCommand(c) })),
+      skills: skillNodes.map((s) => ({ name: s.name, content: skillArtifact(s) })),
+      agents: agentNodes.map((a) => ({ name: a.name, content: agentArtifact(a) })),
+      commands: commandNodes.map((c) => ({ name: c.name, content: commandArtifact(c) })),
       spex: SPEX,
       version: pluginVersion(),
     }
-    for (const p of plugins) emitPlugin(proj, p.folder, render)
+    for (const p of plugins) emitPlugin(proj, p.folder, bundle)
   }
   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 — ALWAYS the per-clone .git/info/exclude ([[residence]]): the exclude is not a
+  //     history guard (the pre-commit surgery owns history — [[commit-surgery]]) but the ignored-bit
+  //     DECLARATION every other git door consults (checkout may overwrite, clean -fd spares, status/add -A/
+  //     stash stay silent). The host's tracked .gitignore is never touched.
+  // Entries must be CHECKOUT-INVARIANT: the exclude lives in the COMMON git dir 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)`,
-    )
-  } 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)
+  const machineEntries = [
+    ...[...machinePaths, ...bundlePaths].map(anchor).filter((p): p is string => p !== null),
+    'spexcode.local.json', '.worktrees/', '.session',
+  ]
+  // the contract three-state ([[residence]]): tracked → filter; untracked+wholly-ours → exclude;
+  // untracked+host-content → NO exclude (never hide user prose) + the clean filter pre-armed, so the user's
+  // own eventual `git add` strips our block — tracking stays entirely their act.
+  const filterContracts: string[] = []
+  const oursContracts: string[] = []
+  for (const f of contractPaths) {
+    if (isTracked(proj, f) || hostContentOf(f).trim()) filterContracts.push(f)
+    else oursContracts.push(f)
   }
-  // (5) stamp the content-hash marker LAST (so a crash mid-render leaves it stale → re-renders next gate).
+  if (contract && filterContracts.length) plantContractFilter(proj, filterContracts, contract)
+  const artifactEntries = [...artifactPaths, ...oursContracts].map(anchor).filter((p): p is string => p !== null)
+  const entries = (list: string[]) => [...new Set(list)].sort().join('\n')
+  writeManagedBlock(infoExcludePath(proj), entries([...machineEntries, ...artifactEntries]), ['# ', ''])
+  // (5) stamp the content-hash marker LAST (a diagnostic freshness record; a crash mid-materialize leaves it stale).
   const h = contentHash(proj)
   writeFileSync(join(rt, 'content-hash'), h)
   return h

package/spec-cli/src/mentions.ts

@@ -6,9 +6,11 @@
 // separate, and sessions.ts is imported LAZILY so a mention-free post pays nothing.
 
 // ── parse (pure) ──────────────────────────────────────────────────────────────────────────────────────
-// `@<token>` at a word boundary is an actor; `[[<id>]]` is a topic. Tokens are [A-Za-z0-9_-]; a session id,
-// a short label/prefix, or the literal `new`. Both forms are deduped in first-seen order.
-const ACTOR_RE = /(?:^|\s)@([A-Za-z0-9_-]+)/g
+// `@<token>` at a word boundary is an actor; `[[<id>]]` is a topic. Token chars are any unicode
+// letter/number plus [_-] (a CJK session handle or node id is first-class — same charset the launch-side
+// MENTION and the dashboard's MENTION_RE use); a session id, a short label/prefix, or the literal `new`.
+// Both forms are deduped in first-seen order.
+const ACTOR_RE = /(?:^|\s)@([\p{L}\p{N}_-]+)/gu
 const NODE_RE = /\[\[([^\]\s]+)\]\]/g
 
 const uniq = (xs: string[]): string[] => [...new Set(xs)]

package/spec-cli/src/plugin-harness.ts

@@ -2,7 +2,7 @@ import { writeFileSync, mkdirSync, readFileSync, existsSync, rmSync, copyFileSyn
 import { join, dirname } from 'node:path'
 import { fileURLToPath } from 'node:url'
 
-// @@@ plugin-harness - the PLUGIN BUNDLE emitter: render the whole SpexCode system into ONE self-contained
+// @@@ plugin-harness - the PLUGIN BUNDLE emitter: materialize the whole SpexCode system into ONE self-contained
 // Claude-plugin bundle dropped into the host-agent-scanned folder [[harness-select]] resolved (e.g. `.zcode` /
 // `.claude` → <folder>/plugins/spexcode/). It is the plugin-target counterpart of the native per-harness
 // write [[harness-adapter]] does — chosen INSTEAD of the natives (plugin exclusivity), so [[harness-delivery]]'s
@@ -29,11 +29,12 @@ const PLUGIN_ROOT = '${CLAUDE_PLUGIN_ROOT}'
 // never invokes the extras, so binding all is harmless and one emit serves every host.
 const PLUGIN_EVENTS = ['SessionStart', 'UserPromptSubmit', 'PreToolUse', 'PostToolUse', 'Stop', 'StopFailure', 'Notification'] as const
 
-// the gathered surface artifacts this render writes into the bundle. contract = the assembled guide+system
+// the gathered surface artifacts this materialize writes into the bundle. contract = the assembled guide+system
 // block (the SAME string the native path folds into CLAUDE.md, here delivered as additionalContext); skills/
-// agents/commands are the already-rendered file CONTENTS (reusing materialize's renderSkill/renderAgent), keyed
+// agents/commands are the already-materialized file CONTENTS (reusing materialize's skillArtifact/agentArtifact),
+// keyed
 // by node name; spex is the baked tsx+cli invocation the dispatcher gate calls; version stamps plugin.json.
-export type PluginRender = {
+export type PluginBundle = {
   contract: string
   skills: { name: string; content: string }[]
   agents: { name: string; content: string }[]
@@ -63,7 +64,7 @@ function pluginManifest(version: string): string {
 }
 
 // hooks.json in the Claude/z-code-compatible shape { "hooks": { "<Event>": [{ "hooks": [command…] }] } }. Every
-// event → the SHARED dispatch.sh (`plugin` baked as its harness id, SPEX inherited for the gate); SessionStart
+// event → the SHARED dispatch.sh (`plugin` baked as its harness id, SPEX inherited by handlers); SessionStart
 // ALSO runs inject-contract.sh first, so the contract additionalContext lands alongside the normal dispatch.
 function pluginHooksJson(spex: string): string {
   const dispatch = (e: string) => `SPEX='${spex}' bash "${PLUGIN_ROOT}/hooks/dispatch.sh" plugin ${e}`
@@ -78,7 +79,7 @@ function pluginHooksJson(spex: string): string {
   return JSON.stringify({ hooks }, null, 2)
 }
 
-// the SessionStart hook OUTPUT carrying the contract as additionalContext. JSON-encoded HERE, at render time,
+// the SessionStart hook OUTPUT carrying the contract as additionalContext. JSON-encoded HERE, at materialize time,
 // so the runtime hook is a trivial `cat` — never a fragile shell escaping of arbitrary contract prose.
 function contractContextJson(contract: string): string {
   return JSON.stringify({ hookSpecificOutput: { hookEventName: 'SessionStart', additionalContext: contract } }, null, 2)
@@ -89,14 +90,14 @@ function contractContextJson(contract: string): string {
 const INJECT_SH = `#!/usr/bin/env bash
 # Emit the SpexCode contract as SessionStart additionalContext — the harness-neutral contract injection (the
 # superpowers pattern; Claude/z-code normalize hookSpecificOutput.additionalContext) that replaces a plugin
-# host's missing --append-system-prompt. The JSON was rendered at materialize time, so this is a trivial cat.
+# host's missing --append-system-prompt. The JSON was written at materialize time, so this is a trivial cat.
 here="$(cd "$(dirname "\${BASH_SOURCE[0]}")" && pwd)"
 [ -f "$here/contract-context.json" ] && cat "$here/contract-context.json"
 exit 0
 `
 
 // emit (or idempotently re-emit) the whole bundle into <folder>/plugins/spexcode.
-export function emitPlugin(proj: string, folder: string, r: PluginRender): void {
+export function emitPlugin(proj: string, folder: string, r: PluginBundle): void {
   const bundle = pluginBundleDir(proj, folder)
   const meta = join(bundle, '.claude-plugin')
   const hooksDir = join(bundle, 'hooks')
@@ -110,7 +111,7 @@ export function emitPlugin(proj: string, folder: string, r: PluginRender): void
   writeFileSync(join(hooksDir, 'inject-contract.sh'), INJECT_SH)
   writeFileSync(join(hooksDir, 'contract-context.json'), contractContextJson(r.contract))
   writeFileSync(join(hooksDir, 'hooks.json'), pluginHooksJson(r.spex))
-  // skills / agents / commands — the Claude-plugin layout, the SAME rendered contents as the native dirs.
+  // skills / agents / commands — the Claude-plugin layout, the SAME materialized contents as the native dirs.
   for (const s of r.skills) writeBundleFile(join(bundle, 'skills', s.name, 'SKILL.md'), s.content)
   for (const a of r.agents) writeBundleFile(join(bundle, 'agents', `${a.name}.md`), a.content)
   for (const c of r.commands) writeBundleFile(join(bundle, 'commands', `${c.name}.md`), c.content)