spexcode 0.2.4 → 0.2.6

package/spec-cli/src/commit-surgery.ts

@@ -0,0 +1,81 @@
+import { execFileSync } from 'node:child_process'
+import { relative } from 'node:path'
+import { materialize, stripSpexcodeBlock, GENERATED_MARK } from './materialize.js'
+import { HARNESSES } from './harness.js'
+
+// @@@ commit-surgery ([[commit-surgery]]) - the history anchor: pre-commit runs an UNCONDITIONAL materialize
+// (the masks are provably fresh at the only moment history is written — the temporal invariant "materialize
+// must never be stale" collapses into this one event) and then REPAIRS the staged index instead of rejecting:
+//   - a staged contract blob carrying our sentinel block → clean it IN PLACE (source = the STAGED BLOB, never
+//     the worktree: `git add -p`'s partial staging survives byte-for-byte; only the block is removed);
+//   - a staged generated/machine artifact that HEAD does not track → evict it (its tracked contribution is
+//     zero bytes by definition — an empty husk is worse than absence);
+//   - anything HEAD already tracks is never deleted by a hook — a legacy committed artifact heals by the
+//     block-strip above, converging history toward pristine without a surprise deletion commit.
+// Both operations carry zero intent ambiguity (the block's content is never the user's; a wholly-ours file
+// holds no user byte), so there is no question to ask and no rejection — one printed note per repair, and
+// the commit proceeds. The worst full path costs the user ONE bump, and it is git's own: `git add` refused
+// on an excluded path, git itself suggests -f, and this surgery makes that native escape hatch safe.
+//
+// GIT ENV, deliberately INVERTED from git.ts's git(): every call here PRESERVES the hook's environment —
+// GIT_INDEX_FILE must be honored so the surgery reads/writes the EXACT index this commit is being built
+// from (a `git commit <path>` pathspec commit and `git commit -a` both run hooks against a TEMPORARY index;
+// operating on the real one would silently miss them). git.ts strips that env for repo DISCOVERY reasons;
+// index surgery is the one place the env is the point.
+const raw = (args: string[], input?: string): string =>
+  execFileSync('git', args, { input, encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] })
+
+function inHead(p: string): boolean {
+  try { raw(['cat-file', '-e', `HEAD:${p}`]); return true } catch { return false }
+}
+function stagedBlob(p: string): string | null {
+  try { return raw(['show', `:${p}`]) } catch { return null }
+}
+function evict(p: string, why: string): void {
+  raw(['update-index', '--force-remove', '--', p])
+  console.error(`spexcode: unstaged ${p} (${why} — generated artifacts are never tracked; the file stays on disk)`)
+}
+function replaceBlob(p: string, content: string): void {
+  const stage = raw(['ls-files', '--stage', '--', p]).trim()          // "100644 <sha> 0\t<p>"
+  const mode = stage.split(/\s/)[0] || '100644'
+  const sha = raw(['hash-object', '-w', '--stdin'], content).trim()
+  raw(['update-index', '--cacheinfo', `${mode},${sha},${p}`])
+  console.error(`spexcode: stripped the <!-- spexcode --> block from staged ${p} (the block is working-tree context, never history)`)
+}
+
+export function commitSurgery(proj = process.cwd()): void {
+  // (1) unconditional materialize — machine-fixable state (exclude entries, filter binding, kind flips)
+  // is repaired BEFORE the index is inspected, so the inspection below judges against fresh masks.
+  try { materialize(proj) } catch (e) {
+    console.error(`spexcode: pre-commit materialize failed (${(e as Error).message}) — footprint may be stale this commit`)
+  }
+  const staged = raw(['diff', '--cached', '--name-only', '-z']).split('\0').filter(Boolean)
+  if (!staged.length) return
+  const rel = (f: string) => relative(proj, f)
+  const contracts = new Set(HARNESSES.flatMap((h) => h.contractFiles(proj)).map(rel))
+  const machine = new Set<string>(['spexcode.local.json', '.session'])
+  for (const h of HARNESSES) {
+    machine.add(rel(h.shimFile(proj)))
+    const a = h.worktreeHookAnchor(proj)
+    if (a) machine.add(rel(a))
+  }
+  const generatedDirs = HARNESSES.flatMap((h) => [h.skillDir(proj), h.agentDir(proj)])
+    .filter((d): d is string => !!d).map((d) => `${rel(d)}/`)
+  for (const p of staged) {
+    if (contracts.has(p)) {
+      const blob = stagedBlob(p)
+      if (blob === null) continue
+      const stripped = stripSpexcodeBlock(blob)
+      if (stripped === blob) continue                               // no block staged — clean already did its job
+      if (!stripped.trim() && !inHead(p)) evict(p, 'wholly a spexcode materialized artifact')
+      else replaceBlob(p, stripped)
+    } else if (machine.has(p) || p.startsWith('.worktrees/')) {
+      if (!inHead(p)) evict(p, 'a machine-local spexcode file')
+      else console.error(`spexcode: ${p} is a machine-local spexcode file but HEAD already tracks it — not touching a tracked file; untrack it yourself (git rm --cached ${p})`)
+    } else if (generatedDirs.some((d) => p.startsWith(d))) {
+      if (inHead(p)) continue                                       // historically tracked — the host's call
+      const blob = stagedBlob(p)
+      if (blob !== null && blob.includes(GENERATED_MARK)) evict(p, 'a generated skill/agent artifact')
+    }
+  }
+}

