spexcode 0.2.5 → 0.2.7

package/spec-cli/src/guide.ts

@@ -40,7 +40,7 @@ Look these up on demand — the formats an agent authors, and the settings it co
   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 share-axis model — what SpexCode plants in a repo, the render policy
+  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
@@ -176,7 +176,7 @@ reading (\`--last\` makes that explicit; repeat to peel junk back one filing at
 
 THE SCOREBOARD: readings live in yatsu.evals.ndjson beside the yatsu.md — one JSON line per measurement
 (a second git-as-database axis). Freshness is derived live from git: a reading goes STALE when a governed
-code file, the scenario (the yatsu.md), or the evaluator moves since it was filed.
+code file or the scenario (the yatsu.md) moves since it was filed.
   spex yatsu scan [--changed]   blind spots: yatsu-schema (malformed) · yatsu-drift (stale) ·
                                 yatsu-missing (never measured) · yatsu-uncovered (governed source, no yatsu.md) ·
                                 yatsu-owners (a file governed by > maxOwners scenarios — split it)
@@ -193,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, a personal "render": "hidden" vote. Layered OVER spexcode.json (see MERGE
+                        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, a personal render:hidden 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.
 
@@ -324,77 +324,87 @@ Example — govern your own source dir and loosen the altitude budget:
               '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. PERSISTENT and
-              self-healing: an edit moves the hook gate's key, so the next harness event re-renders under
-              the new set (a deselected harness's artifacts are pruned) — no manual materialize needed.
-  render      the footprint vote: where the machine-independent RENDERS (CLAUDE.md/AGENTS.md contract
-              blocks, .claude/.codex skills + agents) sit relative to the shared repo. One of
-              "committed" | "ignored" (default) | "hidden". "committed" is a PROJECT fact → spexcode.json;
-              "hidden" is a HOST/person fact → spexcode.local.json. The spec DATA (.spec, spexcode.json)
-              has NO knob — always tracked. Full model + migration recipes: \`spex guide footprint\`.
-  private     RETIRED (old private-overlay toggle) — read as "render": "hidden" with a loud migration
-              notice; its data-untrack semantics are gone. See \`spex guide footprint\` MIGRATIONS.`
-
-const FOOTPRINT = `spex guide footprint — the share-axis model (what SpexCode plants in a repo, and who sees it)
+              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.`
+
+const FOOTPRINT = `spex guide footprint — what SpexCode plants in a repo, and who sees it (one fixed behavior per kind)
 
 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.
-ONE axis — "who sees this artifact in the shared repo?" — is answered per KIND, never per usage mode.
+Materialized artifacts carry no facts, so they are NEVER tracked — there is exactly one residence
+behavior, decided per KIND (and, for a contract file, by its live CONTENT).
 
-── THE FOUR KINDS (three are fixed; one votes) ──
+── 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 ignore rules, whatever those rules' home.
-  renders         the CLAUDE.md/AGENTS.md contract blocks + rendered skills/agents — machine-independent,
-                  derived from the spec tree. THE one voted class: the \`render\` field (see below).
+                  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 ignore-ruled where in-tree.
-
-── THE VOTE: render = "committed" | "ignored" | "hidden" ──
-  committed   renders are ordinary committed files; their entries LEAVE the ignore block (machine facts
-              stay ignored). The contract reaches teammates/CI who never installed SpexCode — the harness
-              discovers the committed file natively. Pick for a fully-adopted team. → spexcode.json.
-  ignored     (default) renders are generated + gitignored via the managed block in the TRACKED
-              .gitignore — the team sees the RULE, never the products. NOTE: a contract file the host
-              ALREADY TRACKS cannot be ignored — it stays visibly dirty, your prompt to pick committed
-              or hidden.
-  hidden      zero repo footprint: the same managed block lives in the per-clone .git/info/exclude, and a
-              HOST-TRACKED CLAUDE.md/AGENTS.md is covered by a per-clone git clean/smudge content filter —
-              the repo keeps the pristine host prose, your working tree carries prose + contract block,
-              and git status stays clean. Pick to dogfood on a repo you don't own. → spexcode.local.json.
-The ignore rules are themselves a render artifact, so their HOME follows the same vote — one axis, no
-second mechanism. TRACK ≠ PUSH: the vote never touches remotes; where commits GO is branch/remote policy.
-Vote at adoption in one step: \`spex init --render <word>\` (committed/ignored → spexcode.json, hidden →
-spexcode.local.json). Until an explicit vote is set, init/materialize print a one-time decision hint
-whenever a host-TRACKED contract file carries the block — the "mystery M" explained at first sight.
+                  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 render first ERASES all landing points by
-SpexCode's own identity stamps, then re-asserts the current policy — so switching render values (or
-harness sets) in ANY order, any number of times, converges; running one policy twice changes nothing.
-\`spex uninstall\` is the empty policy 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, renders
-by re-render (init/materialize/the hook gate), the machine snapshot (spexcode.local.json) by copy.
-
-── THE CONTENT FILTER (hidden + a host-tracked contract file) ──
-Per-clone only — git config filter.spexcode.* + .git/info/attributes + a shim under .git/spexcode/ — and
-planted ONLY when the contract file is actually tracked. 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 file's prose still show as real modifications; only the block is invisible to git.
+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) 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.
+
+── PRIVATE LOCAL NODES (manual posture — works today) ──
+Spec data is always tracked, but tracked WHERE is yours to choose: to keep a node off the shared
+remote, give it a different git HOME instead of untracking it. The manual recipe:
+  1. create the node dir under .spec/ as usual (spec.md and friends);
+  2. add the dir's path to .git/info/exclude — per-clone, so the shared repo never sees it;
+  3. inside the dir, \`git init --separate-git-dir\` pointing somewhere under the main repo's .git/
+     (e.g. .git/spexcode/<name>.git) — the dir then holds only a one-line .git pointer file, so the
+     spec loader never walks an object store;
+  4. commit the node's changes through that inner repo.
+The effect, honestly: filesystem-derived surfaces see the node (board, search, lint); git-derived
+views are blind to it (version count, the history tab, drift), and a dispatched worker's worktree
+checkout does not contain it. Those gaps are what the pending spec-local design (a first-class
+private overlay root) closes — not built yet. Cautions: \`git clean -fdx\` in the outer repo deletes
+the inner repo along with the dir, so off-machine backup means giving the INNER repo its own private
+remote; and taking the node public later is a migration (move it into the shared tree and commit),
+not a flag flip.
 
 ── MIGRATIONS ──
-  private: true (retired)   → replace with { "render": "hidden" } in spexcode.local.json. materialize
-                            reads the old flag as hidden and prints this recipe until you migrate.
-  legacy untracked spec     the retired mode also untracked .spec + spexcode.json. Track them once:
-  (untrack-private)             git add .spec spexcode.json     # then commit on your branch
+  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.
-  hidden → committed/ignored  just edit \`render\` — the hook gate re-renders on the very next harness
-                            event (the gate key covers spexcode.json/.local), or run \`spex materialize\`
-                            to apply immediately; the erase phase unplants the filter/exclude block in
-                            the same pass. Narrowing \`harnesses\` self-heals the same way.
   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 }

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

@@ -20,7 +20,7 @@ import { git } from './git.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 }
@@ -159,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[] }
@@ -179,24 +179,33 @@ export const rvSock = (id: string) => join(tmpdir(), `spexcode-rv-${id}.sock`)
 // A crashed/killed claude can leave its rvSock FILE on disk (a unix-domain socket path is NOT auto-unlinked on
 // an unclean exit), so the old `existsSync(rvSock)` read a DEAD pane as `online` for as long as the stale file
 // lingered — the incident's "dead pane stuck `working` for 30+ min". The honest signal is a live LISTENER:
-// connect() to the socket. A real claude is accepting → connects; a stale file → ECONNREFUSED (instant); an
-// absent file → ENOENT (instant). So the common cases cost no waiting; the short timeout only bounds the
-// pathological file-present-but-listener-wedged case (then treated as not-live). Never throws.
-export function rendezvousListening(id: string, timeoutMs = 800): Promise<boolean> {
+// connect() to the socket. The verdict is TRI-STATE, because only two probe results actually PROVE anything:
+//   'live'  — the connect completed: a real claude is accepting.
+//   'dead'  — ECONNREFUSED (a stale file nothing listens on) / ENOENT (no file): death PROVEN, instantly.
+//   'unproven' — the probe itself failed to conclude: a TIMEOUT (under load the prober's event loop fires the
+//     expired timer before the pending connect event — the thrashed-backend incident where every live worker
+//     read offline in one board answer), or EAGAIN (the listen backlog is FULL, which proves a listener is
+//     alive-but-busy, the opposite of dead). Collapsing these into 'dead' is how a load spike masqueraded as
+//     a graveyard (issue #40); the caller must render unproven death as `unknown`, never `offline`.
+// The common cases cost no waiting (connect/refuse/absent are instant); the short timeout only bounds the
+// wedged/thrashed path. Never throws.
+export type ListenerProbe = 'live' | 'dead' | 'unproven'
+const PROVEN_DEAD = new Set(['ECONNREFUSED', 'ENOENT'])
+export function rendezvousListening(id: string, timeoutMs = 800): Promise<ListenerProbe> {
   return new Promise((resolve) => {
     let settled = false
     let c: ReturnType<typeof createConnection> | undefined
-    const done = (v: boolean) => {
+    const done = (v: ListenerProbe) => {
       if (settled) return
       settled = true
       clearTimeout(timer)
       try { c?.destroy() } catch { /* */ }
       resolve(v)
     }
-    const timer = setTimeout(() => done(false), timeoutMs)
-    try { c = createConnection({ path: rvSock(id) }) } catch { return done(false) }
-    c.on('connect', () => done(true))
-    c.on('error', () => done(false))   // ECONNREFUSED (stale file) / ENOENT (gone) — both mean no live agent
+    const timer = setTimeout(() => done('unproven'), timeoutMs)
+    try { c = createConnection({ path: rvSock(id) }) } catch { return done('unproven') }
+    c.on('connect', () => done('live'))
+    c.on('error', (e) => done(PROVEN_DEAD.has((e as NodeJS.ErrnoException).code ?? '') ? 'dead' : 'unproven'))
   })
 }
 // The app-server Unix socket MUST live on a SHORT, sun_path-safe path — NOT nested under the project runtime
@@ -771,7 +780,7 @@ 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 policy round-trip ([[render-policy]]): a mode flip
+  // 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
@@ -785,7 +794,7 @@ export function removeManagedBlock(file: string, comment: readonly [string, stri
 
 // 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> = {}
@@ -1045,7 +1054,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.

package/spec-cli/src/help.ts

@@ -77,7 +77,7 @@ session list. Identical to GET /api/board; needs the backend (spex serve) reacha
        spex guide spec       the spec.md file format + every lint rule
        spex guide yatsu      the yatsu.md scenario format + how loss is measured and filed
        spex guide config     every spexcode.json / spexcode.local.json field, and which file it belongs in
-       spex guide footprint  the share-axis model: the render vote (committed|ignored|hidden) + migrations
+       spex guide footprint  the footprint model: never-tracked artifacts, exclude + content filter, anchors
 
 guide is the SKILL layer — workflows and formats. Command usage lives here in help
 (\`spex help <cmd>\`); guide carries what the commands assume you know.`,
@@ -187,6 +187,9 @@ a node/<id> branch links its PR for free). Read-only — git/.spec stays the sin
 
 Creates a session: node branch + worktree + a launched agent carrying your prompt (= session new).
 Give it ONLY its task — the dev-flow contract reaches it through the materialized system prompt.
