spexcode 0.6.0 → 0.6.2

package/spec-cli/src/materialize.ts

@@ -5,11 +5,12 @@ import { execFileSync } from 'node:child_process'
 import { loadSystemConfig, loadSkillConfig, loadAgentConfig, loadConfig } from './specs.js'
 import { compileManifest } from './hooks.js'
 import { writeManagedBlock, removeManagedBlock, HARNESSES, type HarnessArtifacts } from './harness.js'
-import { git } from './git.js'
-import { runtimeRoot, treeSlotDir, mainCheckout, readConfig, encodeProject } from './layout.js'
+import { git, gitBinary } from './git.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, retireLegacyContractBlock, settleIndexStat, type ContractFilterBinding, type ContractFilterPayload } from './contract-filter.js'
+import { clearContractFilterPayload, contractFilterPlanted, plantContractFilter, removeContractFilter, settleIndexStat, type ContractFilterBinding, type ContractFilterPayload } from './contract-filter.js'
+import { writeFileIfChanged } from './file-write.js'
 
 export type MaterializedArtifact = {
   kind: 'hook manifest' | 'contract' | 'shim' | 'skill' | 'agent' | 'plugin bundle' | 'trust'
@@ -37,7 +38,9 @@ const SPEX = join(PKG, 'bin', 'spex.mjs')
 export function contentHash(proj: string): string {
   try {
     const harnessSh = join(PKG, 'hooks', 'harness.sh')
-    return execFileSync('bash', ['-c', `cd "${proj}" && . "${harnessSh}" && hp_config_hash`]).toString().trim()
+    const gitDir = dirname(gitBinary(process.env))
+    const env = { ...process.env, PATH: `${gitDir}:${process.env.PATH || ''}` }
+    return execFileSync('bash', ['-c', `cd "${proj}" && . "${harnessSh}" && hp_config_hash`], { env }).toString().trim()
   } catch { return '' }
 }
 
@@ -61,93 +64,136 @@ 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 }
 }
+function clearSkipWorktree(proj: string, file: string): void {
+  if (!isTracked(proj, file)) return
+  try { git(['-C', proj, 'update-index', '--no-skip-worktree', file]) } catch {}
+}
 
 function registeredTrees(proj: string): string[] {
   const rows = git(['-C', mainCheckout(proj), 'worktree', 'list', '--porcelain', '-z']).split('\0')
   return rows.filter((row) => row.startsWith('worktree ')).map((row) => row.slice('worktree '.length))
 }
 
-const TREE_IGNORE_RECEIPT = 'tree-ignore-v1'
-
-function hasLegacyTreeIgnore(proj: string): boolean {
-  return registeredTrees(proj).some((tree) => {
-    const slot = join(runtimeRoot(proj), 'trees', encodeProject(tree))
-    return existsSync(join(slot, 'content-hash')) && !existsSync(join(slot, TREE_IGNORE_RECEIPT))
-  })
-}
-
-function managedExcludeEntries(file: string): string[] {
-  if (!existsSync(file)) return []
-  const lines = readFileSync(file, 'utf8').split('\n')
-  const start = lines.indexOf('# spexcode:start')
-  const end = lines.indexOf('# spexcode:end', start + 1)
-  return start >= 0 && end > start ? lines.slice(start + 1, end).filter(Boolean) : []
-}
-
 function selectionBody(selected: typeof HARNESSES, plugin = false): string {
   return [...new Set([...selected.map((h) => h.dispatchId), ...(plugin ? ['plugin'] : [])])].sort().join('\n') + '\n'
 }
 
 function publishSelection(path: string, body: string): void {
+  try { if (readFileSync(path, 'utf8') === body) return } catch (error: any) { if (error?.code !== 'ENOENT') throw error }
   const prepared = `${path}.${process.pid}.tmp`
   writeFileSync(prepared, body)
   renameSync(prepared, path)
 }
 
