spexcode 0.2.3 → 0.2.5

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 share-axis model — what SpexCode plants in a repo, the render policy
+                        (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, a personal "render": "hidden" vote. 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, a TLS cert path, a personal render:hidden 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,81 @@ 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
+              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)
+
+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.
+
+── THE FOUR KINDS (three are fixed; one votes) ──
+  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).
+  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.
+
+── 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.
+
+── 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
+                            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 }
 
 // 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.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
@@ -770,9 +771,14 @@ 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 ([[render-policy]]): 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)
 }
@@ -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

package/spec-cli/src/help.ts

@@ -72,11 +72,12 @@ session list. Identical to GET /api/board; needs the backend (spex serve) reacha
     see: 'spex tree (the same graph, human-readable) · spex ls (just the sessions, as a table) · spex search (find one node instead of dumping all)',
   },
   guide: {
-    line: 'guide [topic]         the manuals: setup workflow · spec/yatsu file formats · spexcode.json',
+    line: 'guide [topic]         the manuals: setup workflow · spec/yatsu file formats · spexcode.json · footprint',
     body: `Usage: spex guide            the human setup workflow (install once, adopt a repo, serve)
        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
 
 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.`,
@@ -180,16 +181,21 @@ a node/<id> branch links its PR for free). Read-only — git/.spec stays the sin
   },
   // ── dispatch & manage sessions (manager loop) ─────────────────────────────
   new: {
-    line: 'new "<prompt>"        launch a worker session in its own node worktree  [--node <id>] [--launcher <name>]',
+    line: 'new "<prompt>"        launch a worker session in its own node worktree  [--prompt-file <path>|-] [--node <id>] [--launcher <name>]',
     body: `Usage: spex new "<task prompt>" [--node <id>] [--launcher <name>]
+       spex new --prompt-file <path>|- [--node <id>] [--launcher <name>]
 
 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.
+--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.
 The launcher name selects both the agent harness and the command/auth profile (built-ins: claude, codex);
 omitting it requires sessions.defaultLauncher in spexcode.json or spexcode.local.json.
 Routes through the running backend (auth env + concurrency cap); prints the created session JSON.
-Then MONITOR it: background \`spex wait <id>\`, or \`spex watch\` for the whole stream.`,
-    see: 'spex wait / spex watch (monitor) · spex review (when it proposes) · ' + SEL_NOTE.split('\n')[0],
+Then MONITOR it: background \`spex wait <id>\`, or \`spex watch\` for the whole stream.
+Talk to it with \`spex send <id> "<msg>"\` — never raw tmux keystrokes.`,
+    see: 'spex wait / spex watch (monitor) · spex send (talk to it) · spex review (when it proposes) · ' + SEL_NOTE.split('\n')[0],
   },
   ls: {
     line: 'ls [SEL…]             living-sessions table  [--status a,b] [--json] [--api URL]',
@@ -307,12 +313,15 @@ ${ROUTING_NOTE}`,
 
   // ── install & serve (operator) ────────────────────────────────────────────
   init: {
-    line: 'init [dir]            adopt SpexCode on a repo: seed .spec + hooks + materialize  [--preset name]',
-    body: `Usage: spex init [dir=cwd] [--preset default|careful]
+    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]
 
 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).`,
+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).`,
     see: 'spex guide (the full setup workflow) · spex uninstall (the inverse) · spex lint (adoption TODO)',
   },
   uninstall: {

package/spec-cli/src/index.ts

@@ -7,6 +7,7 @@ import { loadSpecs, loadSpecsLite, specContent, specHistory, specDiffAt, loadCon
 import { issuesEnabled, remarkOnHost, resolveRemark, retractRemark } from './localIssues.js'
 import { closeIssue, createIssue, issueStores, mergedIssues, promote, replyIssue } from './issues.js'
 import { residentForgeState, refreshForgeNow } from '../../spec-forge/src/resident.js'
+import { resolveForgeHost } from '../../spec-forge/src/drivers.js'
 import { summarize } from './mentions.js'
 import { resolveLayout, mainBranch } from './layout.js'
 import { getBoardJson } from './boardCache.js'
@@ -44,7 +45,8 @@ app.get('/health', (c) => c.text('ok'))
 // shares ONE build instead of each running its own — the poll-frequency cut (push channel) and the
 // build-coalescing cut compound. A hard timeout bounds a wedged build to a loud 503 rather than an
 // unboundedly-held connection (the wall sits well above the legitimately-several-seconds cold first build);
-// the underlying single-flight build keeps running and caches for the next poll.
+// a merely-slow single-flight build keeps running and caches for the next poll, while a NEVER-settling one
+// is bounded by [[board-cache]]'s own build watchdog, so the next poll retries a fresh build.
 const BOARD_TIMEOUT_MS = Number(process.env.SPEXCODE_BOARD_TIMEOUT_MS || 20000)
 app.get('/api/board', etag(), async (c) => {
   const timeout = Symbol('timeout')
@@ -160,7 +162,7 @@ app.get('/api/issues', etag(), (c) =>
   c.json({
     enabled: issuesEnabled(),
     stores: issueStores(),
-    issues: mergedIssues({ host: 'github', state: residentForgeState() }, loadSpecsLite().map((s) => s.id)),
+    issues: mergedIssues({ host: resolveForgeHost(), state: residentForgeState() }, loadSpecsLite().map((s) => s.id)),
   }))
 // the WRITE surface ([[local-issues]] / [[issues-view]]) — the human reply path, STORE-ROUTED through the one
 // reply verb ([[issues]] replyIssue): a local id git-commits to the trunk store, a forge id ('github#N')
@@ -181,7 +183,7 @@ app.post('/api/issues/:id/reply', async (c) => {
   try {
     // the mention prompt's node context, from the same resident merge the GET serves
     const node = id.includes('#')
-      ? mergedIssues({ host: 'github', state: residentForgeState() }, loadSpecsLite().map((s) => s.id)).find((i) => i.id === id)?.nodes[0] ?? null
+      ? mergedIssues({ host: resolveForgeHost(), state: residentForgeState() }, loadSpecsLite().map((s) => s.id)).find((i) => i.id === id)?.nodes[0] ?? null
       : null
     const r = await replyIssue(id, text, { author: 'human', node, evidence })
     if (r.store !== 'local') await refreshForgeNow()
@@ -446,9 +448,10 @@ app.post('/api/sessions/:id/rawkey', async (c) => {
 // removes the worktree. {ok:false} = no such session.
 app.post('/api/sessions/:id/exit', async (c) => c.json({ ok: await exitSession(c.req.param('id')) }))
 app.post('/api/sessions/:id/close', async (c) => c.json({ ok: await closeSession(c.req.param('id')) }))
-// set (or clear, with a blank) a session's display-name override; persists to the worktree's `.session` so
-// it survives a restart. Unknown id → 404. The worktree file is OUTSIDE the store the board watchers see,
-// so the route nudges the stream explicitly ([[board-stream]]) — the rename shows in ~150ms, not a cold tick.
+// set (or clear, with a blank) a session's display-name override; persists to the session's global record
+// (`session.json`) so it survives a restart. Unknown id → 404. That record sits INSIDE the watched store, but
+// the store watch is best-effort (it can fail to attach), so the route still nudges the stream explicitly
+// ([[board-stream]]) — the rename shows in ~150ms deterministically, never waiting out a cold tick.
 app.post('/api/sessions/:id/rename', async (c) => {
   const body = await c.req.json().catch(() => ({}))
   const ok = await renameSession(c.req.param('id'), typeof body?.name === 'string' ? body.name : '')

package/spec-cli/src/init.ts

@@ -1,8 +1,8 @@
-import { existsSync, mkdirSync, copyFileSync, readdirSync, statSync, chmodSync } from 'node:fs'
+import { existsSync, mkdirSync, copyFileSync, readdirSync, statSync, chmodSync, writeFileSync } from 'node:fs'
 import { join, resolve, relative } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { execFileSync } from 'node:child_process'
-import { readConfig } from './layout.js'
+import { readConfig, readJsonConfig } from './layout.js'
 import { resolveHarnessTargets } from './harness-select.js'
 
 // this file lives at <pkgRoot>/src/init.ts, so `..` is the package root — the same derivation the
@@ -53,9 +53,27 @@ function resolveHooksDir(dir: string): string | null {
   }
 }
 
-export async function specInit(targetArg: string | undefined, presetArg?: string): Promise<void> {
+export async function specInit(targetArg: string | undefined, presetArg?: string, renderArg?: 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.
@@ -99,13 +117,29 @@ export async function specInit(targetArg: string | undefined, presetArg?: string
     }
   }
 
-  // 1b. plant a starter spexcode.json (the lint/layout knob), pointing governedRoots at `src/`.
+  // 1b. plant a starter spexcode.json (the lint/layout knob). The success message reports the value the
+  // template ACTUALLY ships (read from the planted file, never restated as a string literal here — the two
+  // once drifted: the message claimed ["src"] while the template seeded ["."]).
   const cfgDest = join(targetDir, 'spexcode.json')
   if (existsSync(cfgDest)) {
     console.warn(`• spexcode.json already exists at ${cfgDest} — left untouched.`)
   } else {
     copyFileSync(join(TEMPLATES, 'spexcode.json'), cfgDest)
-    console.log(`✓ planted spexcode.json — set lint.governedRoots to YOUR source dirs (starter: ["src"])`)
+    const roots = JSON.stringify(readJsonConfig(cfgDest)?.lint?.governedRoots ?? null)
+    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 +
@@ -149,21 +183,29 @@ export async function specInit(targetArg: string | undefined, presetArg?: string
   const prevCwd = process.cwd()
   try {
     process.chdir(targetDir)
-    const { materialize } = await import('./materialize.js')
+    const { materialize, renderVoteHint } = await import('./materialize.js')
     materialize(targetDir)
-    console.log('✓ materialized harness artifacts (global hook manifest, AGENTS.md/CLAUDE.md block, .claude/.codex shims, Codex trust)')
+    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 {
     process.chdir(prevCwd)
   }
 
-  // 3. next steps — what the human must do to bring the instance to life.
+  // 3. next steps — what the human must do to bring the instance to life. The governedRoots line reads the
+  // LIVE value (the planted starter's, or a pre-existing config's) so it can never drift from what's on disk.
+  const rootsNow = JSON.stringify(readJsonConfig(cfgDest)?.lint?.governedRoots ?? null)
   console.log(`
 Next steps:
   1. Edit .spec/project/spec.md to describe YOUR project, then grow child nodes beneath it.
-  2. Set lint.governedRoots in spexcode.json to your source dir(s) — until you do, \`spex lint\`
-     warns it is governing nothing (it ships pointing at "src").
+  2. lint.governedRoots in spexcode.json (currently ${rootsNow}) names what \`spex lint\` governs —
+     ["."] governs the whole git-tracked tree (tests excluded); narrow it to explicit source roots
+     when you want a curated graph.
   3. Start the backend and open the board:
        spex serve                       # http://localhost:8787
   4. \`spex lint\` should report 0 errors. Coverage warnings are your adoption TODO (source files no

package/spec-cli/src/issues.ts

@@ -9,7 +9,7 @@
 // (createIssue/createComment/closeIssue — the driver stays the only network toucher; the tracer stays read-only).
 import type { ForgeIssue, ForgePR } from '../../spec-forge/src/port.js'
 import { resolveLinks } from '../../spec-forge/src/links.js'
-import { DEFAULT_FORGE_HOST, FORGE_DRIVERS, forgeDriverFor, forgeIssueStores } from '../../spec-forge/src/drivers.js'
+import { FORGE_DRIVERS, forgeDriverFor, forgeIssueStores, resolveForgeHost } from '../../spec-forge/src/drivers.js'
 import { closeLocalIssue, loadLocalIssues, loadOne, postLocalIssue, reply, issuesEnabled, replyLocalIssue, runIssueWrite, ISSUE_WRITE_SUBS } from './localIssues.js'
 import { dispatchMentions, parseMentions, type DispatchOutcome, type LoopIn } from './mentions.js'
 import { envSessionId } from './layout.js'
@@ -191,8 +191,9 @@ export async function promote(id: string, opts: { author?: string } = {}): Promi
   const author = opts.author || envSessionId() || 'unknown'
   const t = loadOne(id)
   if (t.status !== 'open') throw new Error(`'${id}' is ${t.status} — only an open local issue promotes`)
-  const driver = forgeDriverFor(DEFAULT_FORGE_HOST)
-  if (!driver) throw new Error(`unknown default forge host '${DEFAULT_FORGE_HOST}'`)
+  const host = resolveForgeHost()
+  const driver = forgeDriverFor(host)
+  if (!driver) throw new Error(`no driver for this repo's forge host '${host}' (known: ${FORGE_DRIVERS.map((d) => d.host).join(', ')}) — promotion needs one`)
   const body = [
     t.body,
     t.nodes.length ? `\nSpec: ${t.nodes.join(', ')}` : '',
@@ -300,8 +301,9 @@ export async function runIssues(args: string[]): Promise<number> {
   const nodeIds = loadSpecsLite().map((s) => s.id)
   let forge: ForgeSlice | null = null
   try {
-    const driver = forgeDriverFor(DEFAULT_FORGE_HOST)
-    if (!driver) throw new Error(`unknown default forge host '${DEFAULT_FORGE_HOST}'`)
+    const host = resolveForgeHost()
+    const driver = forgeDriverFor(host)
+    if (!driver) throw new Error(`no driver for this repo's forge host '${host}' (known: ${FORGE_DRIVERS.map((d) => d.host).join(', ')})`)
     const [issues, prs] = await Promise.all([driver.listIssues(), driver.listPRs()])
     forge = { host: driver.host, state: { issues, prs } }
   } catch (e) {

package/spec-cli/src/layout.ts

@@ -10,12 +10,21 @@ 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]])
-  // PRIVATE-OVERLAY mode ([[private-overlay]]) — belongs in the gitignored spexcode.local.json, NEVER the
-  // committed spexcode.json. When true, `spex materialize` leaves ZERO trace in the host's TRACKED files /
-  // shared history: the managed ignore entries (incl .spec + spexcode.json, which the DEFAULT mode commits —
-  // "git is the database") go to the per-clone `.git/info/exclude`, and any host-tracked contract file
-  // (CLAUDE.md/AGENTS.md) the system block folds into is marked `skip-worktree` so that block never stages.
-  // The dogfood becomes invisible to collaborators, trading away git-derived spec version history ([[source-of-truth]]).
+  // 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`.
   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.
@@ -46,12 +55,15 @@ type Config = {
   issues?: {
     enabled?: boolean                // the [[local-issues]] issues-workflow on/off switch (default ON). OFF silences the post-merge nudge + hides the dashboard view; flip with `spex issues on|off`. (Pre-rename `proposals.enabled` still reads — localIssues.ts issuesEnabled.)
   }
+  forge?: {
+    host?: string                    // explicit forge host id ('github'|'gitlab'|…) overriding the origin-remote derivation ([[forge-host]] — read by spec-forge drivers.ts resolveForgeHost, not here). A project fact → committed spexcode.json.
+  }
 }
 // the resolved LAYOUT convention — main/mainBranch/branchPrefix filled to defaults. `dashboard`, `sessions`,
-// `serve`, `harnesses`, and `preset` are frontend/runtime/policy concerns (read separately via readConfig —
+// `serve`, `harnesses`, `render`, and `preset` are frontend/runtime/policy concerns (read separately via readConfig —
 // preset by init.ts at seed time, harnesses by [[harness-select]]; see api-endpoint / sessions.ts maxActive /
 // gateway.ts), NOT layout fields, so they stay out of the convention rather than forcing a default.
-type Convention = Required<Omit<Config, 'dashboard' | 'sessions' | 'serve' | 'harnesses' | 'preset' | 'issues' | 'private'>>
+type Convention = Required<Omit<Config, 'dashboard' | 'sessions' | 'serve' | 'harnesses' | 'preset' | 'issues' | 'forge' | 'private' | 'render'>>
 
 export type Worktree = {
   path: string; branch: string | null; node: string | null

package/spec-cli/src/lint.ts

@@ -140,6 +140,11 @@ export async function specLint(): Promise<Finding[]> {
         out.push({ level: 'error', rule: 'integrity', spec: s.id, file: f, msg: `spec '${s.id}' lists a missing file: ${f}` })
       owners.set(f, [...(owners.get(f) ?? []), s.id])
     }
+    // one-govern: a node is source of truth for at most ONE file, so drift/yatsu/ack have a single
+    // unambiguous subject (see [[governed-related]]). >1 is a defect — pick the true subject, demote the
+    // rest to related. ERROR (the node-side twin of too-many-owners' file-side bound). 0 is fine.
+    if (s.code.length > 1)
+      out.push({ level: 'error', rule: 'one-govern', spec: s.id, msg: `'${s.id}' governs ${s.code.length} files [${s.code.join(', ')}] — a node is source of truth for at most ONE. Keep the true subject in code:, move the rest to related:` })
   }
   // a file is COVERED if any node GOVERNS (code:) or merely REFERENCES (related:) it; integrity covers both.
   // `related:` is the coverage net: govern is a sharp ideally-one-file pointer, so most files are reached by
@@ -217,6 +222,20 @@ export async function specLint(): Promise<Finding[]> {
       out.push({ level: 'warn', rule: 'drift', spec: s.id, file: d.file, msg: `${d.file} is ${d.behind} commit(s) ahead of spec '${s.id}' (v${s.version}) — may be stale` })
   }
 
+  // related drift: the SOFT tier ([[governed-related]]). A referenced file moved ahead of the node's
+  // version — a nudge that a dependency shifted. Same ancestry basis as govern drift, but WARN-only,
+  // never reaching the commit gate (driftGate reads govern) or yatsu. It is COMMON (shared substrate and
+  // faces change often without re-versioning every referrer), so per-file it is a wall; like
+  // too-many-owners it collapses to ONE summary line, with the per-file detail riding the board
+  // (relatedDriftFiles). It stays a soft edge, never a per-file interruption.
+  const rd = specs.flatMap((s) => s.relatedDriftFiles.map((d) => ({ id: s.id, behind: d.behind })))
+  if (rd.length) {
+    const byNode = new Map<string, number>()
+    for (const d of rd) byNode.set(d.id, (byNode.get(d.id) ?? 0) + 1)
+    const worst = [...byNode].sort((a, b) => b[1] - a[1]).slice(0, 5).map(([id, n]) => `${id}(${n})`).join(', ')
+    out.push({ level: 'warn', rule: 'related-drift', msg: `${rd.length} related file(s) across ${byNode.size} node(s) drifted ahead of their spec (SOFT — a dependency shifted, worth a glance; never blocks, no ack, no yatsu). Most: ${worst}` })
+  }
+
   return out
 }
 

package/spec-cli/src/localIssues.ts

@@ -362,16 +362,28 @@ export async function replyLocalIssue(id: string, body: string, author: string,
 // The FALLBACK CHAIN of candidates a reply loops in ([[mentions]] loop-in / [[remark-substrate]] R3's dispatch
 // clause), tried in order until one is online. A plain thread's only candidate is its author (`by`). An
 // EVAL-COMMENT thread (concern `eval: <node> · <scenario>`, the eval-remark track) chains: the agent who FILED
-// the reading the remark judges FIRST, then — when that filer is offline/absent — the NODE's governing session,
-// so an unresolved remark still REACHES an agent who can act on it. This is notification only; it resolves
-// nothing (R3: resolve is a deliberate `spex resolve`). Non-eval threads pay nothing (no yatsu/specs import).
+// the reading the remark judges FIRST — resolved from the TRUNK sidecar, then from each LIVE session's
+// WORKTREE (an in-flight reading, filed on an unmerged branch, is invisible to the trunk — exactly the
+// review-time case, when the filer sits online awaiting review and the remark must reach them) — then, when
+// every filer is offline/absent, the NODE's governing session, so an unresolved remark still REACHES an agent
+// who can act on it. A broken/absent worktree sidecar falls through silently — one bad worktree never fails
+// the remark write. This is notification only; it resolves nothing (R3: resolve is a deliberate
+// `spex resolve`). Non-eval threads pay nothing (no yatsu/specs/sessions import).
 const EVAL_CONCERN_RE = /^eval: (.+?) · (.+)$/   // node first (never contains ' · '), then the scenario (may)
 async function threadOriginators(thread: Issue): Promise<(string | null)[]> {
   const m = EVAL_CONCERN_RE.exec(thread.concern)
   if (!m) return [thread.by]
   const node = m[1].trim(), scenario = m[2].trim()
   const { evalReadingFiler } = await import('../../spec-yatsu/src/filing.js')
-  return [evalReadingFiler(node, scenario), await nodeGoverningSession(node)]
+  const chain: (string | null)[] = [evalReadingFiler(node, scenario)]
+  try {
+    const { listSessions } = await import('./sessions.js')
+    for (const s of await listSessions()) {
+      try { if (s.path) chain.push(evalReadingFiler(node, scenario, s.path)) } catch { /* one unreadable worktree → next link */ }
+    }
+  } catch { /* sessions unavailable (bare store, no tmux) → trunk-only chain, as before */ }
+  chain.push(await nodeGoverningSession(node))
+  return chain
 }
 
 // A node's governing session — the `session` its spec resolves to (the Session: trailer of its latest version,