package/spec-cli/src/contract-filter.ts

@@ -0,0 +1,156 @@
+import { mkdirSync, readFileSync, rmSync, writeFileSync, chmodSync } from 'node:fs'
+import { join, relative } from 'node:path'
+import { execFileSync } from 'node:child_process'
+import { git } from './git.js'
+import { writeManagedBlock, removeManagedBlock } from './harness.js'
+
+// @@@ contract-filter ([[content-filter]]) - the answer for a MIXED-CONTENT contract file: a
+// CLAUDE.md/AGENTS.md the HOST TRACKS — or has begun writing its OWN prose into — where "generate + ignore"
+// is either a no-op (git ignores only untracked paths) or would hide USER content. A git clean/smudge
+// content filter keeps the two contents on their own sides of the index: the REPO stores the
+// pristine host prose (clean strips our sentinel block on stage/diff), the WORKING TREE carries prose + block
+// (smudge re-injects it on checkout). Everything the filter needs is PER-CLONE — `git config
+// filter.spexcode.*` + a managed block in `.git/info/attributes` + two files under `<common>/spexcode/` —
+// zero repo footprint. The sentinels are the load-bearing anchor: the invariant
+// is clean(smudge(x)) == x (for text ending in one newline — see the shim), so `git status` stays clean.
+// Planted only where mixed content EXISTS or is imminent (a tracked contract file, or an untracked one the
+// user's prose entered — pre-armed so their eventual `git add` strips the block; a wholly-ours file needs
+// only the exclude). materialize plants/refreshes/erases it per that live kind detection ([[residence]]
+// / the forgetting law).
+
+// the three field-sharpened edges this module owes ([[content-filter]]):
+//   ① the configured command points at a STABLE shim path and degrades to `cat` (identity) when the shim is
+//     missing — a bare missing filter command makes git spray "cannot fork" fatals on EVERY operation;
+//   ② a changed contract does NOT propagate by itself (git re-smudges only on checkout) — materialize's
+//     re-materialize writes the managed block straight into the working file (writeManagedBlock IS the re-smudge),
+//     and this module refreshes the block file the shim reads so future checkouts agree;
+//   ③ unplanting must strip the block from the WORKING FILES before the config goes away, or the block
+//     residue surfaces as an uncommitted modification — the caller (dematerialize) removes the managed
+//     blocks first and only then calls removeContractFilter.
+
+function commonDirOf(proj: string): string {
+  return git(['-C', proj, 'rev-parse', '--path-format=absolute', '--git-common-dir']).trim()
+}
+const filterDir = (common: string) => join(common, 'spexcode')
+const shimPath = (common: string) => join(filterDir(common), 'contract-filter.sh')
+const blockPath = (common: string) => join(filterDir(common), 'contract-block.md')
+const attributesPath = (common: string) => join(common, 'info', 'attributes')
+
+// the per-clone shim both filter directions run through. Pure shell/awk (no node boot on git's hot path),
+// mirroring writeManagedBlock/removeManagedBlock's normalization exactly so the two writers agree:
+//   clean : drop the sentinel block (+ the blank line smudge printed before it) → the pristine host prose.
+//   smudge: clean first (defensive — a block already in the index can never double-inject), then append one
+//           blank line + START + the contract-block file's content + END.
+// Byte-exactness holds for text ending in exactly one newline (git's own well-formed-text shape); a pristine
+// file ending in zero or 2+ newlines is normalized to one on the first round-trip and stable after.
+const SHIM = `#!/usr/bin/env bash
+# spexcode contract filter (generated by spex materialize; see [[content-filter]]).
+# clean(smudge(x)) == x: the repo keeps the pristine host prose, the working tree carries prose + block.
+set -u
+mode="\${1:?usage: contract-filter.sh smudge|clean}"
+here="$(cd "$(dirname "\${BASH_SOURCE[0]}")" && pwd)"
+block="$here/contract-block.md"
+strip() {
+  awk 'BEGIN { n = 0 }
+    { lines[n++] = $0 }
+    END {
+      s = -1; e = -1
+      for (i = 0; i < n; i++) {
+        if (lines[i] == "<!-- spexcode:start -->" && s < 0) s = i
+        if (lines[i] == "<!-- spexcode:end -->" && s >= 0 && e < 0) e = i
+      }
+      if (s >= 0 && e >= s) {
+        a = s; while (a > 0 && lines[a-1] == "") a--
+        b = e; while (b + 1 < n && lines[b+1] == "") b++
+        j = 0
+        for (i = 0; i < n; i++) if (i < a || i > b) lines[j++] = lines[i]
+        n = j
+      }
+      # NO leading-blank strip: dropping a..b (block + its surrounding blanks) can never CREATE a leading
+      # blank, and a host file that BEGINS with blank lines must keep them — clean(smudge(x)) == x.
+      for (i = 0; i < n; i++) print lines[i]
+    }'
+}
+case "$mode" in
+  clean) strip ;;
+  smudge)
+    if [ ! -r "$block" ]; then cat; exit 0; fi          # no block content → identity (graceful, never fatal)
+    strip | awk -v b="$block" 'BEGIN { n = 0 }
+      { lines[n++] = $0 }
+      END {
+        while (n > 0 && lines[n-1] == "") n--           # trim trailing blanks (writeManagedBlock parity)
+        for (i = 0; i < n; i++) print lines[i]
+        if (n > 0) print ""
+        print "<!-- spexcode:start -->"
+        while ((getline l < b) > 0) print l
+        print "<!-- spexcode:end -->"
+      }' ;;
+  *) echo "contract-filter.sh: unknown mode $mode" >&2; exit 1 ;;
+esac
+`
+
+// edge ①: the command git runs is a tolerant wrapper — the shim path is an ARGUMENT ($0), and a missing/
+// unreadable shim degrades to `cat` (identity) instead of a per-operation fatal.
+const filterCmd = (shim: string, mode: 'smudge' | 'clean') =>
+  `sh -c 'test -r "$0" && exec bash "$0" ${mode} || exec cat' '${shim.replace(/'/g, `'\\''`)}'`
+
+// plant (or refresh) the filter for the given contract files (tracked, or untracked-with-host-content —
+// pre-armed): the shim + the block content it smudges, the per-clone git config, and the attribute lines
+// binding each file to the filter. Idempotent — every write is a full replace. `contract` is the assembled
+// block body (guide + surface:system). settleIndexStat skips untracked entries (no index blob) by design.
+export function plantContractFilter(proj: string, trackedFiles: string[], contract: string): void {
+  const common = commonDirOf(proj)
+  mkdirSync(filterDir(common), { recursive: true })
+  writeFileSync(blockPath(common), contract.endsWith('\n') ? contract : `${contract}\n`)   // edge ②: the shim's smudge source, refreshed with the materialize
+  writeFileSync(shimPath(common), SHIM)
+  chmodSync(shimPath(common), 0o755)
+  git(['-C', proj, 'config', 'filter.spexcode.smudge', filterCmd(shimPath(common), 'smudge')])
+  git(['-C', proj, 'config', 'filter.spexcode.clean', filterCmd(shimPath(common), 'clean')])
+  // attribute patterns are checkout-relative, so one line serves the main checkout and every worktree.
+  const entries = trackedFiles.map((f) => `/${relative(proj, f)} filter=spexcode`).sort().join('\n')
+  mkdirSync(join(common, 'info'), { recursive: true })
+  writeManagedBlock(attributesPath(common), entries, ['# ', ''])
+  settleIndexStat(proj, trackedFiles)
+}
+
+// settle the index STAT for each file — the famous filtered-path phantom-`M`: git cannot verify a
+// clean-filtered path by stat alone (worktree size ≠ blob size by design), and `git status` reports such an
+// entry modified FOREVER without ever content-checking it (field-verified on git 2.43; `git diff` meanwhile
+// runs the filter and shows nothing; even `update-index --really-refresh` leaves it). The block-strip side of
+// a mode switch/backout leaves the same stale stat on the then-unfiltered path. `git add --renormalize`
+// re-cleans the file and refreshes the cached stat — run ONLY when the (possibly filtered) worktree already
+// EQUALS the index blob, so it is a pure stat refresh that can never stage a user's real unstaged edit (a
+// genuine edit keeps its honest `M`). Exported for dematerialize (the unplant side); plant calls it below.
+// Best-effort: an unsettled stat is cosmetic noise, never corruption.
+export function settleIndexStat(proj: string, files: string[]): void {
+  const env = { ...process.env }
+  delete env.GIT_DIR; delete env.GIT_WORK_TREE; delete env.GIT_INDEX_FILE; delete env.GIT_OBJECT_DIRECTORY
+  for (const f of files) {
+    const rel = relative(proj, f)
+    try {
+      const indexBlob = git(['-C', proj, 'rev-parse', `:${rel}`]).trim()
+      const filtered = execFileSync('git', ['-C', proj, 'hash-object', '--path', rel, '--stdin'],
+        { input: readFileSync(f), env, stdio: ['pipe', 'pipe', 'ignore'] }).toString().trim()
+      if (indexBlob === filtered) git(['-C', proj, 'add', '--renormalize', '--', rel])
+    } catch { /* best-effort */ }
+  }
+}
+
+// the full inverse (edge ③ — call AFTER the managed blocks left the working files): attribute lines out,
+// config keys unset, shim + block content removed. `<common>/spexcode/` may host other spexcode data
+// (yatsu blobs), so only OUR two files go, never the dir.
+export function removeContractFilter(proj: string): void {
+  let common: string
+  try { common = commonDirOf(proj) } catch { return }   // not a git repo → nothing was ever planted
+  removeManagedBlock(attributesPath(common), ['# ', ''], true)
+  for (const key of ['filter.spexcode.smudge', 'filter.spexcode.clean']) {
+    try { git(['-C', proj, 'config', '--unset', key]) } catch { /* not set — already clean */ }
+  }
+  rmSync(shimPath(common), { force: true })
+  rmSync(blockPath(common), { force: true })
+}
+
+// is the filter currently planted? (the assert-side probe tests use; cheap: one config read)
+export function contractFilterPlanted(proj: string): boolean {
+  try { return git(['-C', proj, 'config', 'filter.spexcode.clean']).trim().length > 0 } catch { return false }
+}

package/spec-cli/src/doctor.ts

@@ -1,9 +1,9 @@
 // @@@ spex doctor - the DIAGNOSIS surface ([[doctor]]; command renamed from `self`, which misread as the
 // tool itself / the global install). When a user launches their OWN claude/codex with no SpexCode process
-// in the launch, the workflow reaches that agent only through the files materialize() renders (the manifest
+// in the launch, the workflow reaches that agent only through the files materialize() writes (the manifest
 // in the global store; the in-tree contract blocks + hook shims + codex trust). Bare `spex doctor` answers
 // "is this agent actually governed, or silently running free?" — diagnosing that materialized contract per
-// LAYER, looping the same HARNESSES adapter materialize renders through (so claude AND codex are covered
+// LAYER, looping the same HARNESSES adapter materialize delivers through (so claude AND codex are covered
 // with no hardcoded paths). It catches the SILENT failure: a shim whose handler is missing, a PATH that
 // can't resolve `spex`, a contract that never landed. Read-only today: the bare report, `contract` (print
 // the surface:system text any agent reads), `conflicts`. install/uninstall are STAGED (noteStaged).
@@ -13,7 +13,7 @@ import { fileURLToPath } from 'node:url'
 import { execFileSync } from 'node:child_process'
 import { homedir } from 'node:os'
 import { loadSystemConfig, loadSkillConfig } from './specs.js'
-import { runtimeRoot, envSessionId, readAliasedRawRecord } from './layout.js'
+import { runtimeRoot, treeSlotDir, envSessionId, readAliasedRawRecord } from './layout.js'
 
 // this file lives at <pkgRoot>/src/self.ts, so `..` is the package root — the same derivation init.ts/
 // materialize.ts use (never a hardcoded repo path), so the git-hook template lookup survives a relocated install.
@@ -255,14 +255,20 @@ async function doctor(): Promise<number> {
     const shim = read(h.shimFile(base))
     line(`${h.id} shim`, /dispatch\.sh/.test(shim) ? `wired (${h.shimFile(base).replace(base + '/', '')})` : 'NOT wired (no dispatch shim)')
   }
+  // manifest resolution mirrors dispatch.sh: this tree's materialize slot first, then the legacy global file
+  // (a pre-slot tree's migration-window fallback) — so the doctor reads exactly what a dispatch would.
   let manifestText = ''
-  try { manifestText = read(join(runtimeRoot(base), 'hooks-manifest')) } catch { /* non-git / no store */ }
+  let manifestHome = 'tree slot'
+  try { manifestText = read(join(treeSlotDir(base), 'hooks-manifest')) } catch { /* non-git / no store */ }
+  if (!manifestText) {
+    try { manifestText = read(join(runtimeRoot(base), 'hooks-manifest')); manifestHome = 'legacy global file (pre-slot materialize — re-run `spex materialize`)' } catch { /* neither */ }
+  }
   if (!manifestText) {
     line('manifest', 'MISSING from the global store — materialize never ran (hooks fire but find no manifest)')
   } else {
     const scripts = manifestScripts(manifestText)
     const missing = scripts.filter((s) => !existsSync(join(base, s)))
-    line('manifest', `${scripts.length} handler(s) in the global store`)
+    line('manifest', `${scripts.length} handler(s) in the ${manifestHome}`)
     line('handlers', missing.length === 0 ? 'all readable in the worktree' : `${missing.length} MISSING in the worktree → those hooks SILENTLY NO-OP:`)
     for (const m of missing) L.push(`      ✗ ${m}`)
   }

package/spec-cli/src/git.ts

@@ -5,11 +5,24 @@ import { join, isAbsolute, resolve } from 'node:path'
 
 const US = '\x1f', RS = '\x1e'
 
+// @@@ bounded git children - a git child that never exits (wedged fs, a hijacked PATH git, a dead network
+// mount) must not pin its awaiter forever: [[board-cache]]'s settle guarantee starts at this seam. Every
+// shared helper passes a generous timeout (an order of magnitude above the slowest legitimate full-history
+// walk) with SIGKILL — same pattern sessions.ts's tmux/ps probes already use — so a hung child dies and the
+// call fails like any other git failure instead of hanging its caller's promise. The kill is warned loudly:
+// gitA maps failure to '', which would otherwise hide the pathology as an innocently-empty result.
+const GIT_TIMEOUT_MS = Number(process.env.SPEXCODE_GIT_TIMEOUT_MS || 120000)
+function warnIfTimedOut(e: any, args: string[]): void {
+  if (e?.signal === 'SIGKILL') console.warn(`spec-cli: git ${args.slice(0, 6).join(' ')}… killed after ${GIT_TIMEOUT_MS}ms — child never exited`)
+}
+
 // strip git's hook-exported env (GIT_DIR etc.) so every call discovers the repo from the filesystem.
 export function git(args: string[]): string {
   const env = { ...process.env }
   delete env.GIT_DIR; delete env.GIT_WORK_TREE; delete env.GIT_INDEX_FILE; delete env.GIT_OBJECT_DIRECTORY
-  return execFileSync('git', args, { encoding: 'utf8', env, stdio: ['ignore', 'pipe', 'pipe'] })
+  try {
+    return execFileSync('git', args, { encoding: 'utf8', env, stdio: ['ignore', 'pipe', 'pipe'], timeout: GIT_TIMEOUT_MS, killSignal: 'SIGKILL' })
+  } catch (e: any) { warnIfTimedOut(e, args); throw e }
 }
 
 const pexecFile = promisify(execFile)
@@ -17,18 +30,19 @@ export async function gitA(args: string[]): Promise<string> {
   const env = { ...process.env }
   delete env.GIT_DIR; delete env.GIT_WORK_TREE; delete env.GIT_INDEX_FILE; delete env.GIT_OBJECT_DIRECTORY
   try {
-    const { stdout } = await pexecFile('git', args, { encoding: 'utf8', env, maxBuffer: 1 << 24 })
+    const { stdout } = await pexecFile('git', args, { encoding: 'utf8', env, maxBuffer: 1 << 24, timeout: GIT_TIMEOUT_MS, killSignal: 'SIGKILL' })
     return stdout
-  } catch { return '' }
+  } catch (e: any) { warnIfTimedOut(e, args); return '' }
 }
 
 export async function gitTry(args: string[]): Promise<{ ok: boolean; stdout: string; stderr: string }> {
   const env = { ...process.env }
   delete env.GIT_DIR; delete env.GIT_WORK_TREE; delete env.GIT_INDEX_FILE; delete env.GIT_OBJECT_DIRECTORY
   try {
-    const { stdout, stderr } = await pexecFile('git', args, { encoding: 'utf8', env, maxBuffer: 1 << 24 })
+    const { stdout, stderr } = await pexecFile('git', args, { encoding: 'utf8', env, maxBuffer: 1 << 24, timeout: GIT_TIMEOUT_MS, killSignal: 'SIGKILL' })
     return { ok: true, stdout, stderr }
   } catch (e: any) {
+    warnIfTimedOut(e, args)
     return { ok: false, stdout: e?.stdout ?? '', stderr: e?.stderr ?? String(e?.message ?? e) }
   }
 }

package/spec-cli/src/guide.ts

@@ -36,10 +36,12 @@ the rest, you don't hand-author the spec tree or wire the dashboard yourself.
      \`spex lint\` must report 0 errors; coverage warnings are your adoption TODO (files no node claims yet).
 
 Look these up on demand — the formats an agent authors, and the settings it configures:
-  spex guide spec     the spec.md format (frontmatter + body + the rules lint enforces)
-  spex guide yatsu    the yatsu.md format (scenario schema + how loss is measured and filed)
-  spex guide config   the spexcode.json / spexcode.local.json settings (launchers, dashboard icon, lint
-                      budgets, layout) — every field, and which of the two files it belongs in`
+  spex guide spec       the spec.md format (frontmatter + body + the rules lint enforces)
+  spex guide yatsu      the yatsu.md format (scenario schema + how loss is measured and filed)
+  spex guide config     the spexcode.json / spexcode.local.json settings (launchers, dashboard icon, lint
+                        budgets, layout) — every field, and which of the two files it belongs in
+  spex guide footprint  the footprint model — what SpexCode plants in a repo, and who sees it
+                        (committed | ignored | hidden), and every migration recipe`
 
 const SPEC = `spex guide spec — the spec.md file format
 
