spexcode 0.2.5 → 0.2.6

package/README.md

@@ -74,7 +74,7 @@ Requires Node ≥ 22 and git. This part is plain tooling — no AI involved yet.
 ```sh
 npm i -g spexcode        # installs the `spex` command
 cd your-repo
-spex init                # seeds .spec/, installs git hooks, renders the agent contract
+spex init                # seeds .spec/, installs git hooks, materializes the agent contract
 spex serve               # API backend on :8787
 spex dashboard           # board UI on :5173, proxying to the backend
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spexcode",
-  "version": "0.2.5",
+  "version": "0.2.6",
   "type": "module",
   "description": "SpexCode — a spec-driven, self-developing dev tool. The `spex` CLI + spec server reads the .spec tree and its git history, and serves the dashboard.",
   "license": "MIT",

package/spec-cli/hooks/dispatch.sh

@@ -3,22 +3,21 @@
 # / .codex/hooks.json, written by each [[harness-adapter]]) binds one line per event to
 # `dispatch.sh <harness> <Event>` — the harness id is BAKED IN by the adapter that wrote the shim, so this is
 # the deterministic harness DETECTOR for the shell side: we export SPEXCODE_HARNESS (read by harness.sh, the
-# adapter's shell mirror, which the hook handlers source) without ever sniffing the payload shape. Two jobs,
-# in order:
-#   (1) GATE — a cheap pure-shell content hash of the config roots (~10ms, every event). If it moved since the
-#       last render, re-run `spex materialize` (the ~0.85s node step) to bring manifest + contract (AGENTS.md/
-#       CLAUDE.md block) + shims + Codex trust back in lockstep with the EDITABLE .config. Content-based, so it
-#       catches bash/sed/user/other-agent/git edits alike (a tool-payload path would miss them). Serialized by
-#       a lock with a re-check inside, so concurrent sessions never race the write (§ atomicity).
-#   (2) DISPATCH — run every handler bound to <Event> from the persistent manifest, in order, feeding each the
-#       ORIGINAL stdin. Reproduces the native parallel multi-hook contract DETERMINISTICALLY: all handlers run
-#       (side effects preserved), their stdout (decision/additionalContext) is concatenated through, and a
-#       block:true handler that exits 2 makes the dispatch exit 2 with that handler's stderr — the one signal
-#       the harness propagates. Pure bash, no node boot on the hot path (node runs only inside the gate, only
-#       on actual change). cwd = the project/worktree. $SPEX (abs tsx+cli) is inherited from the shim env.
+# adapter's shell mirror, which the hook handlers source) without ever sniffing the payload shape. ONE job:
+#   DISPATCH — run every handler bound to <Event> from the persistent manifest, in order, feeding each the
+#   ORIGINAL stdin. Reproduces the native parallel multi-hook contract DETERMINISTICALLY: all handlers run
+#   (side effects preserved), their stdout (decision/additionalContext) is concatenated through, and a
+#   block:true handler that exits 2 makes the dispatch exit 2 with that handler's stderr — the one signal
+#   the harness propagates. Pure bash, no node boot on the hot path. cwd = the project/worktree. $SPEX (abs
+#   tsx+cli) is inherited from the shim env.
+#
+# The old (1) GATE — an auto-materialize when the config content-hash moved — is RETIRED ([[commit-surgery]]):
+# a harness event is never a materialize trigger; the materialize anchors are git-native only (spex verbs,
+# session-worktree creation, and the pre-commit/post-checkout/post-merge hooks). .config edits are
+# git-transactional: they take effect at the commit/checkout/merge that carries them, like any other source.
 set -u
 # args: `<harness> <Event>`. A harness id as $1 (claude|codex|plugin) is consumed; otherwise we keep $1 as the
-# event and default the harness to claude — so a stale shim still rendered as `dispatch.sh <Event>` keeps working.
+# event and default the harness to claude — so a stale shim still written as `dispatch.sh <Event>` keeps working.
 # `plugin` is the bundle form ([[plugin-harness]]): it parses payloads as the claude family in harness.sh (z-code/
 # Claude share Claude's tool names + file_path), so it joins the claude branch there via the default case.
 harness=claude
@@ -30,35 +29,24 @@ export SPEXCODE_HARNESS="$harness"
 export SPEXCODE_HARNESS_LIB="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/harness.sh"
 . "$SPEXCODE_HARNESS_LIB"
 proj="${CLAUDE_PROJECT_DIR:-$PWD}"
-# the manifest + content-hash + gate lock live in the GLOBAL per-project store (mirrors layout.runtimeRoot),
-# NOT the worktree — so the worktree carries zero SpexCode-rendered runtime. Empty if git can't resolve.
+# the manifest lives in THIS tree's materialize slot of the GLOBAL per-project store (mirrors layout.treeSlotDir),
+# NOT the worktree — and per tree, so a dispatch can only read the manifest of the tree it fires in
+# ([[hook-dispatch]]). Slot key = this cwd's rev-parse --show-toplevel through hp_tree_dir. Empty if git
+# can't resolve.
 rt="$(cd "$proj" 2>/dev/null && hp_runtime_dir)" || rt=""
+slot="$(cd "$proj" 2>/dev/null && hp_tree_dir)" || slot=""
 
-# --- (1) gate -------------------------------------------------------------------------------------------
-# the config fingerprint is hp_config_hash (harness.sh, already sourced) — the SAME function materialize.ts
-# shells to, so the gate and the renderer never disagree on "changed".
-cur="$( (cd "$proj" 2>/dev/null && hp_config_hash) )"
-if [ -n "$rt" ] && [ -n "$cur" ] && [ "$cur" != "$(cat "$rt/content-hash" 2>/dev/null || true)" ]; then
-  mkdir -p "$rt" 2>/dev/null
-  # POSIX-portable mutex: mkdir is atomic on every POSIX fs, so it serializes the render with NO dependency on
-  # util-linux `flock` (absent on macOS — where it silently no-op'd, letting concurrent sessions race the write).
-  # Spin on `mkdir` with a bounded wait; after ~10s (200 * 0.05s, well above the ~0.85s materialize) treat the
-  # dir as orphaned by a dead entrant and clear it, so a stale lock can never deadlock a launch. Held only across
-  # the re-check + render, released right after.
-  lockd="$rt/.materialize.lock.d"
-  _lk=0
-  until mkdir "$lockd" 2>/dev/null; do
-    _lk=$((_lk+1)); [ "$_lk" -ge 200 ] && { rm -rf "$lockd" 2>/dev/null; _lk=0; }
-    sleep 0.05
-  done
-  if [ "$cur" != "$(cat "$rt/content-hash" 2>/dev/null || true)" ]; then   # re-check: a sibling dispatch may have just rendered
-    ( cd "$proj" && ${SPEX:-spex} materialize >/dev/null 2>&1 )
-  fi
-  rmdir "$lockd" 2>/dev/null
+# --- dispatch ---------------------------------------------------------------------------------------------
+if [ -n "${SPEX_HOOK_MANIFEST:-}" ]; then
+  manifest="$SPEX_HOOK_MANIFEST"
+else
+  # migration window: a tree last materialized by a pre-slot toolchain has no slot until its next git-native
+  # anchor — fall back to the legacy global manifest (its exact pre-migration behavior) so no hook (the
+  # Stop gate included) silently no-ops. The legacy file is never written again; the next anchor plants the
+  # slot and this branch goes dead.
+  manifest="$slot/hooks-manifest"
+  [ -f "$manifest" ] || manifest="$rt/hooks-manifest"
 fi
-
-# --- (2) dispatch ---------------------------------------------------------------------------------------
-manifest="${SPEX_HOOK_MANIFEST:-$rt/hooks-manifest}"
 [ -f "$manifest" ] || exit 0          # no manifest yet (materialize never ran) → nothing to dispatch
 input="$(cat 2>/dev/null || true)"    # capture stdin ONCE; each handler gets its own copy
 err="/tmp/.spex-hook-$$.err"          # per-dispatch (pid-unique) stderr capture; no cross-session race

package/spec-cli/hooks/harness.sh

@@ -70,7 +70,7 @@ hp_session_id() {
 
 # the per-PROJECT GLOBAL runtime dir (mirrors spec-cli/src/layout.ts `runtimeRoot`): <store>/projects/<enc>,
 # keyed by the project (dirname of the ABSOLUTE git-common-dir, so the answer is identical from main or any
-# worktree). This is where the materialized hook manifest + content-hash + gate lock live — NOT the worktree.
+# worktree). The per-session dirs and the per-tree materialize slots (hp_tree_dir) live under it.
 # Echoes the dir; returns non-zero (echoing nothing) when git can't resolve, so a caller can `|| exit 0`.
 hp_runtime_dir() {
   local gcd
@@ -79,6 +79,19 @@ hp_runtime_dir() {
   printf '%s/projects/%s' "${SPEXCODE_HOME:-$HOME/.spexcode}" "$(printf '%s' "$(dirname "$gcd")" | sed 's#[/.]#-#g')"
 }
 
+# the per-WORKTREE materialize slot (mirrors layout.ts `treeSlotDir`): <runtime>/trees/<enc(worktree-toplevel)> —
+# where THIS tree's materialized hook manifest + content-hash marker live. Keyed by the cwd's own
+# `rev-parse --show-toplevel` through the same enc transform, so a dispatch can only ever read the manifest
+# of the tree it fires in ([[hook-dispatch]] — the old single global file let the last-materialized tree's
+# hook set reach every other tree's sessions). Echoes the dir; returns non-zero when git can't resolve.
+hp_tree_dir() {
+  local rd top
+  rd=$(hp_runtime_dir) || return 1
+  top=$(git rev-parse --show-toplevel 2>/dev/null)
+  [ -n "$top" ] || return 1
+  printf '%s/trees/%s' "$rd" "$(printf '%s' "$top" | sed 's#[/.]#-#g')"
+}
+
 # the per-session GLOBAL store dir for a session id — <runtime>/sessions/<id> (sibling of the per-project
 # runtime above). Echoes the dir; returns non-zero (echoing nothing) when git can't resolve.
 # ALIAS resolution: a codex hook fires from the shared per-PROJECT app-server process, whose env may carry a
@@ -99,35 +112,32 @@ hp_store_dir() {
   printf '%s' "$direct"
 }
 
-# the RENDERER's own version fingerprint — the toolchain side of the gate key. The rendered artifacts are a
-# function of (config content, renderer), so a TOOLCHAIN update must move the key too, or an updated deploy
-# never self-heals its stale contract/shims/manifest until someone happens to edit .config (the field lesson:
-# a toolchain update does NOT self-heal). A source checkout answers with the git TREE hash of the package dir
-# (moves exactly when the toolchain's content moves, not on every repo commit); an npm install (no .git)
-# answers with the package.json hash (npm bumps the version). env-stripped git — a git hook's exported
-# GIT_DIR must not misdirect repo discovery (same rule as git.ts's git()).
+# the TOOLCHAIN's own version fingerprint — the toolchain side of the content key. The materialized artifacts
+# are a function of (config content, toolchain), so a TOOLCHAIN update must move the key too, or an updated
+# deploy never self-heals its stale contract/shims/manifest until someone happens to edit .config (the field
+# lesson: a toolchain update does NOT self-heal). A source checkout answers with the git TREE hash of the
+# package dir (moves exactly when the toolchain's content moves, not on every repo commit); an npm install
+# (no .git) answers with the package.json hash (npm bumps the version). env-stripped git — a git hook's
+# exported GIT_DIR must not misdirect repo discovery (same rule as git.ts's git()).
 SPEXCODE_HP_PKG="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." 2>/dev/null && pwd)"
-hp_renderer_version() {
+hp_toolchain_version() {
   ( cd "$SPEXCODE_HP_PKG" 2>/dev/null && env -u GIT_DIR -u GIT_INDEX_FILE git rev-parse 'HEAD:./' 2>/dev/null ) \
     || sha256sum "$SPEXCODE_HP_PKG/package.json" 2>/dev/null | cut -d' ' -f1 \
     || echo unversioned
 }
 
-# the deterministic content fingerprint of EVERYTHING the render is a function of: the EDITABLE config
+# the deterministic content fingerprint of EVERYTHING the materialize is a function of: the EDITABLE config
 # roots (.config + config md/sh), the PERSISTED POLICY files (the MAIN checkout's spexcode.json +
-# spexcode.local.json — the `harnesses` set and `render` vote materialize reads via readConfig(mainCheckout)),
-# and the renderer version above — the gate's "did anything the render depends on move?" signal. The policy
-# files are in the key so a harness-selection or render-policy edit SELF-HEALS on the very next hook event
-# (before this, narrowing `harnesses` left the deselected harness's stale artifacts in place until an
-# unrelated .config edit happened to fire the gate — [[harness-select]]). Run with cwd = the project. ONE
-# definition: the dispatch.sh gate sources this and materialize.ts shells to it, so the gate and the renderer
-# can NEVER disagree on what "changed" means (the two used to inline this pipeline verbatim, each commenting
-# the other "MUST match"). env-stripped git, same rule as hp_renderer_version.
+# spexcode.local.json — the `harnesses` set materialize reads via readConfig(mainCheckout)), and the
+# toolchain version above. Since the dispatch-gate retired ([[commit-surgery]] — materialize anchors on
+# git-native events only), this is a FRESHNESS STAMP materialize records after each pass, a diagnostic
+# (is the last materialize current?) rather than a trigger. Run with cwd = the project. ONE definition:
+# materialize.ts shells to it. env-stripped git, same rule as hp_toolchain_version.
 hp_config_hash() {
   local gcd
   gcd=$(env -u GIT_DIR -u GIT_INDEX_FILE git rev-parse --path-format=absolute --git-common-dir 2>/dev/null) \
     || gcd=$(realpath "$(env -u GIT_DIR -u GIT_INDEX_FILE git rev-parse --git-common-dir 2>/dev/null)" 2>/dev/null)
-  { hp_renderer_version
+  { hp_toolchain_version
     find .spec/*/.config .spec/*/config \( -name '*.md' -o -name '*.sh' \) -type f -print0 2>/dev/null \
       | sort -z | xargs -0 cat 2>/dev/null
     [ -n "$gcd" ] && cat "$(dirname "$gcd")/spexcode.json" "$(dirname "$gcd")/spexcode.local.json" 2>/dev/null

package/spec-cli/src/cli.ts

@@ -52,7 +52,7 @@ function flushExit(code = 0): Promise<never> {
 }
 const has = (name: string) => process.argv.includes(`--${name}`)
 // bare positionals after argv index `from`, skipping flags and their values (selectors for ls/watch).
-const VALUE_FLAGS = new Set(['--status', '--as', '--interval', '--propose', '--note', '--node', '--prompt', '--prompt-file', '--timeout', '--reason', '--out', '--password', '--tls-cert', '--tls-key', '--harness', '--launcher', '--harness-session', '--port', '--api', '--api-port', '--host', '--preset', '--render', '--limit', '--session', '--depth'])
+const VALUE_FLAGS = new Set(['--status', '--as', '--interval', '--propose', '--note', '--node', '--prompt', '--prompt-file', '--timeout', '--reason', '--out', '--password', '--tls-cert', '--tls-key', '--harness', '--launcher', '--harness-session', '--port', '--api', '--api-port', '--host', '--preset', '--limit', '--session', '--depth'])
 function positionals(from: number): string[] {
   const out: string[] = []
   for (let i = from; i < process.argv.length; i++) {
@@ -279,9 +279,9 @@ if (cmd === 'serve') {
   }
 } else if (cmd === 'init') {
   // scaffold a repo to adopt SpexCode: copy the shipped DATA templates (seed spec tree + git hooks)
-  // into <targetDir> (default cwd). spex init [targetDir] [--preset <tier>] [--render <word>]
+  // into <targetDir> (default cwd). spex init [targetDir] [--preset <tier>]
   const { specInit } = await import('./init.js')
-  await specInit(positionals(3)[0], flag('preset'), flag('render'))
+  await specInit(positionals(3)[0], flag('preset'))
 } else if (cmd === 'uninstall') {
   // the surgical inverse of init: remove every SpexCode-generated artifact (harness shims/contract/trust, the
   // .gitignore block, the global store, any plugin bundle) — NEVER the user's .spec/.config data or their own
@@ -401,19 +401,16 @@ if (cmd === 'serve') {
   const run = cmd === 'remark' ? m.runRemark : cmd === 'resolve' ? m.runResolve : m.runRetract
   await flushExit(await run(process.argv.slice(3)))
 } else if (cmd === 'materialize') {
-  // @@@ materialize - the pay-per-change render: surface nodes → manifest + AGENTS.md/CLAUDE.md block +
-  // shims + Codex trust, for cwd's project. The cheap shell gate (dispatch.sh) invokes it only on change.
-  // The adoption vote hint ([[render-policy]]) prints only here and on init — the human surfaces — never
-  // from the silent gate/bootstrap renders of the same function.
-  const { materialize, renderVoteHint } = await import('./materialize.js')
+  // @@@ materialize - surface nodes → manifest + AGENTS.md/CLAUDE.md block + shims + Codex
+  // trust, for cwd's project. Anchored on git-native events only ([[commit-surgery]]): this verb, init,
+  // session-worktree creation, and the planted pre-commit/post-checkout/post-merge hooks.
+  const { materialize } = await import('./materialize.js')
   console.log(`materialized — content-hash ${materialize()}`)
-  const hint = renderVoteHint()
-  if (hint) console.log(`\n${hint}`)
 } else if (cmd === 'doctor') {
   // @@@ doctor - the diagnosis surface ([[doctor]], né `self` — renamed: "self" read as the tool itself /
   // the global install, while the report is about THIS agent's wiring): does the materialized workflow
   // actually reach this agent? Bare `doctor` reports per-layer coverage (preconditions · git-hook floor ·
-  // contract · hooks+handler-existence · backend) over the same HARNESSES materialize renders through;
+  // contract · hooks+handler-existence · backend) over the same HARNESSES materialize delivers through;
   // `contract` prints the surface:system text; `conflicts` just the double-delivery check. Thin route.
   const { runDoctor } = await import('./doctor.js')
   await flushExit(await runDoctor(process.argv.slice(3)))
@@ -760,6 +757,19 @@ if (cmd === 'serve') {
     const sid = process.env.SPEXCODE_SESSION_ID
     if (sid) markHarnessSessionId(sid, r.threadId)
     console.log(r.threadId)
+  } else if (sub === 'commit-surgery') {
+    // the pre-commit footprint anchor ([[commit-surgery]]): unconditional materialize + staged-index repair
+    // (strip our sentinel block from staged blobs, unstage HEAD-untracked generated artifacts). Called only
+    // by the planted pre-commit hook; repairs and proceeds, never rejects. Exit non-zero only on an internal
+    // error — the hook treats that as advisory (warn + continue), CI lint remains the real gate.
+    const { commitSurgery } = await import('./commit-surgery.js')
+    commitSurgery()
+  } else if (sub === 'refresh-footprint') {
+    // the post-checkout / post-merge freshness anchor ([[commit-surgery]]): a quiet materialize after a git
+    // state transition (the only events that can move the materialize's inputs — .spec/.config arrive by commit,
+    // merge, or checkout). Best-effort and silent on success; hooks call it fire-and-forget.
+    const { materialize } = await import('./materialize.js')
+    try { materialize() } catch (e) { console.error(`spexcode: footprint refresh failed (${(e as Error).message})`); process.exit(1) }
   } else if (sub === 'codex-turn') {
     // fire a follow-up turn on an OWNED thread over the per-project socket (the delivery channel, exposed for
     // tests / scripts). steer-vs-start is chosen live from the thread read.

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

@@ -4,24 +4,25 @@ import { execFileSync } from 'node:child_process'
 import { git } from './git.js'
 import { writeManagedBlock, removeManagedBlock } from './harness.js'
 
-// @@@ contract-filter ([[content-filter]]) - the render=hidden answer for a MIXED-CONTENT contract file: a
-// CLAUDE.md/AGENTS.md the HOST ALREADY TRACKS, where "generate + ignore" is a no-op (git ignores only
-// untracked paths) and the folded-in block would ride the tracked file into every teammate's diff. A git
-// clean/smudge content filter keeps the two contents on their own sides of the index: the REPO stores the
+// @@@ 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, exactly the hidden contract. The sentinels are the load-bearing anchor: the invariant
+// 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 for a file the host tracks (the weakest sufficient tool: an untracked contract file is wholly
-// ours and plain generate+ignore already hides it — no filter). materialize plants/refreshes it under
-// render=hidden and erases it under every other policy ([[render-policy]] / the forgetting law).
+// 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-render writes the managed block straight into the working file (writeManagedBlock IS the re-smudge),
+//     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
@@ -43,7 +44,7 @@ const attributesPath = (common: string) => join(common, 'info', 'attributes')
 // 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 — render=hidden; see [[content-filter]]).
+# 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}"
@@ -93,13 +94,14 @@ esac
 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 TRACKED contract files: 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).
+// 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 render
+  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')])

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}`)
   }