-const SENTINEL_RE = /\n*<!-- spexcode:start -->[\s\S]*?<!-- spexcode:end -->\n*/
-export function stripSpexcodeBlock(text: string): string {
-  const m = SENTINEL_RE.exec(text)
+function managedBlockPattern(comment: readonly [string, string]): RegExp {
+  const [open, close] = comment
+  const escape = (value: string) => value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+  return new RegExp(`\\n*${escape(`${open}spexcode:start${close}`)}[\\s\\S]*?${escape(`${open}spexcode:end${close}`)}\\n*`)
+}
+export function stripSpexcodeBlock(text: string, comment: readonly [string, string] = ['<!-- ', ' -->']): string {
+  const sentinel = managedBlockPattern(comment)
+  const m = sentinel.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')
+  const replaced = text.replace(sentinel, '\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', '--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
+function pruneGeneratedSkills(dir: string | null, keep: ReadonlySet<string>): boolean {
+  if (!dir || !existsSync(dir)) return false
+  let changed = false
   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 */ }
+    try {
+      if (!keep.has(e.name) && existsSync(f) && readFileSync(f, 'utf8').includes(GENERATED_MARK)) {
+        rmSync(join(dir, e.name), { recursive: true, force: true })
+        changed = true
+      }
+    } catch { /* unreadable → not provably ours */ }
   }
+  return changed
 }
-function sweepGeneratedAgents(dir: string | null): void {
-  if (!dir || !existsSync(dir)) return
+function pruneGeneratedAgents(dir: string | null, keep: ReadonlySet<string>): boolean {
+  if (!dir || !existsSync(dir)) return false
+  let changed = false
   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 */ }
+    try {
+      if (!keep.has(e.name.slice(0, -3)) && readFileSync(f, 'utf8').includes(GENERATED_MARK)) {
+        rmSync(f, { force: true })
+        changed = true
+      }
+    } catch { /* unreadable → not provably ours */ }
+  }
+  return changed
+}
+
+type TreeTargets = {
+  contracts: ReadonlySet<string>
+  treeShims: ReadonlySet<string>
+  anchors: ReadonlySet<string>
+  skills: ReadonlyMap<string, ReadonlySet<string>>
+  agents: ReadonlyMap<string, ReadonlySet<string>>
+}
+
+function cleanupHarnessDirs(proj: string): void {
+  const roots = new Set([proj, mainCheckout(proj)])
+  const dirs = HARNESSES.flatMap((h) => {
+    const anchor = h.worktreeHookAnchor(proj)
+    return [h.skillDir(proj), h.agentDir(proj), dirname(h.shimFile(proj)), anchor ? dirname(anchor) : null]
+  }).filter((d): d is string => !!d)
+  for (const d of [...new Set([...dirs, ...dirs.map((dir) => dirname(dir))])]
+    .filter((dir) => !roots.has(dir)).sort((a, b) => b.length - a.length)) {
+    try { rmdirSync(d) } catch {}
   }
 }
 
+function reconcileTree(proj: string, targets: TreeTargets, tracked: (file: string) => boolean): void {
+  let removed = false
+  const contractFiles = new Set(HARNESSES.flatMap((h) => h.contractFiles(proj)))
+  for (const file of contractFiles) {
+    if (targets.contracts.has(file) || !existsSync(file)) continue
+    const text = readFileSync(file, 'utf8')
+    if (!text.includes('<!-- spexcode:start -->')) continue
+    removeManagedBlock(file, ['<!-- ', ' -->'], !tracked(file))
+    removed = true
+  }
+  const treeShims = new Set(HARNESSES.filter((h) => h.shimScope === 'tree').map((h) => h.shimFile(proj)))
+  const anchors = new Set(HARNESSES.map((h) => h.worktreeHookAnchor(proj)).filter((path): path is string => !!path))
+  for (const file of [...treeShims, ...anchors]) {
+    if (targets.treeShims.has(file) || targets.anchors.has(file) || !existsSync(file)) continue
+    if (readFileSync(file, 'utf8').includes('dispatch.sh')) { rmSync(file, { force: true }); removed = true }
+  }
+  for (const dir of new Set(HARNESSES.map((h) => h.skillDir(proj)).filter((path): path is string => !!path)))
+    removed = pruneGeneratedSkills(dir, targets.skills.get(dir) ?? new Set()) || removed
+  for (const dir of new Set(HARNESSES.map((h) => h.agentDir(proj)).filter((path): path is string => !!path)))
+    removed = pruneGeneratedAgents(dir, targets.agents.get(dir) ?? new Set()) || removed
+  if (removed) cleanupHarnessDirs(proj)
+}
+
 function eraseTree(proj: string, arts: HarnessArtifacts, preserveProject: boolean): 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, preserveProject)