@@ -191,12 +193,12 @@ PORTABILITY, and picking the right one is the whole discipline:
                         identity, lint budgets, launcher NAMES. "Git is the database": tracked so the
                         team shares ONE configuration.
   spexcode.local.json   GITIGNORED — host-specific, never committed. Absolute launcher paths, cert/secret
-                        paths, private-overlay mode. Layered OVER spexcode.json (see MERGE below); a
-                        targeted env override (SPEXCODE_CODEX_SERVER_CMD, …) still wins at its read site.
+                        paths. Layered OVER spexcode.json (see MERGE
+                        below); a targeted env override (SPEXCODE_CODEX_SERVER_CMD, …) still wins at its read site.
 
 Rule of thumb — is the value TRUE FOR THE PROJECT or TRUE FOR THIS MACHINE? A branch name, a dashboard
 icon, a lint budget, a launcher's name+harness are project facts → committed spexcode.json. The ABSOLUTE
-PATH of a launcher wrapper, a TLS cert path, private mode are machine facts → gitignored spexcode.local.json.
+PATH of a launcher wrapper or a TLS cert path are machine facts → gitignored spexcode.local.json.
 Both files are optional; omit any field to take its default, except \`sessions.defaultLauncher\` when using
 \`spex new\` or the dashboard without an explicit launcher choice.
 
@@ -292,6 +294,13 @@ the guard (the flag is the proof of intent). Reads point anywhere.
   issues.enabled      the issues-workflow on/off switch (default ON). OFF silences the post-merge nudge and
                       hides the dashboard view; the CLI toggle is \`spex issues on|off\`.
 
+── FORGE (spexcode.json — which forge this repo's remote is; a project fact, so committed) ──
+  forge.host          explicit forge host id ('github' | 'gitlab' | …) overriding the automatic derivation.
+                      Normally OMIT it: spec-forge resolves the host from the origin remote's hostname —
+                      github.com → github, a gitlab/self-hosted remote → gitlab — and only an ambiguous
+                      self-hosted domain the heuristic misreads needs the override. A resolved host with no
+                      registered driver degrades to an EMPTY forge slice (local issues still work, no error).
+
 ── LINT (spexcode.json — a top-level "lint" key; budgets are portable, so committed only) ──
   lint.governedRoots       dirs whose source files must each be governed by a spec (coverage).
                            '.' = the whole project (only git-TRACKED files). Default
@@ -314,37 +323,84 @@ Example — govern your own source dir and loosen the altitude budget:
   preset      the SELECTED init preset — which cumulative .config tier \`spex init\` seeds (default
               'default'; seed-time only, read by init.ts).
   harnesses   which harness targets \`spex materialize\` delivers into — native ids ("claude"|"codex") or a
-              { "plugin": "<folder>" } bundle. Default (omitted): all native harnesses.
-  private     (spexcode.local.json ONLY) private-overlay mode — when true, \`spex materialize\` leaves ZERO
-              trace in the host's TRACKED files: managed ignore entries go to .git/info/exclude and any
-              tracked contract file is marked skip-worktree. Trades away git-derived spec version history.
-              A HOST decision → never the committed file. See PRIVATE MODE below.
-
-── PRIVATE MODE (default ⇄ private — the two delivery modes) ──
-DEFAULT mode (private absent/false): materialize commits .spec + spexcode.json and writes its ignore list as
-a managed block in the TRACKED .gitignore — transparent, but every collaborator sees it. PRIVATE mode
-(spexcode.local.json { "private": true }): the SAME contract reaches the agent, but the ignore list goes to
-the per-clone .git/info/exclude and any host-tracked CLAUDE.md/AGENTS.md is skip-worktree'd — so \`git status\`
-stays clean and nothing enters shared history.
-
-  Switch:   edit spexcode.local.json  ({ "private": true } on / false or remove = off), then \`spex materialize\`
-            (the hook gate also re-runs it on the next agent turn).
-  Reversible + idempotent: the two modes fully CANCEL OUT. default→private→default (or private→default→private)
-            converges to the SAME on-disk state as running that mode once — each mode re-asserts the inverse of
-            the other (exclude block ⇄ .gitignore block, skip-worktree set ⇄ cleared). Switch order never
-            matters; running a mode twice changes nothing.
-
-MANUAL STEP (the only one materialize can't do for you — it also PRINTS this when needed):
-  .git/info/exclude hides UNTRACKED paths only. If you adopted DEFAULT mode first, .spec + spexcode.json are
-  already committed, so private mode can't hide them until you un-track them ONCE:
-      git rm -r --cached .spec spexcode.json     # keeps the files on disk, stops tracking them
-  (then commit that on your branch). A private-from-the-start adoption never needs this.
-
-FOOTGUN (skip-worktree): a host-tracked CLAUDE.md/AGENTS.md is skip-worktree'd in private mode, so a later
-  \`git pull\` that touches it can complain. Fix: flip back to DEFAULT mode (or \`git update-index
-  --no-skip-worktree CLAUDE.md AGENTS.md\`), pull, then re-materialize.`
-
-const TOPICS: Record<string, string> = { spec: SPEC, yatsu: YATSU, config: CONFIG }
+              { "plugin": "<folder>" } bundle. Default (omitted): all native harnesses. PERSISTENT and
+              git-transactional: the edit takes effect at the next git-native materialize anchor (the commit
+              that carries it, a checkout/merge that receives it, or a manual \`spex materialize\`) — a
+              deselected harness's artifacts are pruned by that pass.
+  render      RETIRED (the old three-word footprint vote) — ignored with a loud notice. Materialized
+              artifacts are never tracked; there is exactly one residence behavior. Remove the field.
+              \`spex guide footprint\`.
+  private     RETIRED (old private-overlay toggle) — ignored with a loud notice, same as \`render\`; its
+              data-untrack semantics are gone. See \`spex guide footprint\` MIGRATIONS.`
+
+const FOOTPRINT = `spex guide footprint — what SpexCode plants in a repo, and who sees it (no vote — one behavior)
+
+SpexCode claims software engineering's HEAD (the recording of intent) and TAIL (the storage of
+measurement) and leaves the MIDDLE — construction — to the harness/agent/test framework; freshness
+stitches the two ends into a closed loop. The footprint follows: the head+tail (.spec, spexcode.json,
+readings) is the ASSET and lives in git like source; everything else is derived wiring or a machine fact.
+Materialized artifacts carry no facts, so they are NEVER tracked — the old render vote is retired; there
+is exactly one residence behavior, decided per KIND (and, for a contract file, by its live CONTENT).
+
+── THE FOUR KINDS (all fixed) ──
+  spec data       .spec/ (incl .config/) + spexcode.json — ALWAYS tracked. Git is the database; there is
+                  deliberately NO way to say "untrack the spec" in this schema.
+  machine facts   spexcode.local.json, the hook shims (.claude/settings.json, .codex/hooks.json), plugin
+                  bundles — NEVER tracked; always in the per-clone exclude.
+  artifacts       the CLAUDE.md/AGENTS.md contract blocks + materialized skills/agents — derived, NEVER
+                  tracked; hidden via .git/info/exclude. The host's tracked .gitignore is never touched.
+  run residue     .worktrees/, the global store (~/.spexcode), .git/spexcode blobs — never tracked;
+                  out-of-tree, or exclude-ruled where in-tree.
+
+── A CONTRACT FILE'S RESIDENCE IS A LIVE CONTENT FACT (re-judged at every materialize) ──
+  host-tracked          → the clean/smudge content filter: the repo keeps the pristine host prose, your
+                          working tree carries prose + block, status stays clean.
+  untracked, wholly ours→ one exclude entry. The exclude is the ignored-bit DECLARATION the rest of git
+                          consults (checkout may overwrite, clean -fd spares, status/add -A/stash silent).
+  untracked, YOUR prose → the exclude entry is withdrawn (hiding user content would be data-loss shaped)
+    entered the file      and the clean filter is pre-armed: the file shows honestly as untracked, and
+                          IF you choose to \`git add\` it, the block is stripped automatically — tracking
+                          is always your act; SpexCode never stages or commits anything for you.
+
+── THE GIT-NATIVE ANCHORS (no harness event ever triggers a materialize) ──
+  spex init / spex materialize / session-worktree creation — the explicit passes;
+  pre-commit    the correctness anchor: an UNCONDITIONAL materialize (masks provably fresh at the only
+                moment history is written) + staged-index surgery — a staged blob carrying the sentinel
+                block is cleaned IN PLACE (partial staging survives; source is the staged blob), a
+                HEAD-untracked generated artifact is unstaged. Repairs and proceeds, never rejects.
+  post-checkout/post-merge   freshness anchors: .spec/.config edits are git-transactional — they take
+                effect at the commit/checkout/merge that carries them, like any other source change.
+An environment with no spex-planted hooks (CI, a cloud agent's fresh clone, a teammate who hasn't
+installed) simply runs \`spex materialize\` in its setup step — there is no committed-artifact mode.
+TRACK ≠ PUSH: none of this ever touches remotes; where commits GO is branch/remote policy.
+
+── GUARANTEES (the forgetting law) ──
+materialize(P₂) ∘ materialize(P₁) = materialize(P₂): every materialize first ERASES all landing points by
+SpexCode's own identity stamps, then re-asserts — legacy states (a .gitignore managed block, a committed
+artifact, the retired vote's homes) are forgotten by the same pass. \`spex uninstall\` is the empty
+materialize plus the global store: a total backout that never touches your .spec/.config or prose. Fresh
+clones and session worktrees are self-sufficient: data by checkout, materialized artifacts by
+re-materialize, the machine snapshot (spexcode.local.json) by copy.
+
+── THE CONTENT FILTER (mixed-content contract files) ──
+Per-clone only — git config filter.spexcode.* + .git/info/attributes + a shim under .git/spexcode/ —
+planted where mixed content exists or is imminent (tracked, or untracked with your prose). clean strips
+the sentinel block (history never sees it); smudge re-injects it on checkout. A missing shim degrades to
+identity (never a git fatal). Your own edits to the prose still show as real modifications; only the
+block is invisible to git.
+
+── MIGRATIONS ──
+  render: "..." (retired)   remove the field from spexcode.json / spexcode.local.json — it is ignored
+                            with a loud notice. A previously COMMITTED artifact heals at your next commit
+                            touching it (pre-commit strips the block from the staged blob); or run
+                            \`spex materialize\` + commit the block's removal once.
+  private: true (retired)   same — remove it; its data-untrack semantics are long gone.
+  legacy untracked spec     track the sources once:  git add .spec spexcode.json  (commit on your branch)
+                            WARNING: tracking is not retroactive secrecy — history already pushed
+                            elsewhere cannot be recalled.
+  back out entirely         \`spex uninstall\` (add --hooks to also remove the spexcode git hooks).`
+
+const TOPICS: Record<string, string> = { spec: SPEC, yatsu: YATSU, config: CONFIG, footprint: FOOTPRINT }
 
 // every guide page ends by naming the OTHER help layer, so a reader never dead-ends here: guide is
 // the skill layer (workflows · formats · settings); command usage lives in help.ts's two layers.

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

@@ -2,9 +2,9 @@ import { HARNESSES, type Harness, type HarnessId } from './harness.js'
 
 // @@@ harness-select - the DECLARATIVE choice of WHICH harness targets `spex materialize` delivers the
 // SpexCode system into. The selection is persistent config (spexcode.json's `harnesses`), NOT a one-shot
-// flag, because materialize is driven by a content-hash gate (re-run on every .config edit), so the intent
+// flag, because materialize re-runs at every git-native anchor ([[commit-surgery]]), so the intent
 // must live where every re-materialize can read it. This module owns ONLY the vocabulary + validation; the
-// per-harness write/clean mechanics live on the [[harness-adapter]], the render loop on [[harness-delivery]].
+// per-harness write/clean mechanics live on the [[harness-adapter]], the materialize loop on [[harness-delivery]].
 
 // a resolved DELIVERY TARGET. Either a NATIVE harness (claude/codex — its adapter writes shims/contract/trust
 // directly), or a PLUGIN bundle dropped into a host-agent-scanned folder. The plugin EMITTER is a later node;

package/spec-cli/src/harness.ts

@@ -8,6 +8,7 @@ import { promisify } from 'node:util'
 import { fileURLToPath } from 'node:url'
 import { claudeSlashCommands, codexSlashCommands, type SlashCommand } from './slash-commands.js'
 import { runtimeRoot, mainCheckout, readConfig } from './layout.js'
+import { git } from './git.js'
 
 // @@@ harness-adapter - the ONE seam between SpexCode and the coding-agent harness (Claude Code, Codex, …).
 // Every harness-specific fact lives behind THIS interface with one implementation per harness; product code
@@ -19,7 +20,7 @@ import { runtimeRoot, mainCheckout, readConfig } from './layout.js'
 // dispatch.sh's first argument (`bash <dispatch> <id> <Event>`). dispatch.sh exports SPEXCODE_HARNESS, so a
 // hook subprocess learns its harness deterministically from the shim that wired it — never from guessing the
 // payload shape. On the TS side the harness is derived from the selected launcher or ALL adapters at once
-// (materialize renders every harness's artifacts).
+// (materialize writes every harness's artifacts).
 
 export type HarnessId = 'claude' | 'codex'
 export type HarnessLivenessRecord = { session: string; harnessSessionId?: string | null }
@@ -158,7 +159,7 @@ export interface Harness {
 // its existing importers.
 export type DispatchResult = { ok: boolean; error?: string }
 export type HarnessDeliveryRecord = { session: string; worktreePath?: string; harnessSessionId?: string | null; runtimeDir?: string }
-// the on-demand surface artifacts a materialize render wrote, by node NAME — so clean() knows EXACTLY which
+// the on-demand surface artifacts a materialize pass wrote, by node NAME — so clean() knows EXACTLY which
 // skill subdirs / agent files are SpexCode's to remove (name-scoped, never a blind wipe of a dir the user may
 // also populate). materialize passes the live skill/agent node names; clean reconstructs the same paths.
 export type HarnessArtifacts = { skills: readonly string[]; agents: readonly string[] }
@@ -770,16 +771,21 @@ export function removeManagedBlock(file: string, comment: readonly [string, stri
   // remove ONLY our block plus the blank lines writeManagedBlock inserted around it; do NOT normalize the
   // user's OWN whitespace elsewhere — this must leave every other byte intact so it is a faithful INVERSE of
   // writeManagedBlock's append. A global `\n{3,}→\n\n` collapse used to sit here and mutated pre-existing
-  // blank-line runs in the user's file, which broke the private⇄default round-trip ([[private-overlay]]):
-  // default→private→default left a spurious one-line diff on a .gitignore that had internal blank lines.
-  const out = cur.replace(re, '\n').replace(/^\n+/, '')
+  // blank-line runs in the user's file, which broke the policy round-trip ([[residence]]): a mode flip
+  // and back left a spurious one-line diff on a .gitignore that had internal blank lines. The leading-newline
+  // strip is GUARDED the same way: it exists only for a block sitting at the TOP of the file (whose '\n'
+  // replacement would otherwise become a leading blank) — a host file that BEGINS with its own blank lines
+  // keeps them ([[content-filter]]'s invariant, same bug class as the shim's old unconditional strip).
+  const atTop = (re.exec(cur)?.index ?? -1) === 0
+  const replaced = cur.replace(re, '\n')
+  const out = atTop ? replaced.replace(/^\n+/, '') : replaced
   if (deleteIfEmpty && !out.trim()) { rmSync(file, { force: true }); return }
   writeFileSync(file, out)
 }
 
 // the shim for one harness: every event → `SPEX='…' bash <dispatch> <harnessId> <Event>`. The harness id is
 // baked in so dispatch.sh can export SPEXCODE_HARNESS (the detector for the shell side). SPEX is inherited by
-// the cli-needing handlers + the gate's `spex materialize`.
+// the cli-needing handlers.
 function buildShim(id: HarnessId, events: readonly string[], dispatch: string, spex: string): { json: string; cmd: (e: string) => string } {
   const cmd = (e: string) => `SPEX='${spex}' bash ${dispatch} ${id} ${e}`
   const hooks: Record<string, unknown> = {}
@@ -874,6 +880,11 @@ function removeCodexTrust(proj: string): void {
   writeFileSync(file, cleaned ? `${cleaned}\n` : '')
 }
 
+// is this file git-tracked in proj? (guards cleanHarness's deleteIfEmpty; env-stripped git, never throws)
+function isTrackedFile(proj: string, f: string): boolean {
+  try { git(['-C', proj, 'ls-files', '--error-unmatch', f]); return true } catch { return false }
+}
+
 // @@@ cleanHarness - the shared clean: the inverse of materialize's per-harness write, expressed PURELY
 // through the adapter's own path methods so it can never drift from what write put there. Each step is
 // surgical, gated on a SpexCode identity stamp: the contract files carry the managed-block sentinels; the shim
@@ -882,7 +893,10 @@ function removeCodexTrust(proj: string): void {
 // blocks and our own named products — never a user's CLAUDE.md/AGENTS.md prose, a hand-made settings.json, or
 // a sibling skill/agent the user added, and NEVER any .spec data.
 function cleanHarness(h: Harness, proj: string, arts: HarnessArtifacts): void {
-  for (const f of h.contractFiles(proj)) removeManagedBlock(f, ['<!-- ', ' -->'], true)
+  // deleteIfEmpty ONLY for an UNTRACKED contract file: a wholly-ours generated file goes; a HOST-TRACKED file
+  // that carried nothing but our block (an empty committed CLAUDE.md we folded into) is stripped back to its
+  // pristine emptiness but never deleted — deleting a tracked file would surface as a `D` in the host's status.
+  for (const f of h.contractFiles(proj)) removeManagedBlock(f, ['<!-- ', ' -->'], !isTrackedFile(proj, f))
   const shim = h.shimFile(proj)
   if (existsSync(shim) && readFileSync(shim, 'utf8').includes('dispatch.sh')) rmSync(shim, { force: true })
   const anchor = h.worktreeHookAnchor(proj)   // the linked-worktree anchor copy, same identity gate as the shim
@@ -1031,7 +1045,7 @@ export const codexHarness: Harness = {
   resumeArg: (rec) => (rec.harnessSessionId ? `--resume ${rec.harnessSessionId}` : ''),
 }
 
-// every adapter — materialize iterates this to render each harness's artifacts in one pass.
+// every adapter — materialize iterates this to write each harness's artifacts in one pass.
 export const HARNESSES: readonly Harness[] = [claudeHarness, codexHarness]
 
 // the legacy/default adapter for old records and config defaults. New launches derive harness from a launcher.