+--node <id> (or the prompt's first [[id]] mention, same effect) binds the session to that node:
+branch name node/<id>-<shortid>, board attribution, and one appended line with the node's spec.md
+path when the node exists. With neither, the session is bound to no node.
 --prompt-file <path> reads the prompt from a file (- = stdin), so a long multi-paragraph prompt never
 fights shell quoting; it is exclusive with the inline prompt (both given = error), and an unreadable
 or empty file refuses the launch.
@@ -313,15 +316,14 @@ ${ROUTING_NOTE}`,
 
   // ── install & serve (operator) ────────────────────────────────────────────
   init: {
-    line: 'init [dir]            adopt SpexCode on a repo: seed .spec + hooks + materialize  [--preset name] [--render word]',
-    body: `Usage: spex init [dir=cwd] [--preset default|careful] [--render committed|ignored|hidden]
+    line: 'init [dir]            adopt SpexCode on a repo: seed .spec + hooks + materialize  [--preset name]',
+    body: `Usage: spex init [dir=cwd] [--preset default|careful]
 
 Scaffolds adoption in one shot: seeds a starter .spec tree (project root + .config plugins), plants
 spexcode.json, installs the git hooks, and materializes the harness artifacts (contract block +
 shims). Additive — never overwrites your files. --preset picks the .config plugin tier (cumulative).
---render casts the one-time render-policy vote at adoption (committed → spexcode.json, hidden →
-spexcode.local.json; an unknown word fails loud) — without it, a host-tracked CLAUDE.md/AGENTS.md
-prints a one-time decision hint instead (see spex guide footprint).`,
+Footprint is fixed: materialized artifacts are never tracked — hidden via the per-clone .git/info/exclude, with
+a tracked/mixed CLAUDE.md/AGENTS.md covered by the clean/smudge filter (see spex guide footprint).`,
     see: 'spex guide (the full setup workflow) · spex uninstall (the inverse) · spex lint (adoption TODO)',
   },
   uninstall: {
@@ -329,30 +331,32 @@ prints a one-time decision hint instead (see spex guide footprint).`,
     body: `Usage: spex uninstall [dir=cwd] [--hooks]
 
 Removes every SpexCode-GENERATED artifact (harness shims · contract blocks · trust entries ·
-.gitignore block · global store · plugin bundle) and never your .spec/.config data or your own
+exclude/ignore blocks · global store · plugin bundle) and never your .spec/.config data or your own
 prose. Git hooks are preserved unless --hooks.`,
     see: 'spex init (re-adopt later — your .spec survives)',
   },
   materialize: {
-    line: 'materialize           re-render the harness artifacts (contract block · shims) for cwd’s project',
+    line: 'materialize           re-materialize the harness artifacts (contract block · shims) for cwd’s project',
     body: `Usage: spex materialize
 
-Renders the surface:system config nodes into the managed <!-- spexcode --> block of
-CLAUDE.md/AGENTS.md plus the .claude/.codex shims, and prints the content hash. Run it after a
-toolchain update or any .config edit that the automatic dispatch gate hasn't picked up — these
-artifacts are generated and gitignored, so they never arrive via git.`,
-    see: 'spex doctor (verify the render actually reaches an agent)',
+Materializes the surface:system config nodes into the managed <!-- spexcode --> block of
+CLAUDE.md/AGENTS.md plus the .claude/.codex shims, and prints the content hash. The materialize anchors on
+git-native events only (init · this verb · session-worktree creation · the pre-commit/post-checkout/
+post-merge hooks) — run it by hand after a toolchain update, or in the setup step of any clone that
+has no spex-planted hooks yet (CI, a cloud agent): the artifacts are generated and excluded, so they
+never arrive via git.`,
+    see: 'spex doctor (verify the materialized artifacts actually reach an agent)',
   },
   doctor: {
     line: 'doctor                diagnose whether the workflow actually reaches this agent — per-layer, per-harness',
     body: `Usage: spex doctor             per-layer coverage report: preconditions · git-hook floor · contract ·
-                               hooks + handler existence · backend — for every harness materialize renders
+                               hooks + handler existence · backend — for every harness materialize delivers to
        spex doctor contract    print the composed surface:system text any agent here reads
        spex doctor conflicts   detect double-delivery (loose artifacts beside the managed ones)
 
 Run it when a worker seems to be missing its contract or hooks — it names the broken layer and the
 repair, instead of you diffing materialized files by hand.`,
-    see: 'spex materialize (re-render the artifacts doctor checks)',
+    see: 'spex materialize (re-materialize the artifacts doctor checks)',
   },
   serve: {
     line: 'serve                 run the API backend (default :8787)  [--port N] [--public --password pw]',
@@ -381,10 +385,12 @@ so bind wide only on a network you trust (for the internet, use \`spex serve --p
   // ── plumbing ──────────────────────────────────────────────────────────────
   internal: {
     line: '',   // deliberately not on the map
-    body: `Usage: spex internal <trunk | codex-launch | codex-turn>
+    body: `Usage: spex internal <trunk | commit-surgery | refresh-footprint | codex-launch | codex-turn>
 
 Machine plumbing — called by generated hooks and launch scripts, never typed by a human or agent:
-  trunk         print the resolved source-of-truth branch (the pre-commit main-guard captures it)
+  trunk             print the resolved source-of-truth branch (the pre-commit main-guard captures it)
+  commit-surgery    pre-commit footprint anchor: unconditional materialize + staged-index repair
+  refresh-footprint quiet materialize — the post-checkout/post-merge freshness anchor
   codex-launch  <sock> <cwd> [prompt…]   backend-owned codex thread/start + first turn (launch script)
   codex-turn    <sock> <threadId> <text…>  fire a follow-up turn on an owned thread (tests/scripts)
 

package/spec-cli/src/init.ts

@@ -53,27 +53,9 @@ function resolveHooksDir(dir: string): string | null {
   }
 }
 
-export async function specInit(targetArg: string | undefined, presetArg?: string, renderArg?: string): Promise<void> {
+export async function specInit(targetArg: string | undefined, presetArg?: string): Promise<void> {
   const targetDir = resolve(targetArg ?? process.cwd())
 
-  // the one-step render vote (`--render <committed|ignored|hidden>`, see [[render-policy]]): validated up
-  // front against the same vocabulary materialize enforces (resolveRenderPolicy — an unknown word fails loud
-  // BEFORE anything is written), applied to the config files below, and honored by this run's materialize.
-  const render = renderArg?.trim()
-  if (renderArg !== undefined) {
-    if (!render) {
-      console.error('spex init: --render needs a value — the render axis has three words: committed | ignored | hidden (see `spex guide footprint`)')
-      process.exit(1)
-    }
-    try {
-      const { resolveRenderPolicy } = await import('./materialize.js')
-      resolveRenderPolicy({ render })
-    } catch (e) {
-      console.error(`spex init: ${(e as Error).message}`)
-      process.exit(1)
-    }
-  }
-
   // the preset the NEW adopter gets — `--preset <name>` wins, else an existing target spexcode.json's
   // `preset` field, else the lean `default`. Validated loudly against the chain (an unknown name would
   // otherwise seed silently). A non-default tier stacks its template package on top of the default set below.
@@ -129,19 +111,6 @@ export async function specInit(targetArg: string | undefined, presetArg?: string
     console.log(`✓ planted spexcode.json — lint.governedRoots starts as ${roots} (the whole git-tracked tree, tests excluded); curate explicit roots later if you want a narrower graph`)
   }
 
-  // 1c. apply the --render vote where the axis says each word lives ([[render-policy]]): committed/ignored
-  // are project facts → the committed spexcode.json; hidden is a host/person fact → the gitignored
-  // spexcode.local.json. An explicit flag is an explicit instruction, so it sets the field even in a
-  // pre-existing config file (the ONE deliberate exception to "existing files are left untouched").
-  if (render) {
-    const home = render === 'hidden' ? 'spexcode.local.json' : 'spexcode.json'
-    const p = join(targetDir, home)
-    const cur = readJsonConfig(p)   // fails loud on a malformed existing file, {} when absent
-    cur.render = render
-    writeFileSync(p, JSON.stringify(cur, null, 2) + '\n')
-    console.log(`✓ render policy voted: "${render}" → ${home}`)
-  }
-
   // validate the harness DELIVERY TARGET set ([[harness-select]]) up front: a bad `harnesses` set (plugin +
   // native, or a plugin with no folder) must fail LOUD here, not be silently swallowed by the materialize
   // try/catch below. A fresh starter spexcode.json omits the field (defaults to all natives), so this only
@@ -175,22 +144,18 @@ export async function specInit(targetArg: string | undefined, presetArg?: string
     if (installed.length) console.log(`✓ installed git hooks (${installed.join(', ')}) → ${hooksDir}`)
   }
 
-  // 2c. RENDER the harness-discovered artifacts so a USER-self-launched claude/codex works with zero further
+  // 2c. MATERIALIZE the harness-discovered artifacts so a USER-self-launched claude/codex works with zero further
   // steps: the hook manifest (in the GLOBAL per-project store, not the worktree), the AGENTS.md/CLAUDE.md
   // <spexcode> contract block (user content preserved), the .claude/.codex shims, and the Codex trust (global,
   // scoped) so codex self-launch is prompt-free. Runs with cwd = the target so the loaders read the just-seeded
-  // .config. Idempotent — the dispatch.sh gate keeps it fresh thereafter on every .config edit.
+  // .config. Idempotent — the planted git hooks (pre-commit/post-checkout/post-merge) keep it fresh
+  // thereafter on the git-native anchors ([[commit-surgery]]); no harness event ever triggers a materialize.
   const prevCwd = process.cwd()
   try {
     process.chdir(targetDir)
-    const { materialize, renderVoteHint } = await import('./materialize.js')
+    const { materialize } = await import('./materialize.js')
     materialize(targetDir)
     console.log('✓ materialized harness artifacts (global hook manifest, AGENTS.md/CLAUDE.md block, harness shims, Codex trust)')
-    // the adoption vote hint ([[render-policy]]): a host-TRACKED contract file now carries the generated
-    // block and shows honestly dirty under the default policy — print the one-time decision guidance while
-    // the vote is open (an explicit `render`, including --render on this very run, retires it).
-    const hint = renderVoteHint(targetDir)
-    if (hint) console.log(`\n${hint}`)
   } catch (e) {
     console.warn(`• materialize skipped (${(e as Error).message}) — run \`spex materialize\` once the packages are installed.`)
   } finally {

package/spec-cli/src/layout.ts

@@ -10,21 +10,15 @@ type Config = {
   mainBranch?: string              // source-of-truth BRANCH worktrees fork from (default: auto-detected — see mainBranch())
   branchPrefix?: string            // how a branch names its node (default: "node/")
   preset?: string                  // the SELECTED init preset — which cumulative .config tier `spex init` seeds (default 'default'; seed-time only, no launcher gate; read by init.ts; see [[init-preset]])
-  // the RENDER POLICY ([[render-policy]]) — the ONE voted footprint knob: where the machine-independent
-  // RENDERS (the CLAUDE.md/AGENTS.md contract blocks, the .claude/.codex skills + agents) sit relative to the
-  // shared repo. Three words, validated fail-loud by materialize's resolveRenderPolicy:
-  //   'committed'  the renders are ordinary committed files (their entries leave the ignore block) — the
-  //                contract reaches un-adopted teammates/CI through the harness's native discovery, for free;
-  //   'ignored'    (default) the renders are generated + gitignored via the managed block in the TRACKED
-  //                .gitignore — the team sees the rule, never the products;
-  //   'hidden'     zero repo footprint — the ignore rules live in the per-clone .git/info/exclude, and a
-  //                HOST-TRACKED contract file is handled by the clean/smudge content filter ([[content-filter]]).
-  // `committed` is a project fact → spexcode.json; `hidden` is a host/person fact → spexcode.local.json.
-  // The schema deliberately has NO knob for the spec DATA: `.spec` + spexcode.json are ALWAYS tracked
-  // ("git is the database") — the vocabulary itself makes "untrack the spec" unsayable.
-  render?: 'committed' | 'ignored' | 'hidden'
-  // DEPRECATED ([[render-policy]] compat): the retired private-overlay toggle. Read as render:'hidden' (with a
-  // loud, non-fatal migration notice); its old data-untrack semantics are gone — see `spex guide footprint`.
+  // RETIRED ([[residence]]) — the old three-word footprint vote. Materialized artifacts carry no facts and are never
+  // tracked now (one residence behavior: the per-clone exclude, plus the content filter for a mixed
+  // contract file), so the field is IGNORED with a loud non-fatal notice (materialize's retiredAxisNotice);
+  // it stays in the type only so the notice can read it. The schema deliberately has NO knob for the spec
+  // DATA: `.spec` + spexcode.json are ALWAYS tracked ("git is the database") — the vocabulary itself makes
+  // "untrack the spec" unsayable.
+  render?: string
+  // RETIRED (residence compat): the old private-overlay toggle — ignored with the same loud notice;
+  // its data-untrack semantics are long gone. See `spex guide footprint` MIGRATIONS.
   private?: boolean
   // which harness targets `spex materialize` delivers into — native ids ('claude'|'codex') or a {plugin:"<folder>"}
   // bundle; resolved + validated by [[harness-select]] (harness-select.ts). Default (omitted): all native harnesses.
@@ -145,17 +139,29 @@ export function spexcodeHome(): string {
 export function encodeProject(root: string): string {
   return root.replace(/[/.]/g, '-')
 }
-// this project's per-PROJECT runtime tier — the materialized hook manifest + content-hash marker (and the
-// gate's lock) — living alongside sessions/ under the SAME global per-project dir, so NOTHING SpexCode renders
-// stays in the worktree (not even the manifest; the worktree holds only the harness-discovered CLAUDE.md/
-// AGENTS.md + shims, which must sit in-tree). proj-aware for `spex init <dir>` / materialize(proj); cwd-based
-// default for the hooks/board. The shell hooks mirror this as hp_runtime_dir.
+// this project's per-PROJECT runtime tier — the sessions/ records AND the per-TREE materialize slots (below) —
+// living under the SAME global per-project dir, so NOTHING SpexCode materializes stays in the worktree (the
+// worktree holds only the harness-discovered CLAUDE.md/AGENTS.md + shims, which must sit in-tree).
+// proj-aware for `spex init <dir>` / materialize(proj); cwd-based default for the hooks/board. The shell
+// hooks mirror this as hp_runtime_dir.
 export function runtimeRoot(proj?: string): string {
   const gcd = proj
     ? git(['-C', proj, 'rev-parse', '--path-format=absolute', '--git-common-dir']).trim()
     : gitCommonDir()
   return join(spexcodeHome(), 'projects', encodeProject(dirname(gcd)))
 }
+// the per-WORKTREE materialize slot — <runtime>/trees/<enc(worktree-toplevel)> — holding the materialize
+// products that are a pure function of ONE tree's .config (hooks-manifest, content-hash, plugin-folders).
+// Slotted per tree exactly like sessions/<id> is slotted per session: the old single global file made the
+// last-materialized tree win, so dispatch ran tree A's compiled hook set inside tree B's sessions
+// ([[hook-dispatch]]). Key = the sessions encodeProject transform over `rev-parse --show-toplevel`, the
+// SAME derivation dispatch.sh's shell mirror (hp_tree_dir) runs from its own cwd — so writer and reader
+// land on the same slot from the same tree, and only from the same tree. Throws when `wt` is not a live
+// git tree (fail loud); a best-effort caller (the close-time GC) wraps it.
+export function treeSlotDir(wt: string): string {
+  const top = git(['-C', wt, 'rev-parse', '--show-toplevel']).trim()
+  return join(runtimeRoot(wt), 'trees', encodeProject(top || wt))
+}
 // this project's per-session records dir, one session's dir, its structured record, and a sibling artifact —
 // all keyed by session_id under <home>/projects/<enc>/sessions/.
 export function sessionsRoot(): string { return join(runtimeRoot(), 'sessions') }