spexcode 0.5.2 → 0.5.4

package/spec-cli/src/layout.ts

@@ -1,13 +1,15 @@
 import { readFileSync, existsSync, readdirSync } from 'node:fs'
 import { join, dirname } from 'node:path'
-import { homedir } from 'node:os'
 import { git, repoRoot, gitA, headSha, worktreeSpecSig, worktreeSpecDelta, type NodeOp } from './git.js'
 import { guardWorktree } from './resilience.js'
 import { HARNESSES, type HarnessId } from './harness.js'
+import { encodeProject, projectRuntimeRoot, spexcodeHome } from './project-store.js'
 
-type Config = {
+export { encodeProject, spexcodeHome } from './project-store.js'
+
+export type Config = {
   main?: string                    // path to the source-of-truth checkout (default: the `main` worktree)
-  mainBranch?: string              // source-of-truth BRANCH worktrees fork from (default: auto-detected — see mainBranch())
+  mainBranch?: string              // stable source-of-truth branch stamped by init (default: "main")
   branchPrefix?: string            // how a branch names its node (default: "node/")
   preset?: string                  // the SELECTED init preset — which cumulative .plugins tier `spex init` seeds (default 'default'; seed-time only, no launcher gate; read by init.ts; see [[init-preset]])
   // RETIRED ([[residence]]) — the old three-word footprint vote. Materialized artifacts carry no facts and are never
@@ -38,6 +40,13 @@ type Config = {
     launchers?: { [name: string]: { harness?: HarnessId; cmd: string } }
     defaultLauncher?: string       // the launcher a create with no explicit --launcher/dropdown pick uses; required for no-choice creates
   }
+  resources?: {
+    sessionRssMiB?: number         // resident-memory budget for one session owner (default 1024)
+    backendRssMiB?: number         // resident-memory budget for this project's backend instance (default 2048)
+    idleCpuPercent?: number        // CPU budget for a non-progressing owner (default 2)
+    sampleMs?: number              // CPU measurement window for an on-demand report (default 1000)
+    reportIntervalMs?: number      // supervisor-owned snapshot cadence (default 60000)
+  }
   serve?: {
     // public-exposure config for `spex serve --public` (resolved gateway-side; see [[public-mode]] / gateway.ts).
     // The password is NEVER read from here — flag/env only — so this file stays committable.
@@ -58,11 +67,12 @@ type Config = {
 // `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' | 'forge' | 'private' | 'render'>>
+type Convention = Required<Omit<Config, 'dashboard' | 'sessions' | 'resources' | 'serve' | 'harnesses' | 'preset' | 'issues' | 'forge' | 'private' | 'render'>>
 
 export type Worktree = {
   path: string; branch: string | null; node: string | null
   session: string | null; status: string | null; isMain: boolean
+  liveness?: 'offline' | 'unknown'
   ops: NodeOp[]   // pending spec-node changes this worktree makes vs main (the board's overlay)
 }
 export type Layout = { main: string; convention: Convention; worktrees: Worktree[] }
@@ -104,13 +114,9 @@ export function gitCommonDir(): string {
 }
 
 export function mainBranch(): string {
-  try {
-    const override = readConfig(mainCheckout()).mainBranch?.trim()
-    if (override) return override
-    const cur = git(['-C', mainCheckout(), 'symbolic-ref', '--short', 'HEAD']).trim()
-    if (cur) return cur
-  } catch { /* fall through to the conventional default */ }
-  return 'main'
+  let checkout: string
+  try { checkout = mainCheckout() } catch { return 'main' }
+  return readConfig(checkout).mainBranch?.trim() || 'main'
 }
 
 // the MAIN checkout (the root working tree) for a project — the SAME answer from main OR any linked worktree
@@ -132,14 +138,8 @@ export function mainCheckout(proj?: string): string {
 // so the board enumerates ONE directory. This is the single seam that knows where the store sits; sessions.ts
 // and the shell hooks resolve through the SAME scheme (the hooks reimplement it in bash, so any change here
 // must be mirrored in .plugins/core/*/). SPEXCODE_HOME overrides the root for test isolation.
-export function spexcodeHome(): string {
-  return process.env.SPEXCODE_HOME || join(homedir(), '.spexcode')
-}
 // encode a project-root path into ONE safe directory segment (Claude's scheme: path separators → '-'). The
 // SAME transform runs in TS and in the shell hooks, so a board read and a hook write land on the SAME dir.
-export function encodeProject(root: string): string {
-  return root.replace(/[/.]/g, '-')
-}
 // 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).
@@ -149,7 +149,7 @@ 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)))
+  return projectRuntimeRoot(gcd)
 }
 // the per-WORKTREE materialize slot — <runtime>/trees/<enc(worktree-toplevel)> — holding the materialize
 // products that are a pure function of ONE tree's .plugins (hooks-manifest, content-hash, plugin-folders).
@@ -178,9 +178,61 @@ export type RawRecord = {
   node: string | null; title: string | null; name: string | null; parent?: string | null
   status: string; proposal: string | null; merges: number; note: string | null
   sortkey: number | null; createdAt: number; harness?: string; harness_session_id?: string
+  stopped?: boolean
+  archived?: boolean  // the human ARCHIVED this session ([[archive]]) — only a proven cold/offline row; absent → false on old records
+  cold_proof?: string  // durable exact leaf + adapter cold proof; absent on legacy archives, which remain visible hazards
+  adapter_recovery?: string // explicit lifecycle recovery required after a partial adapter mutation; absent on old records
   launcher?: string   // the launcher profile this session was created under ([[launcher-select]]); absent/empty only on old records predating launchers
   launch_cmd?: string // the RESOLVED base launcher command PINNED at creation, so a resume replays the EXACT launcher (and its config-dir env) that made the conversation, never a since-changed default ([[launcher-select]] resume-launcher-pin); absent → old record, fall back to the launcher name / ambient
+  launch_readiness_pending?: '' | RawLaunchReadinessPending
+}
+
+export const SESSION_LIFECYCLES = ['active', 'idle', 'awaiting', 'parked', 'error', 'asking', 'queued'] as const
+export const SESSION_PROPOSALS = ['merge', 'nothing', 'close'] as const
+export type SessionLifecycle = typeof SESSION_LIFECYCLES[number]
+export type SessionProposal = typeof SESSION_PROPOSALS[number]
+const sessionLifecycles = new Set<string>(SESSION_LIFECYCLES)
+const sessionProposals = new Set<string>(SESSION_PROPOSALS)
+export const isSessionLifecycle = (value: unknown): value is SessionLifecycle =>
+  typeof value === 'string' && sessionLifecycles.has(value)
+export const isSessionProposal = (value: unknown): value is SessionProposal =>
+  typeof value === 'string' && sessionProposals.has(value)
+
+export type RawLaunchReadinessOriginal = {
+  status: string
+  proposal: string | null
+  note: string | null
+  stopped: boolean
+  archived: boolean
+  cold_proof: string | null
+  adapter_recovery: string | null
 }
+
+export type RawLaunchReadinessPending = {
+  version: 1
+  startedAt: number
+  original: RawLaunchReadinessOriginal
+}
+
+// A launch candidate is durable before it is public. Readers of the authored lifecycle use this one parser
+// so the board and the independent timeline observer cannot disagree about an in-flight resume. Invalid
+// pending bytes throw: a damaged publication fence is unknowable state, never permission to project online.
+export function rawLaunchReadinessOriginal(raw: RawRecord): RawLaunchReadinessOriginal | null {
+  const pending = raw.launch_readiness_pending
+  if (pending == null || pending === '') return null
+  const original = pending && typeof pending === 'object' ? pending.original : null
+  if (pending.version !== 1 || !Number.isFinite(pending.startedAt) || !original || typeof original !== 'object'
+    || !isSessionLifecycle(original.status)
+    || !(original.proposal === null || original.proposal === '' || isSessionProposal(original.proposal))
+    || !(typeof original.note === 'string' || original.note === null)
+    || typeof original.stopped !== 'boolean' || typeof original.archived !== 'boolean'
+    || !(typeof original.cold_proof === 'string' || original.cold_proof === null)
+    || !(typeof original.adapter_recovery === 'string' || original.adapter_recovery === null)) {
+    throw new Error(`session '${raw.session_id}' has an invalid launch_readiness_pending fence`)
+  }
+  return original
+}
+
 // the agent's OWN session id from the environment — the only locator now that the record left the worktree.
 // Three tiers, in order:
 //   (1) a harness's per-thread env var (`sessionEnvVar`) RESOLVED VIA THE ALIAS — when it lands on a governed
@@ -211,11 +263,80 @@ export function envSessionId(): string | null {
   for (const h of HARNESSES) { const v = process.env[h.sessionEnvVar]; if (v && v.trim()) return v.trim() }
   return null
 }
-export function readRawRecord(id: string): RawRecord | null {
+// @@@ RecordEntry - a record read has THREE outcomes, and collapsing them is what let a live session read as
+// "no session record". ABSENT (no file) is the legitimate nothing — a self-launched agent that only ever wrote
+// spec-discipline sentinels has a store dir and no record. CORRUPT (present but unparseable, or parseable but
+// not a record) is a FACT about a session that exists, so it must reach the surfaces as itself instead of
+// masquerading as absence: sessions-core refuses every writer on it and the board gives it its own row. Any
+// OTHER read failure (permissions, I/O) still THROWS — a transient fault must not read as either.
+export type RecordEntry =
+  | { kind: 'ok'; raw: RawRecord }
+  | { kind: 'absent' }
+  | { kind: 'corrupt'; path: string; error: string }
+
+export type PublicRecordEntry =
+  | { kind: 'ok'; raw: RawRecord; liveness: 'offline' | null }
+  | { kind: 'absent' }
+  | { kind: 'corrupt'; sessionId: string; governed: boolean | null; path: string; error: string; liveness: 'unknown' }
+
+export function readRecordEntry(id: string): RecordEntry {
+  const path = sessionRecordPath(id)
+  let text: string
+  try { text = readFileSync(path, 'utf8') }
+  catch (e) { if ((e as NodeJS.ErrnoException).code === 'ENOENT') return { kind: 'absent' }; throw e }
+  let raw: unknown
+  try { raw = JSON.parse(text) }
+  catch (e) { return { kind: 'corrupt', path, error: e instanceof Error ? e.message : String(e) } }
+  if (!raw || typeof raw !== 'object' || !(raw as RawRecord).session_id)
+    return { kind: 'corrupt', path, error: 'parsed, but carries no session_id — not a session record' }
+  return { kind: 'ok', raw: raw as RawRecord }
+}
+
+// The ONE public session-record parser. Internal mutation/readiness code uses readRecordEntry's exact raw
+// candidate; every public projection passes through here. A valid pending fence replaces all lifecycle-facing
+// fields with its frozen original and forces offline liveness. Malformed pending bytes remain a present,
+// corrupt/unknown row instead of leaking candidate state or disappearing as absence.
+export function projectPublicRecordEntry(id: string, entry: RecordEntry): PublicRecordEntry {
+  if (entry.kind === 'absent') return entry
+  if (entry.kind === 'corrupt') return {
+    kind: 'corrupt', sessionId: id, governed: null, path: entry.path, error: entry.error, liveness: 'unknown',
+  }
   try {
-    const raw = JSON.parse(readFileSync(sessionRecordPath(id), 'utf8'))
-    return raw && typeof raw === 'object' && raw.session_id ? raw as RawRecord : null
-  } catch { return null }
+    const original = rawLaunchReadinessOriginal(entry.raw)
+    if (!original) return { kind: 'ok', raw: entry.raw, liveness: null }
+    return {
+      kind: 'ok',
+      raw: {
+        ...entry.raw,
+        status: original.status,
+        proposal: original.proposal || null,
+        note: original.note || null,
+        stopped: original.stopped,
+        archived: original.archived,
+        cold_proof: original.cold_proof ?? undefined,
+        adapter_recovery: original.adapter_recovery ?? undefined,
+        launch_readiness_pending: '',
+      },
+      liveness: 'offline',
+    }
+  } catch (error) {
+    return {
+      kind: 'corrupt',
+      sessionId: id,
+      governed: typeof entry.raw.governed === 'boolean' ? entry.raw.governed : null,
+      path: sessionRecordPath(id),
+      error: error instanceof Error ? error.message : String(error),
+      liveness: 'unknown',
+    }
+  }
+}
+
+export function readPublicRecordEntry(id: string): PublicRecordEntry {
+  return projectPublicRecordEntry(id, readRecordEntry(id))
+}
+export function readRawRecord(id: string): RawRecord | null {
+  try { const e = readRecordEntry(id); return e.kind === 'ok' ? e.raw : null }
+  catch { return null }
 }
 // resolve a possibly-ALIASED session id to its raw record. A codex hook or spawned command can carry the codex
 // THREAD id — payload session_id / CODEX_THREAD_ID — not the SpexCode record id the store is keyed by. Direct id
@@ -223,13 +344,20 @@ export function readRawRecord(id: string): RawRecord | null {
 // before any tool turn).
 // Null when neither resolves. Mirrors the shell `hp_store_dir` alias grep — one resolution rule, both layers.
 export function readAliasedRawRecord(id: string): RawRecord | null {
-  const direct = readRawRecord(id)
-  if (direct) return direct
+  const e = readAliasedRecordEntry(id)
+  return e.kind === 'ok' ? e.raw : null
+}
+// the same alias resolution, keeping the three-way outcome. A CORRUPT record at the direct id settles the
+// question — we found this session and cannot read it; walking on to the alias would report a corrupt record
+// as absent, the exact collapse this type exists to prevent.
+export function readAliasedRecordEntry(id: string): RecordEntry {
+  const direct = readRecordEntry(id)
+  if (direct.kind !== 'absent') return direct
   for (const sid of listSessionIds()) {
     const r = readRawRecord(sid)
-    if (r && r.harness_session_id && r.harness_session_id === id) return r
+    if (r && r.harness_session_id && r.harness_session_id === id) return { kind: 'ok', raw: r }
   }
-  return null
+  return { kind: 'absent' }
 }
 // every session_id this project has a record for (the board's enumeration source — replaces `git worktree
 // list`). A MISSING store dir means no session ever launched → []. But any OTHER readdir failure THROWS
@@ -242,24 +370,27 @@ export function listSessionIds(): string[] {
   return ents.filter((d) => d.isDirectory()).map((d) => d.name)
 }
 
-// memo the overlay (3 git diffs/worktree) keyed on fork-point merge-base + HEAD + spec sig — keying on the
-// merge-base NOT main's HEAD means unrelated merges that don't move the fork point stay cache hits.
+// memo the overlay (4 git diffs/worktree, all .spec-scoped) keyed on fork-point merge-base + HEAD + spec
+// sig + MAIN'S TIP ([[worktree-linker]]): the main-tip component is what lets a merge landing identical
+// content dissolve a worktree's now-moot ops — the recompute it triggers is cheap because every diff is
+// .spec-scoped.
 const deltaCache = new Map<string, { key: string; ops: NodeOp[] }>()
 const safeHead = (p: string): string => { try { return headSha(p) } catch { return '' } }
 const safeMergeBase = async (wtPath: string, mainRef: string): Promise<string> => {
   try { return (await gitA(['-C', wtPath, 'merge-base', mainRef, 'HEAD'])).trim() } catch { return '' }
 }
 let layoutHeadWarned = false
-async function cachedDelta(wtPath: string, mainRef: string): Promise<NodeOp[]> {
+async function cachedDelta(wtPath: string, mainRef: string, mainSha: string): Promise<NodeOp[]> {
   const wtHead = safeHead(wtPath)
   const base = await safeMergeBase(wtPath, mainRef)
-  // fail loud, never stale: if the merge-base or HEAD can't be read the key is untrustworthy — bypass the
-  // cache and recompute (warn once) rather than risk serving a delta keyed on an empty sha across a real change.
-  if (!base || !wtHead) {
-    if (!layoutHeadWarned) { layoutHeadWarned = true; console.warn('spec-cli: layout overlay cache bypassed (unreadable merge-base/HEAD), recomputing every read') }
+  // fail loud, never stale: if the merge-base, HEAD, or main tip can't be read the key is untrustworthy —
+  // bypass the cache and recompute (warn once) rather than risk serving a delta keyed on an empty sha
+  // across a real change.
+  if (!base || !wtHead || !mainSha) {
+    if (!layoutHeadWarned) { layoutHeadWarned = true; console.warn('spec-cli: layout overlay cache bypassed (unreadable merge-base/HEAD/main tip), recomputing every read') }
     return worktreeSpecDelta(wtPath, mainRef)
   }
-  const key = `${base}\0${wtHead}\0${worktreeSpecSig(wtPath)}`
+  const key = `${base}\0${wtHead}\0${mainSha}\0${worktreeSpecSig(wtPath)}`
   const hit = deltaCache.get(wtPath)
   if (hit && hit.key === key) return hit.ops
   const ops = await worktreeSpecDelta(wtPath, mainRef, base)
@@ -284,20 +415,37 @@ export async function resolveLayout(): Promise<Layout> {
   // independent → compute (or cache-hit) in parallel, keyed by worktree path as before. guardWorktree wraps
   // each: a worktree whose dir was genuinely removed mid-read (a worker self-merged + retired it) is OMITTED;
   // one that still exists but hit a transient detail failure is kept as a DEGRADED row from the last cached delta.
-  const records = listSessionIds().map(readRawRecord).filter((r): r is RawRecord => !!r && r.governed)
-  const rows = await Promise.all(records.map((r) => {
+  const publicEntries = listSessionIds().map((id) => readPublicRecordEntry(id))
+    .filter((entry) => entry.kind === 'corrupt' ? entry.governed !== false : entry.kind === 'ok' && entry.raw.governed)
+  const records = publicEntries.flatMap((entry) => entry.kind === 'ok' ? [entry] : [])
+  // main's tip, resolved ONCE per board read — a component of every worktree's overlay cache key
+  // ([[worktree-linker]]: landed content must dissolve the ops it made moot).
+  const mainSha = await (async () => {
+    try { return (await gitA(['-C', main, 'rev-parse', '--verify', `${mainRef}^{commit}`])).trim() } catch { return '' }
+  })()
+  const rows = await Promise.all(records.map(({ raw: r, liveness }) => {
     const node = r.node ?? (r.branch && r.branch.startsWith(convention.branchPrefix) ? r.branch.slice(convention.branchPrefix.length) : null)
-    const base: Worktree = { path: r.worktree_path, branch: r.branch, node, session: r.session_id, status: r.status, isMain: false, ops: [] }
+    const base: Worktree = { path: r.worktree_path, branch: r.branch, node, session: r.session_id, status: r.status, isMain: false, ...(liveness ? { liveness } : {}), ops: [] }
+    // @@@ archived rows cost nothing - a shelved session ([[archive]]) keeps its row (the record is the
+    // existence truth) but skips the per-worktree spec-delta entirely: that git-history probe is the board's
+    // dominant per-row cost, and shelving is exactly the human saying "stop spending attention here". So the
+    // price of a retained archive is one enumerated record, NOT a git walk per poll.
+    if (r.archived) return Promise.resolve(base)
     return guardWorktree<Worktree>(r.worktree_path,
-      async (): Promise<Worktree> => ({ ...base, ops: await cachedDelta(r.worktree_path, mainRef) }),
+      async (): Promise<Worktree> => ({ ...base, ops: await cachedDelta(r.worktree_path, mainRef, mainSha) }),
       (): Worktree => ({ ...base, ops: deltaCache.get(r.worktree_path)?.ops ?? [] }))
   }))
-  const sessionWorktrees = rows.filter((w): w is Worktree => w !== null)
+  const corruptRows: Worktree[] = publicEntries.flatMap((entry) => entry.kind === 'corrupt'
+    ? [{ path: '', branch: null, node: null, session: entry.sessionId, status: 'corrupt', liveness: 'unknown', isMain: false, ops: [] }]
+    : [])
+  const sessionWorktrees = [...rows.filter((w): w is Worktree => w !== null), ...corruptRows]
   // the main checkout row (isMain) — always present, carries no overlay; it anchors the merged tree the board draws.
   const mainRow: Worktree = { path: main, branch: base, node: null, session: null, status: null, isMain: true, ops: [] }
   const worktrees = [mainRow, ...sessionWorktrees]
-  // drop cache entries for worktrees no longer in the store (closed sessions), so the map stays bounded.
-  const live = new Set(sessionWorktrees.map((w) => w.path))
+  // drop cache entries for worktrees that may no longer hold one — closed sessions (gone from the store) AND
+  // newly-archived ones (which no longer compute a delta), so archiving SELF-EVICTS its cached ops instead of
+  // stranding them in a map nothing prunes.
+  const live = new Set(records.filter(({ raw }) => !raw.archived).map(({ raw }) => raw.worktree_path))
   for (const k of [...deltaCache.keys()]) if (!live.has(k)) deltaCache.delete(k)
   return { main: convention.main || main || root, convention, worktrees }
 }

package/spec-cli/src/lint.ts

@@ -1,9 +1,9 @@
 import { readFileSync, existsSync, statSync } from 'node:fs'
 import { join } from 'node:path'
-import { repoRoot, git, driftIndex, historyIndex, rowsFor } from './git.js'
-import { loadSpecs } from './specs.js'
+import { repoRoot, git, sourceIndexes, rowsFor, treeFilePaths, treeFileText } from './git.js'
+import { loadSpecs, parseFrontmatter } from './specs.js'
 import { readJsonConfig } from './layout.js'
-import { extractors, extractorFor, extOf, resolveAnchor, windowCommits, anchorHitCommits } from './anchors.js'
+import { extractors, extractorFor, extOf, parseCodeEntry, relationClaimsPath, resolveAnchor, windowEvents, anchorHitCommits } from './anchors.js'
 import { DEFAULT_TEST_GLOBS, sourcePolicyDescription, trackedSourceFiles } from './source-files.js'
 
 export type Finding = { level: 'error' | 'warn'; rule: string; spec?: string; file?: string; msg: string }
@@ -31,10 +31,17 @@ const DEFAULT_CONFIG: LintConfig = {
   scenarioTags: ['frontend-e2e', 'backend-api', 'cli', 'desktop', 'mobile'],
   scopedCodeMiss: 'warn',
 }
-export function loadConfig(root: string): LintConfig {
+export function loadConfig(root: string, pendingSource?: string | null): LintConfig {
   // Absent spexcode.json → tuned defaults; a MALFORMED one throws LOUD (readJsonConfig) rather than
   // silently reverting the author's budgets to defaults and green-washing the very warnings they tuned.
-  const c = readJsonConfig(join(root, 'spexcode.json'))?.lint ?? {}
+  let parsed: any
+  if (pendingSource === undefined) parsed = readJsonConfig(join(root, 'spexcode.json'))
+  else if (pendingSource === null) parsed = {}
+  else {
+    try { parsed = JSON.parse(pendingSource) }
+    catch (e: any) { throw new Error(`invalid JSON in candidate spexcode.json: ${e?.message ?? e}`) }
+  }
+  const c = parsed?.lint ?? {}
   const merged = { ...DEFAULT_CONFIG, ...c }
   return normalizeConfig(merged)
 }
@@ -61,11 +68,92 @@ export function normalizeConfig(cfg: LintConfig): LintConfig {
   }
 }
 
-export async function specLint(): Promise<Finding[]> {
-  const root = repoRoot()
-  const cfg = loadConfig(root)
-  const governed = trackedSourceFiles(root, cfg.governedRoots, cfg)
-  const specs = await loadSpecs()
+export type SpecLintOptions = { tip?: string }
+
+function untrackedAdoptionFiles(root: string): string[] {
+  if (git(['-C', root, 'rev-parse', '--is-inside-work-tree']).trim() !== 'true') return []
+  const status = git([
+    '-C', root,
+    '-c', 'core.quotePath=false',
+    'status', '--porcelain=v1', '-z', '--untracked-files=all',
+    '--', '.spec', 'spexcode.json',
+  ])
+  return status.split('\0')
+    .filter((entry) => entry.startsWith('?? '))
+    .map((entry) => entry.slice(3))
+    .filter(Boolean)
+}
+
+function pendingChangedPaths(root: string, tip: string): string[] {
+  try {
+    git(['-C', root, 'rev-parse', `${tip}^{commit}`])
+    // `-m` compares a merge with every parent. An `ours` merge can leave the result tree
+    // identical to its first parent while still making an unacknowledged side-branch commit
+    // reachable; first-parent-only paths would filter that debt out of the pending anchor window.
+    const fields = git(['-C', root, '-c', 'core.quotePath=false', 'diff-tree', '--no-commit-id', '--name-status', '-z', '-r', '-m', '-M', tip])
+      .split('\0').filter(Boolean)
+    const changed: string[] = []
+    for (let i = 0; i < fields.length;) {
+      const status = fields[i++]
+      if (/^[RC]/.test(status)) {
+        changed.push(fields[i++], fields[i++])
+      } else {
+        changed.push(fields[i++])
+      }
+    }
+    return [...new Set(changed.filter(Boolean))]
+  } catch { return [] }
+}
+// Cheap pending classification for the reference hook. It reads only the candidate tree and claims; it
+// never constructs either history index. A normal lint call deliberately does not use this
+// shortcut so its full findings/oracle contract remains unchanged.
+export async function pendingTouchesGoverned(root: string, tip: string): Promise<boolean> {
+  // A merge can introduce reachable side-branch debt without changing the result tree. The first-parent
+  // diff is insufficient for a scope proof, so all multi-parent candidates stay on the full lint path.
+  const parentCount = git(['-C', root, 'rev-list', '--parents', '-n1', tip]).trim().split(/\s+/).length - 1
+  if (parentCount > 1) return true
+  const changed = pendingChangedPaths(root, tip)
+  if (!changed.length) return true
+  // `governedRoots` is source discovery policy, not the set of actual code claims: a spec may deliberately
+  // govern a path outside those roots. Read only the candidate spec tree (no history/drift indexes) so the
+  // scope proof follows the same code:/related: declarations that lint later enforces.
+  const specs = await loadSpecs(root, { tip, history: null, drift: null })
+  const claims = specs.flatMap((spec) => [...spec.code, ...spec.related])
+  return changed.some((path) => claims.some((claim) => relationClaimsPath(claim, path))
+    || path === 'spexcode.json' || path === 'spexcode.local.json'
+    || (path.startsWith('.spec/') && !path.startsWith('.spec/.issues/'))
+    || path === '.spec')
+}
+
+export async function specLint(root = repoRoot(), regs = extractors(root), options: SpecLintOptions = {}): Promise<Finding[]> {
+  const tip = options.tip ?? 'HEAD'
+  const pending = tip !== 'HEAD'
+  const changed = pending ? pendingChangedPaths(root, tip) : []
+  const files = pending ? treeFilePaths(root, tip) : null
+  const directories = new Set<string>()
+  for (const file of files ?? []) {
+    const parts = file.split('/')
+    for (let i = 1; i < parts.length; i++) directories.add(parts.slice(0, i).join('/'))
+  }
+  const existsAtTip = (path: string) => files ? files.has(path) || directories.has(path.replace(/\/+$/, '')) : existsSync(join(root, path))
+  const isDirectoryAtTip = (path: string) => files
+    ? !files.has(path) && directories.has(path.replace(/\/+$/, ''))
+    : statSync(join(root, path)).isDirectory()
+  const textAtTip = (path: string) => pending ? treeFileText(root, tip, path) : readFileSync(join(root, path), 'utf8')
+  const cfg = loadConfig(root, pending ? treeFileText(root, tip, 'spexcode.json') : undefined)
+  const untracked = untrackedAdoptionFiles(root)
+  if (untracked.length) {
+    const shown = untracked.slice(0, 6)
+    const suffix = untracked.length > shown.length ? ` (+${untracked.length - shown.length} more)` : ''
+    return [{
+      level: 'error',
+      rule: 'integrity',
+      msg: `project source of truth is untracked: ${shown.join(', ')}${suffix} — add it with \`git add .spec spexcode.json\` and commit it; generated harness files such as .codex/, .claude/, and AGENTS.md are machine-local`,
+    }]
+  }
+  const governed = trackedSourceFiles(root, cfg.governedRoots, cfg, tip)
+  const [hidx, didx] = await sourceIndexes(root, tip)
+  const specs = await loadSpecs(root, { tip, history: hidx, drift: didx })
   const out: Finding[] = []
 
   // integrity + build the file -> owners map. A relation's STRUCTURAL problems (a duplicate entry,
@@ -73,14 +161,16 @@ export async function specLint(): Promise<Finding[]> {
   // [[code-anchor]]) are integrity errors: malformed edges block like broken ones.
   const owners = new Map<string, string[]>()
   const claimed = new Set<string>()
+  const governedClaims = new Set<string>()
   for (const s of specs) {
     for (const p of s.relationProblems)
       out.push({ level: 'error', rule: 'integrity', spec: s.id, msg: `'${s.id}' ${p}` })
     const scopedPaths = new Set(s.codeScoped.map((e) => e.path))
     for (const f of s.code) {
-      if (!existsSync(join(root, f)))
+      if (!existsAtTip(f))
         out.push({ level: 'error', rule: 'integrity', spec: s.id, file: f, msg: `spec '${s.id}' lists a missing file: ${f}` })
       claimed.add(f)
+      governedClaims.add(f)
       // a selector-SCOPED entry claims named units, not the whole file, so it stays out of the owners
       // bound below ([[code-anchor]]) — `spex spec owner` still displays it as a (scoped) governor.
       if (!scopedPaths.has(f)) owners.set(f, [...(owners.get(f) ?? []), s.id])
@@ -96,11 +186,34 @@ export async function specLint(): Promise<Finding[]> {
   // `related:` is the coverage net: govern is a sharp ideally-one-file pointer, so most files are reached by
   // related, not govern (see [[governed-related]]). It carries coverage but never drift, never eval freshness.
   for (const s of specs) for (const f of s.related) {
-    if (!existsSync(join(root, f)))
+    if (!existsAtTip(f))
       out.push({ level: 'error', rule: 'integrity', spec: s.id, file: f, msg: `spec '${s.id}' lists a missing related file: ${f}` })
     claimed.add(f)
   }
 
+  // A candidate may retire a node together with the implementation it owned, or transfer that path to a
+  // new node. It may not delete the governor while leaving the governed subject behind: ordinary coverage
+  // is advisory, so without this transition check a candidate could erase the very contract that would
+  // reject its code change. Read only deleted spec blobs from HEAD; no second history index is needed.
+  if (pending) {
+    let deleted: string[] = []
+    try {
+      deleted = git(['-C', root, '-c', 'core.quotePath=false', 'diff', '--diff-filter=D', '--name-only', 'HEAD', tip, '--', '.spec'])
+        .split('\n').map((path) => path.trim()).filter((path) => path.endsWith('/spec.md'))
+    } catch { /* an unreadable comparison is already surfaced by the candidate history reads */ }
+    for (const specPath of deleted) {
+      const oldSource = treeFileText(root, 'HEAD', specPath)
+      if (oldSource === null) continue
+      const value = parseFrontmatter(oldSource).fm.code
+      const rows = Array.isArray(value) ? value : value ? [value] : []
+      for (const row of rows) {
+        const path = parseCodeEntry(row).path
+        if (existsAtTip(path) && !governedClaims.has(path))
+          out.push({ level: 'error', rule: 'integrity', file: path, msg: `candidate deletes governor '${specPath}' but leaves its governed subject '${path}' without a code: owner — delete the retired implementation too, or transfer it to a real node in this commit` })
+      }
+    }
+  }
+
   // id-format: a node id (its leaf dir basename) passes an EXACT per-character whitelist — an ascii char
   // must be [a-z0-9-]; a non-ascii char must be a unicode letter/number (judged on NFC, the mint's
   // canonical form) — and is UNIQUE tree-wide (ERROR). This is THE id vocabulary, defined once (the
@@ -200,23 +313,22 @@ export async function specLint(): Promise<Finding[]> {
 
   // code anchors ([[code-anchor]]): a code:/related: entry may pin named units (`path#symbol` — any
   // number per base file, OR'd). On code:, the anchor is the BLOCKING tier of drift: a window
-  // commit (spec's last version..HEAD, non-merge, touching the governed file) whose --unified=0 hunks
+  // commit (spec's last version..tip, ordinary diff or merge-authored combined diff) whose zero-context hunks
   // intersect any pinned unit's line range — extracted from the file AS OF that commit, by the
   // extension's ONE designated extractor — is ONE anchor-drift ERROR naming the hit selectors, unless a
   // Spec-OK ack covers it. On related:, the SAME engine yields only a soft warn on a hit — a scoped
   // related miss is silent (never blocks, no ack, no eval freshness). Resolution failures are never
-  // silent for either relation: a dead or ambiguous selector, a selector on a directory, an unparseable
-  // working-tree file, an extension with no designated extractor, and a designated extractor that can't
-  // run here (no host typescript) all ERROR with the repair spelled out.
-  const regs = extractors(root)
-  const [didx, hidx] = await Promise.all([driftIndex(root), historyIndex(root)])
+  // silent for either relation: a dead or ambiguous selector, a selector on a directory, and an
+  // unparseable working-tree file ERROR. An extension with no designated extractor, or a designated
+  // extractor that cannot run here, also ERRORS but skips those anchors so the remaining checks continue.
   const readyWarned = new Set<string>()
   for (const s of specs) {
     for (const { relation, entries } of [{ relation: 'code' as const, entries: s.codeScoped }, { relation: 'related' as const, entries: s.relatedScoped }]) {
       for (const { path, selectors } of entries) {
+        if (pending && !changed.some((file) => relationClaimsPath(path, file))) continue
         const x = extractorFor(regs, extOf(path))
         if (!x) {
-          out.push({ level: 'error', rule: 'integrity', spec: s.id, file: path, msg: `'${s.id}' anchors ${path}#${selectors.join(', #')} (${relation}:), but no extractor is designated for '.${extOf(path)}' files — this language has no anchor support yet: add a LangSpec row (anchors.ts) or drop the selector(s)` })
+          out.push({ level: 'error', rule: 'integrity', spec: s.id, file: path, msg: `'${s.id}' anchors ${path}#${selectors.join(', #')} (${relation}:), but no extractor is designated for '.${extOf(path)}' files — anchor validation was skipped and remains unverified; add a LangSpec row (anchors.ts) or drop the selector(s)` })
           continue
         }
         const ready = x.ready()
@@ -225,13 +337,17 @@ export async function specLint(): Promise<Finding[]> {
           if (!readyWarned.has(x.id + ready)) { readyWarned.add(x.id + ready); out.push({ level: 'error', rule: 'integrity', msg: `anchor extractor '${x.id}' cannot run: ${ready}` }) }
           continue
         }
-        if (!existsSync(join(root, path))) continue // the missing FILE already errored above
-        if (statSync(join(root, path)).isDirectory()) {
+        if (!existsAtTip(path)) continue // the missing FILE already errored above
+        if (isDirectoryAtTip(path)) {
           out.push({ level: 'error', rule: 'integrity', spec: s.id, file: path, msg: `'${s.id}' puts a selector on a directory (${relation}: ${path}#${selectors[0]}) — a selector scopes ONE real file` })
           continue
         }
         let units
-        try { units = x.extract(readFileSync(join(root, path), 'utf8'), path) } catch (e: any) {
+        try {
+          const source = textAtTip(path)
+          if (source === null) throw new Error(`candidate tree has no file '${path}'`)
+          units = x.extract(source, path)
+        } catch (e: any) {
           out.push({ level: 'error', rule: 'integrity', spec: s.id, file: path, msg: `anchor ${path}#${selectors.join(', #')} ('${s.id}') is unverifiable — the current file does not parse: ${e?.message ?? e}` })
           continue
         }
@@ -253,17 +369,26 @@ export async function specLint(): Promise<Finding[]> {
         }
         if (!live.length) continue
         const since = rowsFor(hidx, s.path)[0]?.hash || ''
-        const win = windowCommits(didx, since, path)
+        const win = windowEvents(didx, since, path, s.id)
         if (!win.length) continue
-        const hits = await anchorHitCommits(root, win, path, live, x)
+        const hits = await anchorHitCommits(root, win, live, regs)
         if (!hits.length) continue
         const hitSyms = [...new Set(hits.flatMap((h) => h.selectors))]
         const shas = hits.map((h) => h.commit.slice(0, 8)).join(', ')
         const unparseable = hits.filter((h) => h.unparseable)
         const parseNote = unparseable.length ? ` (${unparseable.length} of these could not be parsed at that commit — counted as hits conservatively)` : ''
-        if (relation === 'code')
-          out.push({ level: 'error', rule: 'anchor-drift', spec: s.id, file: path, msg: `${path}#${hitSyms.join(', #')} was changed by ${hits.length} commit(s) since spec '${s.id}' v${s.version} [${shas}]${parseNote} — the anchored contract's code moved: update the spec, or 'spex spec ack ${s.id} --reason "…"' if the contract still holds` })
-        else
+        if (relation === 'code') {
+          const current = pending && hits.some((hit) => hit.commit === tip)
+          const older = pending && hits.some((hit) => hit.commit !== tip)
+          const remedy = !pending
+            ? `update the spec, or 'spex spec ack ${s.id} --reason "…"' if the contract still holds`
+            : current && older
+              ? `update the spec in this commit; its own hit can be declared by retrying with 'git commit --trailer "Spec-OK: ${s.id}" …', but the listed older debt must be cleared first (an in-commit declaration never pardons ancestors)`
+              : current
+                ? `update the spec in this commit, or retry with 'git commit --trailer "Spec-OK: ${s.id}" …'; a later empty ack cannot pre-author this candidate`
+                : `update the spec in this commit, or clear this older debt with 'spex spec ack ${s.id} --reason "…"' before retrying the candidate`
+          out.push({ level: 'error', rule: 'anchor-drift', spec: s.id, file: path, msg: `${path}#${hitSyms.join(', #')} was changed by ${hits.length} commit(s) since spec '${s.id}' v${s.version} [${shas}]${parseNote} — the anchored contract's code moved: ${remedy}` })
+        } else
           out.push({ level: 'warn', rule: 'related-drift', spec: s.id, file: path, msg: `related ${path}#${hitSyms.join(', #')} ('${s.id}') was changed by ${hits.length} commit(s) since v${s.version} [${shas}]${parseNote} — a scoped dependency shifted, worth a glance (SOFT: never blocks, no ack, no eval staleness)` })
       }
     }

package/spec-cli/src/localIssues.ts

@@ -178,11 +178,15 @@ export function loadOne(id: string): Issue {
 }
 
 // a filesystem-safe, readable, collision-free id from the concern (slug + numeric suffix if taken).
+// RESERVED_IDS are the words an issue address gives its own meaning — `new` is the compose PAGE
+// ([[issues-view]]), so an issue owning that id would be unreachable at its own detail address. The slug
+// steps around them with the same numeric suffix a taken id gets: a collision, not a silent shadow.
+const RESERVED_IDS = new Set(['new'])
 function uniqueId(concern: string): string {
   const base = concern.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 48) || 'issue'
   const dir = localStoreDir()
   let id = base
-  for (let n = 2; existsSync(join(dir, `${id}.md`)); n++) id = `${base}-${n}`
+  for (let n = 2; RESERVED_IDS.has(id) || existsSync(join(dir, `${id}.md`)); n++) id = `${base}-${n}`
   return id
 }