-    for (const f of h.contractFiles(proj)) clearSkipWorktree(proj, f)   // legacy private-overlay bit — erase-only
-    sweepGeneratedSkills(h.skillDir(proj))
-    sweepGeneratedAgents(h.agentDir(proj))
+    for (const f of h.contractFiles(proj)) clearSkipWorktree(proj, f)
+    pruneGeneratedSkills(h.skillDir(proj), new Set())
+    pruneGeneratedAgents(h.agentDir(proj), new Set())
   }
   // 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'))
-  removeContractFilter(proj, [...HARNESSES.flatMap((h) => h.contractFiles(proj)), join(proj, '.gitignore')])
+  clearContractFilterPayload(proj, [...HARNESSES.flatMap((h) => h.contractFiles(proj)), join(proj, '.gitignore')])
   // 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).
@@ -157,16 +203,7 @@ function eraseTree(proj: string, arts: HarnessArtifacts, preserveProject: boolea
   // because a harness may nest its shim a level below its home (opencode's .opencode/plugins/, pi's
   // .pi/extensions/) — but never the checkout roots themselves. 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)
-    const dirs = [h.skillDir(proj), h.agentDir(proj), dirname(h.shimFile(proj)), anchor ? dirname(anchor) : null]
-      .filter((d): d is string => !!d)
-    const roots = new Set([proj, mainCheckout(proj)])
-    const sweep = [...new Set([...dirs, ...dirs.map((d) => dirname(d))])]
-      .filter((d) => !roots.has(d))
-      .sort((a, b) => b.length - a.length)
-    for (const d of sweep) { try { rmdirSync(d) } catch { /* non-empty or absent — keep */ } }
-  }
+  cleanupHarnessDirs(proj)
 }
 
 export function dematerialize(proj = process.cwd(), arts: HarnessArtifacts = { skills: [], agents: [] }): void {
@@ -177,7 +214,7 @@ export function dematerialize(proj = process.cwd(), arts: HarnessArtifacts = { s
     git(['-C', tree, 'rev-parse', '--show-toplevel'])
   }
   for (const tree of trees) {
-    // Only the caller's live spec may widen the legacy name sweep. Siblings are identity-stamp-only: the
+    // Only the caller's live spec may widen the name sweep. Siblings are identity-stamp-only: the
     // same name there may be user-owned or may not exist in this tree's divergent spec at all.
     eraseTree(tree, tree === current ? arts : { skills: [], agents: [] }, false)
   }
@@ -196,7 +233,7 @@ export function materialize(proj = process.cwd()): MaterializeResult {
   }
   // (1) hook manifest (persistent — the dispatcher reads it; regenerated only here, on change).
   const manifest = join(rt, 'hooks-manifest')
-  writeFileSync(manifest, compileManifest())
+  writeFileIfChanged(manifest, compileManifest())
   record('hook manifest', manifest)
   // (2) the contract = the surface:system plugin 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.
@@ -213,14 +250,7 @@ export function materialize(proj = process.cwd()): MaterializeResult {
   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.
-  eraseTree(proj, arts, true)
-
-  // ---- 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, 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.
@@ -239,53 +269,80 @@ export function materialize(proj = process.cwd()): MaterializeResult {
   // because their residence is the live three-state kind detection below, not a static entry.
   const artifactPaths: string[] = []
   const machinePaths: string[] = []
-  const contractPaths: string[] = []
+  const contractTargets = new Map<string, string>()
+  const treeShimTargets = new Map<string, string>()
+  const anchorTargets = new Map<string, string>()
+  const skillTargets = new Map<string, string>()
+  const agentTargets = new Map<string, string>()
+  const skillsByDir = new Map<string, Set<string>>()
+  const agentsByDir = new Map<string, Set<string>>()
+  const addTarget = (targets: Map<string, string>, path: string, content: string) => {
+    const prior = targets.get(path)
+    if (prior !== undefined && prior !== content) throw new Error(`conflicting materialize targets for ${path}`)
+    targets.set(path, content)
+  }
   for (const h of selected) {
-    if (contract) for (const f of h.contractFiles(proj)) { writeManagedBlock(f, contract); contractPaths.push(f); record('contract', f) }
+    if (contract) for (const f of h.contractFiles(proj)) addTarget(contractTargets, f, contract)
     const shim = h.shim(DISPATCH, SPEX)
     if (h.shimScope === 'tree') {
-      const shimFile = h.shimFile(proj)
-      mkdirSync(dirname(shimFile), { recursive: true })
-      writeFileSync(shimFile, shim.content)
-      record('shim', shimFile)
-      machinePaths.push(shimFile)
+      addTarget(treeShimTargets, h.shimFile(proj), shim.content)
     }
     // 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). One adapter line; null otherwise.
     const anchor = h.worktreeHookAnchor(proj)
-    if (anchor) { mkdirSync(dirname(anchor), { recursive: true }); writeFileSync(anchor, shim.content); machinePaths.push(anchor); record('shim', anchor) }
+    if (anchor) addTarget(anchorTargets, anchor, shim.content)
+  }
+  for (const sk of skillNodes) for (const h of selected) {
+    const dir = h.skillDir(proj); if (!dir) continue
+    addTarget(skillTargets, join(dir, sk.name, 'SKILL.md'), skillArtifact(sk))
+    const names = skillsByDir.get(dir) ?? new Set<string>(); names.add(sk.name); skillsByDir.set(dir, names)
+  }
+  for (const ag of agentNodes) for (const h of selected) {
+    const dir = h.agentDir(proj); if (!dir) continue
+    addTarget(agentTargets, join(dir, `${ag.name}.md`), agentArtifact(ag))
+    const names = agentsByDir.get(dir) ?? new Set<string>(); names.add(ag.name); agentsByDir.set(dir, names)
+  }
+  const tracked = new Map<string, boolean>()
+  const isTrackedHere = (file: string) => {
+    const known = tracked.get(file)
+    if (known !== undefined) return known
+    const value = isTracked(proj, file); tracked.set(file, value); return value
+  }
+  reconcileTree(proj, {
+    contracts: new Set(contractTargets.keys()), treeShims: new Set(treeShimTargets.keys()), anchors: new Set(anchorTargets.keys()),
+    skills: skillsByDir, agents: agentsByDir,
+  }, isTrackedHere)
+  const changedMaterialized = new Set<string>()
+  for (const [file, content] of contractTargets) {
+    if (writeManagedBlock(file, content)) changedMaterialized.add(file)
+    record('contract', file)
+  }
+  const contractPaths = [...contractTargets.keys()]
+  for (const [file, content] of treeShimTargets) {
+    mkdirSync(dirname(file), { recursive: true }); writeFileIfChanged(file, content)
+    record('shim', file); machinePaths.push(file)
+  }
+  for (const [file, content] of anchorTargets) {
+    mkdirSync(dirname(file), { recursive: true }); writeFileIfChanged(file, content)
+    record('shim', file); machinePaths.push(file)
   }
   const selectedByDispatch = new Map(selected.map((h) => [h.dispatchId, h]))
   for (const h of selectedByDispatch.values()) {
     const shim = h.shim(DISPATCH, SPEX)
     if (h.shimScope === 'project') {
       const file = h.shimFile(proj)
-      mkdirSync(dirname(file), { recursive: true }); writeFileSync(file, shim.content)
+      mkdirSync(dirname(file), { recursive: true }); writeFileIfChanged(file, shim.content)
       record('shim', file)
     }
     for (const file of h.writeTrust(proj, shim.cmd)) record('trust', file)
   }
-  // (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, skillArtifact(sk))
-      artifactPaths.push(f)
-      record('skill', f)
-    }
+  for (const [file, content] of skillTargets) {
+    mkdirSync(dirname(file), { recursive: true }); writeFileIfChanged(file, content)
+    artifactPaths.push(file); record('skill', file)
   }
-  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, agentArtifact(ag))
-      artifactPaths.push(f)
-      record('agent', f)
-    }
+  for (const [file, content] of agentTargets) {
+    mkdirSync(dirname(file), { recursive: true }); writeFileIfChanged(file, content)
+    artifactPaths.push(file); record('agent', file)
   }
   // (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
@@ -294,11 +351,7 @@ export function materialize(proj = process.cwd()): MaterializeResult {
   //     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')
-  // 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 prevFolders = existsSync(ledger) ? readFileSync(ledger, '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) {
@@ -315,7 +368,7 @@ export function materialize(proj = process.cwd()): MaterializeResult {
       record('plugin bundle', pluginBundleDir(proj, p.folder))
     }
   }
-  writeFileSync(ledger, curFolders.join('\n'))
+  writeFileIfChanged(ledger, curFolders.join('\n'))
   // (9) ignore + mixed text. Only checkout-invariant residue and project-shared shims belong in the COMMON
   // info/exclude; selection-dependent paths live in this tree's filtered working .gitignore.
   const mc = mainCheckout(proj)
@@ -327,43 +380,38 @@ export function materialize(proj = process.cwd()): MaterializeResult {
     'spexcode.local.json', '.worktrees/', '.session',
   ]
   const entries = (list: string[]) => [...new Set(list)].sort().join('\n')
-  const priorCommonEntries = managedExcludeEntries(infoExcludePath(proj))
-
   // Contract residence stays a live fact. Selection-dependent untracked products are ignored by this tree's
   // working .gitignore, whose own managed block is filtered when the host tracks/owns that file.
   const filterContracts: string[] = []
   const oursContracts: string[] = []
   for (const f of contractPaths) {
-    if (isTracked(proj, f) || hostContentOf(f).trim()) filterContracts.push(f)
+    if (isTrackedHere(f) || hostContentOf(f).trim()) filterContracts.push(f)
     else oursContracts.push(f)
   }
   const localEntries = [...machinePaths, ...bundlePaths, ...artifactPaths, ...oursContracts]
     .map((p) => relative(proj, p)).filter((p) => !p.startsWith('..'))
   const ignoreFile = join(proj, '.gitignore')
-  const ignoreTracked = isTracked(proj, ignoreFile)
-  const ignoreHost = existsSync(ignoreFile) ? readFileSync(ignoreFile, 'utf8') : ''
+  const ignoreTracked = isTrackedHere(ignoreFile)
+  const ignoreHost = existsSync(ignoreFile) ? stripSpexcodeBlock(readFileSync(ignoreFile, 'utf8'), ['# ', '']) : ''
   if (!ignoreTracked && !ignoreHost.trim()) localEntries.push('.gitignore')
   const ignoreBody = entries(localEntries)
-  writeManagedBlock(ignoreFile, ignoreBody, ['# ', ''])
+  if (writeManagedBlock(ignoreFile, ignoreBody, ['# ', ''])) changedMaterialized.add(ignoreFile)
 
   const payloads: ContractFilterPayload[] = filterContracts.map((file) => ({ file: relative(proj, file), content: contract }))
   if (ignoreTracked || ignoreHost.trim()) payloads.push({ file: '.gitignore', content: ignoreBody })
   const bindings: ContractFilterBinding[] = [
     ...[...new Set(HARNESSES.flatMap((h) => h.contractFiles(proj).map((file) => relative(proj, file))))]
-      .map((file) => ({ file, start: '<!-- spexcode:start -->', end: '<!-- spexcode:end -->', legacy: true })),
+      .map((file) => ({ file, start: '<!-- spexcode:start -->', end: '<!-- spexcode:end -->' })),
     { file: '.gitignore', start: '# spexcode:start', end: '# spexcode:end' },
   ]
-  if (payloads.length) plantContractFilter(proj, payloads, bindings)
-  // (5) finish diagnostics/migration, then atomically publish the allowlist LAST. Dispatch consumes only that
+  if (payloads.length) plantContractFilter(proj, payloads, bindings, [...changedMaterialized])
+  else if (contractFilterPlanted(proj)) removeContractFilter(proj, [...HARNESSES.flatMap((h) => h.contractFiles(proj)), join(proj, '.gitignore')])
+  // (5) finish diagnostics, then atomically publish the allowlist LAST. Dispatch consumes only that
   // final receipt; a killed writer leaves the preceding successful selection intact.
   const h = contentHash(proj)
-  writeFileSync(join(rt, 'content-hash'), h)
-  writeFileSync(join(rt, 'contract-filter-v2'), '')
-  writeFileSync(join(rt, TREE_IGNORE_RECEIPT), '')
-  writeFileSync(join(runtimeRoot(proj), 'harness-selection-v1'), '')
-  retireLegacyContractBlock(proj)
-  const legacyEntries = hasLegacyTreeIgnore(proj) ? priorCommonEntries : []
-  writeManagedBlock(infoExcludePath(proj), entries([...commonEntries, ...legacyEntries]), ['# ', ''])
+  writeFileIfChanged(join(rt, 'content-hash'), h)
+  writeFileIfChanged(join(runtimeRoot(proj), 'harness-selection-v1'), '')
+  writeManagedBlock(infoExcludePath(proj), entries(commonEntries), ['# ', ''])
   publishSelection(join(rt, 'harnesses'), selectionBody(selected, plugins.length > 0))
   return { contentHash: h, planted }
 }

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

@@ -1,31 +1,32 @@
-import { writeFileSync, mkdirSync, readFileSync, existsSync, rmSync, copyFileSync } from 'node:fs'
+import { mkdirSync, readFileSync, existsSync, readdirSync, rmSync } from 'node:fs'
 import { join, dirname } from 'node:path'
 import { fileURLToPath } from 'node:url'
+import { copyFileIfChanged, writeFileIfChanged } from './file-write.js'
 
 // @@@ 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-plugin bundle dropped into the host-agent-scanned folder [[harness-select]] resolved (e.g. `.adopter-a` /
 // `.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
 // materialize prunes every native first, then emits this. The bundle follows the de-facto Claude-plugin schema
 // (a `.claude-plugin/plugin.json` pointing at hooks/skills/commands/agents); the host's discovery order is
-// `.zcode-plugin > .claude-plugin > .codex-plugin` and z-code/Claude both read a `.claude-plugin` directly, so
-// the ONE `.claude-plugin` bundle reaches ZCode, Claude, and (future) Codex from a single emit.
+// `.adopter-a-plugin > .claude-plugin > .codex-plugin` and adopter-a/Claude both read a `.claude-plugin` directly, so
+// the ONE `.claude-plugin` bundle reaches AdopterA, Claude, and (future) Codex from a single emit.
 //
 // The contract is NOT delivered by an always-on CLAUDE.md block here (the bundle never touches the repo's own
 // files) — it maps to a SessionStart hook that emits hookSpecificOutput.additionalContext (the harness-neutral
-// injection Claude/z-code normalize, the superpowers pattern), so a plugin host gets the contract with no
+// injection Claude/adopter-a normalize, the superpowers pattern), so a plugin host gets the contract with no
 // --append-system-prompt. The hooks reuse the SAME dispatch.sh wiring as the natives, located via the host's
 // ${CLAUDE_PLUGIN_ROOT} variable; dispatch.sh's first arg is the harness id `plugin`, so its shell mirror
-// (harness.sh) parses payloads as the claude family (z-code/Claude share Claude's tool names + file_path).
+// (harness.sh) parses payloads as the claude family (adopter-a/Claude share Claude's tool names + file_path).
 
 const PKG = fileURLToPath(new URL('..', import.meta.url))   // installed spec-cli root
 const HOOKS_SRC = join(PKG, 'hooks')                        // the canonical dispatch.sh + harness.sh source
 const PLUGIN_NAME = 'spexcode'
 // the host substitutes ${CLAUDE_PLUGIN_ROOT} with the bundle's own absolute path before running a hook command
-// (the same variable z-code's hook-compat honours), so dispatch.sh/inject-contract.sh resolve regardless of
+// (the same variable adopter-a's hook-compat honours), so dispatch.sh/inject-contract.sh resolve regardless of
 // where the host scanned the bundle from.
 const PLUGIN_ROOT = '${CLAUDE_PLUGIN_ROOT}'
-// the lifecycle events the bundle binds — the Claude/z-code superset; a host that fires fewer (Codex) simply
+// the lifecycle events the bundle binds — the Claude/adopter-a superset; a host that fires fewer (Codex) simply
 // 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
 
@@ -50,7 +51,7 @@ export function pluginBundleDir(proj: string, folder: string): string {
 }
 
 // the de-facto Claude-plugin manifest: name (the bundle identity clean() gates on), version, description, and
-// the component pointers Claude/z-code discover (hooks.json + the skills/commands/agents dirs).
+// the component pointers Claude/adopter-a discover (hooks.json + the skills/commands/agents dirs).
 function pluginManifest(version: string): string {
   return JSON.stringify({
     name: PLUGIN_NAME,
@@ -63,7 +64,7 @@ function pluginManifest(version: string): string {
   }, null, 2)
 }
 
-// hooks.json in the Claude/z-code-compatible shape { "hooks": { "<Event>": [{ "hooks": [command…] }] } }. Every
+// hooks.json in the Claude/adopter-a-compatible shape { "hooks": { "<Event>": [{ "hooks": [command…] }] } }. Every
 // 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 {
@@ -89,7 +90,7 @@ function contractContextJson(contract: string): string {
 // stand-in for --append-system-prompt). A bare cat — all the encoding happened at materialize time.
 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
+# superpowers pattern; Claude/adopter-a normalize hookSpecificOutput.additionalContext) that replaces a plugin
 # 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"
@@ -103,23 +104,33 @@ export function emitPlugin(proj: string, folder: string, r: PluginBundle): void
   const hooksDir = join(bundle, 'hooks')
   mkdirSync(meta, { recursive: true })
   mkdirSync(hooksDir, { recursive: true })
-  writeFileSync(join(meta, 'plugin.json'), pluginManifest(r.version))
+  writeFileIfChanged(join(meta, 'plugin.json'), pluginManifest(r.version))
   // hooks: the SHARED dispatcher + its shell mirror (copied verbatim — the exact native wiring), the contract
   // injector + its pre-encoded payload, and the event→dispatch binding.
-  copyFileSync(join(HOOKS_SRC, 'dispatch.sh'), join(hooksDir, 'dispatch.sh'))
-  copyFileSync(join(HOOKS_SRC, 'harness.sh'), join(hooksDir, 'harness.sh'))
-  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))
+  copyFileIfChanged(join(HOOKS_SRC, 'dispatch.sh'), join(hooksDir, 'dispatch.sh'))
+  copyFileIfChanged(join(HOOKS_SRC, 'harness.sh'), join(hooksDir, 'harness.sh'))
+  writeFileIfChanged(join(hooksDir, 'inject-contract.sh'), INJECT_SH)
+  writeFileIfChanged(join(hooksDir, 'contract-context.json'), contractContextJson(r.contract))
+  writeFileIfChanged(join(hooksDir, 'hooks.json'), pluginHooksJson(r.spex))
   // skills / agents / commands — the Claude-plugin layout, the SAME materialized contents as the native dirs.
+  reconcileBundleDirectory(join(bundle, 'skills'), new Set(r.skills.map((s) => s.name)))
+  reconcileBundleDirectory(join(bundle, 'agents'), new Set(r.agents.map((a) => `${a.name}.md`)))
+  reconcileBundleDirectory(join(bundle, 'commands'), new Set(r.commands.map((c) => `${c.name}.md`)))
   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)
 }
 
+function reconcileBundleDirectory(dir: string, expectedNames: ReadonlySet<string>): void {
+  if (!existsSync(dir)) return
+  for (const entry of readdirSync(dir)) {
+    if (!expectedNames.has(entry)) rmSync(join(dir, entry), { recursive: true, force: true })
+  }
+}
+
 function writeBundleFile(f: string, content: string): void {
   mkdirSync(dirname(f), { recursive: true })
-  writeFileSync(f, content)
+  writeFileIfChanged(f, content)
 }
 
 // the INVERSE of emitPlugin — prune the bundle when its folder is DESELECTED ([[harness-delivery]] tracks the

package/spec-cli/src/process-identity.ts

@@ -142,6 +142,19 @@ export function verifyDetachedRuntime(pid: number, receiptFile: string, adapter:
   return live
 }
 
+// The inverse question of verifyDetachedRuntime: not "is the recorded process running right now" but "is it
+// provably GONE". The two are not complements — a missing receipt, an unreadable identity, or a PID we never
+// recorded answers neither, and a caller that treats "unproven" as "dead" would retire a live runtime it can
+// simply no longer address. Only a recorded start identity that the live PID no longer matches (including a
+// PID that is not running at all) is proof of death.
+export function detachedRuntimeIsGone(pid: number, receiptFile: string, adapter: ProcessAdapter = hostProcessAdapter): boolean {
+  let receipt: DetachedLaunchReceiptV4 | null
+  try { receipt = parseDetachedLaunchReceipt(readFileSync(receiptFile, 'utf8'), adapter.platform) }
+  catch { return false }
+  if (!receipt || receipt.pid !== pid) return false
+  return adapter.startToken(pid) !== receipt.startToken
+}
+
 // A v3 scope is only a migration witness when every recorded and live Linux identity agrees. Readers never
 // call this: minting a v4 receipt belongs to the write admission path that needs the shared runtime.
 export function migrateLegacyDetachedRuntimeReceipt(