spexcode 0.4.0 → 0.4.3

package/spec-cli/src/init.ts

@@ -3,7 +3,7 @@ import { join, resolve, relative } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { execFileSync } from 'node:child_process'
 import { readConfig, readJsonConfig } from './layout.js'
-import { resolveHarnessTargets } from './harness-select.js'
+import { resolveHarnessTargets, parseHarnessFlag, NATIVE_HARNESS_IDS } from './harness-select.js'
 
 // this file lives at <pkgRoot>/src/init.ts, so `..` is the package root — the same derivation the
 // launch paths use, never a hardcoded repo path (so a relocated/installed package still finds its data).
@@ -54,7 +54,7 @@ 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, harnessArg?: string): Promise<void> {
   const targetDir = resolve(targetArg ?? process.cwd())
 
   // the preset the NEW adopter gets — `--preset <name>` wins, else an existing target spexcode.json's
@@ -78,6 +78,24 @@ export async function specInit(targetArg: string | undefined, presetArg?: string
     process.exit(1)
   }
 
+  // the harness DELIVERY TARGET set ([[harness-select]]) is a REQUIRED, explicit choice — `--harness <ids>`
+  // stamps it into spexcode.json; absent the flag, a pre-existing explicit `harnesses` field IS the choice.
+  // Neither → abort BEFORE writing anything: with many harnesses, a silent "deliver to all" would litter the
+  // adopter's tree (and global tool configs) with artifacts for harnesses they never installed. Legality
+  // (unknown ids, plugin exclusivity, empty set) fails loud here too, not as a soft materialize warning.
+  const flagRaw = (harnessArg ?? '').trim() ? parseHarnessFlag(harnessArg!.trim()) : null
+  const chosenHarnesses = flagRaw ?? readConfig(targetDir).harnesses ?? null
+  if (chosenHarnesses === null) {
+    console.error(`spex init: --harness is required — name the harness(es) this repo delivers into, e.g. \`spex init --harness claude\`. Known native ids: ${NATIVE_HARNESS_IDS.join(', ')} (comma-separate several; a plugin bundle: --harness plugin:<folder>). A pre-existing spexcode.json "harnesses" field also satisfies this.`)
+    process.exit(1)
+  }
+  try {
+    resolveHarnessTargets(chosenHarnesses)
+  } catch (e) {
+    console.error(`spex init: ${(e as Error).message}`)
+    process.exit(1)
+  }
+
   if (!existsSync(targetDir)) mkdirSync(targetDir, { recursive: true })
   console.log(`spex init → ${targetDir}`)
 
@@ -100,27 +118,35 @@ export async function specInit(targetArg: string | undefined, presetArg?: string
     }
   }
 
-  // 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 ["."]).
+  // 1b. plant a starter spexcode.json (the lint/layout knob) carrying the CHOSEN `harnesses` set. The
+  // template ships launchers for every native harness; seeding keeps only the SELECTED ones (a launcher for
+  // a tool the adopter didn't pick is exactly the litter --harness exists to prevent) — a plugin-only
+  // selection keeps them all, since the bundle serves the HOST agent while dispatched sessions still need a
+  // launcher. The success message reports values read back from the planted file, never restated literals.
   const cfgDest = join(targetDir, 'spexcode.json')
+  const nativeChosen = (chosenHarnesses as unknown[]).filter((m): m is string => typeof m === 'string')
   if (existsSync(cfgDest)) {
-    console.warn(`• spexcode.json already exists at ${cfgDest} — left untouched.`)
+    if (flagRaw) {
+      // an explicit --harness on a re-init is a deliberate command: restamp THAT field, touch nothing else.
+      const cfg = (readJsonConfig(cfgDest) ?? {}) as Record<string, unknown>
+      cfg.harnesses = flagRaw
+      writeFileSync(cfgDest, JSON.stringify(cfg, null, 2) + '\n')
+      console.log(`✓ stamped "harnesses": ${JSON.stringify(flagRaw)} into the existing spexcode.json (other fields untouched)`)
+    } else {
+      console.warn(`• spexcode.json already exists at ${cfgDest} — left untouched (harnesses: ${JSON.stringify(chosenHarnesses)}).`)
+    }
   } else {
-    copyFileSync(join(TEMPLATES, 'spexcode.json'), cfgDest)
+    const cfg = (readJsonConfig(join(TEMPLATES, 'spexcode.json')) ?? {}) as Record<string, any>
+    cfg.harnesses = chosenHarnesses
+    if (nativeChosen.length && cfg.sessions?.launchers) {
+      cfg.sessions.launchers = Object.fromEntries(
+        Object.entries(cfg.sessions.launchers as Record<string, { harness?: string }>).filter(([, l]) => nativeChosen.includes(l.harness ?? 'claude')))
+      const names = Object.keys(cfg.sessions.launchers)
+      if (names.length) cfg.sessions.defaultLauncher = names[0]
+    }
+    writeFileSync(cfgDest, JSON.stringify(cfg, null, 2) + '\n')
     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`)
-  }
-
-  // validate the harness DELIVERY TARGET set ([[harness-select]]) up front: a bad `harnesses` set (plugin +
-  // native, or a plugin with no folder) must fail LOUD here, not be silently swallowed by the materialize
-  // try/catch below. A fresh starter spexcode.json omits the field (defaults to all natives), so this only
-  // bites a hand-edited or re-init'd config — exactly where a clear error belongs.
-  try {
-    resolveHarnessTargets(readConfig(targetDir).harnesses)
-  } catch (e) {
-    console.error(`spex init: ${(e as Error).message}`)
-    process.exit(1)
+    console.log(`✓ planted spexcode.json — harnesses ${JSON.stringify(chosenHarnesses)}, launchers ${JSON.stringify(Object.keys(cfg.sessions?.launchers ?? {}))}; lint.governedRoots starts as ${roots} (the whole git-tracked tree, tests excluded)`)
   }
 
   // 2. install the git hooks: templates/hooks/* -> <repo>/<common-git-dir>/hooks/* (skip any that exist).
@@ -145,18 +171,20 @@ export async function specInit(targetArg: string | undefined, presetArg?: string
     if (installed.length) console.log(`✓ installed git hooks (${installed.join(', ')}) → ${hooksDir}`)
   }
 
-  // 2c. MATERIALIZE the harness-discovered artifacts so a USER-self-launched claude/codex works with zero further
-  // steps: the hook manifest (in the GLOBAL per-project store, not the worktree), the AGENTS.md/CLAUDE.md
-  // <spexcode> contract block (user content preserved), the .claude/.codex shims, and the Codex trust (global,
-  // scoped) so codex self-launch is prompt-free. Runs with cwd = the target so the loaders read the just-seeded
+  // 2c. MATERIALIZE the harness-discovered artifacts so a USER-self-launched harness works with zero further
+  // steps. Runs with cwd = the target so the loaders read the just-seeded
   // .plugins. Idempotent — the planted git hooks (pre-commit/post-checkout/post-merge) keep it fresh
   // thereafter on the git-native anchors ([[commit-surgery]]); no harness event ever triggers a materialize.
   const prevCwd = process.cwd()
   try {
     process.chdir(targetDir)
     const { materialize } = await import('./materialize.js')
-    materialize(targetDir)
-    console.log('✓ materialized harness artifacts (global hook manifest, AGENTS.md/CLAUDE.md block, harness shims, Codex trust)')
+    const result = materialize(targetDir)
+    const display = (path: string) => {
+      const local = relative(targetDir, path)
+      return local && local !== '..' && !local.startsWith('../') && !local.startsWith('..\\') ? local : path
+    }
+    console.log(`✓ materialized harness artifacts (${result.planted.map((a) => `${a.kind}: ${display(a.path)}`).join(', ')})`)
   } catch (e) {
     console.warn(`• materialize skipped (${(e as Error).message}) — run \`spex materialize\` once the packages are installed.`)
   } finally {

package/spec-cli/src/layout.ts

@@ -3,7 +3,7 @@ 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 } from './harness.js'
+import { HARNESSES, type HarnessId } from './harness.js'
 
 type Config = {
   main?: string                    // path to the source-of-truth checkout (default: the `main` worktree)
@@ -20,13 +20,13 @@ type Config = {
   // RETIRED (residence compat): the old private-overlay toggle — ignored with the same loud notice;
   // its data-untrack semantics are long gone. See `spex guide footprint` MIGRATIONS.
   private?: boolean
-  // which harness targets `spex materialize` delivers into — native ids ('claude'|'codex') or a {plugin:"<folder>"}
-  // bundle; resolved + validated by [[harness-select]] (harness-select.ts). Default (omitted): all native harnesses.
+  // which harness targets `spex materialize` delivers into — a native HarnessId or a {plugin:"<folder>"}
+  // bundle; resolved + validated by [[harness-select]] (harness-select.ts). REQUIRED — no default set; `spex init --harness` stamps it.
   harnesses?: (string | { plugin?: string })[]
   dashboard?: {
     apiUrl?: string                // the per-project backend the board proxies to (read frontend-side; see api-endpoint)
     title?: string                 // override for the browser-tab name (default: the repo-root basename; see tab-title)
-    icon?: string                  // the browser-tab favicon: an emoji ("🔭") or an Iconify name ("mdi:rocket-launch"); see tab-icon
+    icon?: string                  // project identity icon: a picker preset id; existing emoji/Iconify/URL values remain supported ([[identity-config]])
   }
   sessions?: {
     maxActive?: number             // concurrency cap: max agents AUTONOMOUSLY PROGRESSING at once (default 8; see sessions.ts maxActive)
@@ -34,7 +34,7 @@ type Config = {
     // its harness AND its exact launch command; the chosen NAME is persisted on the record so resume reuses the
     // same auth. `harness` defaults to 'claude'. Host-specific `cmd`s (abs wrapper paths) belong in the
     // gitignored spexcode.local.json — the name is portable, the cmd is a machine fact.
-    launchers?: { [name: string]: { harness?: 'claude' | 'codex'; cmd: string } }
+    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
   }
   serve?: {

package/spec-cli/src/lint.ts

@@ -1,145 +1,92 @@
-import { readdirSync, readFileSync, existsSync } from 'node:fs'
+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 { readJsonConfig } from './layout.js'
 import { extractors, extractorFor, extOf, resolveAnchor, windowCommits, 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 }
 
 export type LintConfig = {
-  governedRoots: string[]       // dirs whose source files must each be governed by a spec (coverage). '.' = whole project (safe: only git-TRACKED files, so node_modules/build/nested worktrees never count).
-  sourceExtensions: string[]    // extensions coverage treats as source files
-  testGlobs: string[]           // globs EXCLUDED from coverage — tests aren't governed product (default ['**/*.test.*']; set [] to govern tests too)
-  identifierExtensions: string[]// extensions the altitude bare-filename signal recognises (see IDENT below)
-  altitude: { lineBudget: number; charBudget: number; sizeable: number; dense: number; steps: number }
-  maxChildren: number        // breadth budget: warn at >= this many direct children
+  governedRoots: string[]       // dirs whose tracked source files must each be governed by a spec. '.' = whole project.
+  sourceIncludeGlobs: string[] | null // null includes every tracked regular text file; [] intentionally includes none
+  sourceExcludeGlobs: string[]  // explicit source-policy subtraction
+  sourceExtensions: string[] | null // compatibility shorthand compiled into sourceIncludeGlobs
+  testGlobs: string[]           // globs EXCLUDED from coverage; set [] to govern tests too
   maxOwners: number          // warn when a file is governed (code:) by > this many nodes
   scenarioTags: string[]     // the closed vocabulary an eval scenario's `tags:` must draw from; extend it to mint a new tag
+  scopedCodeMiss: 'warn' | 'ignore' // the file-level drift ADVISORY on a selector-scoped code: file whose window has no
+                             // selector hit ([[code-anchor]]). 'warn' (default) keeps today's drift warning; 'ignore'
+                             // silences ONLY that advisory — hit blocks, bare code drift, integrity, acks, related
+                             // semantics, and eval freshness are all untouched by this knob.
 }
 const DEFAULT_CONFIG: LintConfig = {
   governedRoots: ['spec-dashboard/src', 'spec-cli/src'],
-  sourceExtensions: ['ts', 'tsx', 'js', 'jsx'],
-  testGlobs: ['**/*.test.*'],
-  identifierExtensions: ['ts', 'tsx', 'js', 'jsx', 'json', 'md'],
-  altitude: { lineBudget: 50, charBudget: 4200, sizeable: 35, dense: 1.3, steps: 3 },
-  maxChildren: 8,
+  sourceIncludeGlobs: null,
+  sourceExcludeGlobs: [],
+  sourceExtensions: null,
+  testGlobs: DEFAULT_TEST_GLOBS,
   maxOwners: 3,
   scenarioTags: ['frontend-e2e', 'backend-api', 'cli', 'desktop', 'mobile'],
+  scopedCodeMiss: 'warn',
 }
 export function loadConfig(root: string): 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 ?? {}
-  const merged = { ...DEFAULT_CONFIG, ...c, altitude: { ...DEFAULT_CONFIG.altitude, ...(c.altitude ?? {}) } }
+  const merged = { ...DEFAULT_CONFIG, ...c }
   return normalizeConfig(merged)
 }
 
-// canonicalize two adopter-input footguns that would otherwise SILENTLY match ZERO files (the same failure
-// class as an unset governedRoots — a green board that governs nothing). Both are natural mistakes a non-web
-// adopter makes reading the prose, so we accept-what-they-meant rather than reject:
-//  - a LEADING DOT on an extension: the matcher is `\.(ext)$`, so a literal ".ts" becomes `\..ts$` and never
-//    matches. Strip leading dots → ["ts"] and [".ts"] both work (prose historically showed ".ts").
-//  - a testGlob with NO "/": globs anchor to the full repo-relative path, so a bare "*.test.ts" matches only
-//    ROOT-level files and leaks every nested test into coverage. A slash-less glob is a basename intent →
-//    prepend "**/" so it matches that basename at any depth (the default "**/*.test.*" already does).
+// Compile every author-facing source selector into one include-minus-exclude/test policy. In particular,
+// sourceExtensions is compatibility syntax only: it contributes include globs and never reaches discovery.
 export function normalizeConfig(cfg: LintConfig): LintConfig {
+  // a mistyped enum silently reverting to the default would green-wash (or over-warn) exactly the
+  // advisory the author meant to tune — same fail-loud rule as a malformed spexcode.json.
+  if (cfg.scopedCodeMiss !== 'warn' && cfg.scopedCodeMiss !== 'ignore')
+    throw new Error(`spexcode.json lint.scopedCodeMiss must be "warn" or "ignore", got ${JSON.stringify(cfg.scopedCodeMiss)}`)
   const dedot = (xs: string[]) => xs.map((x) => x.replace(/^\.+/, ''))
+  const anyDepth = (xs: string[]) => xs.map((g) => (g.includes('/') ? g : `**/${g}`))
+  const extensions = cfg.sourceExtensions === null ? null : dedot(cfg.sourceExtensions)
+  const includes = cfg.sourceIncludeGlobs === null && extensions === null
+    ? null
+    : [...new Set([...anyDepth(cfg.sourceIncludeGlobs ?? []), ...(extensions ?? []).map((ext) => `**/*.${ext}`)])]
   return {
     ...cfg,
-    sourceExtensions: dedot(cfg.sourceExtensions),
-    identifierExtensions: dedot(cfg.identifierExtensions),
-    testGlobs: cfg.testGlobs.map((g) => (g.includes('/') ? g : `**/${g}`)),
+    sourceIncludeGlobs: includes,
+    sourceExcludeGlobs: anyDepth(cfg.sourceExcludeGlobs),
+    sourceExtensions: extensions,
+    testGlobs: anyDepth(cfg.testGlobs),
   }
 }
 
-// the source-file matcher, built from the configurable `sourceExtensions` knob. Coverage uses it to decide
-// which tracked files must be governed; eval lint's `eval-coverage` reuses THE SAME knob so ONE setting
-// defines "source" for both coverage axes — a non-web project (Rust/Go/Python .rs/.go/.py) sets it once and
-// both the coverage warning and the loss-signal blind-spot check follow, with no second web-only allowlist.
-export const sourceExtRe = (extensions: string[]) => new RegExp(`\\.(${extensions.join('|')})$`)
-
-// a minimal glob → RegExp anchored to the full repo-relative path: `**` = any dirs, `*` = within a segment.
-function globToRe(glob: string): RegExp {
-  const body = glob.split(/(\*\*\/|\*\*|\*|\?)/).map((seg) => {
-    if (seg === '**/') return '(?:.*/)?'
-    if (seg === '**') return '.*'
-    if (seg === '*') return '[^/]*'
-    if (seg === '?') return '[^/]'
-    return seg.replace(/[.+^${}()|[\]\\]/g, '\\$&')
-  }).join('')
-  return new RegExp(`^${body}$`)
-}
-
-// coverage enumerates source via GIT-TRACKED files (`git ls-files`, through git() which strips the hook's
-// GIT_DIR), NOT a raw fs walk. Tracked-only auto-excludes node_modules + build output (gitignored), nested
-// or linked worktrees + submodules (a separate index), `.git`, and anything untracked — so governedRoots
-// '.' means "all tracked source" with no fs explosion and no hand-maintained skip list (git IS the database).
-// Test files drop per cfg.testGlobs (default *.test.*; set [] to govern tests too).
-function trackedSourceFiles(root: string, roots: string[], src: RegExp, testGlobs: string[]): string[] {
-  const testRes = testGlobs.map(globToRe)
-  const out = new Set<string>()
-  for (const r of roots) {
-    let listed = ''
-    try { listed = git(['-C', root, 'ls-files', '-z', '--', r]) } catch { continue }
-    for (const f of listed.split('\0')) {
-      if (!f || !src.test(f) || testRes.some((re) => re.test(f))) continue
-      out.add(f)
-    }
-  }
-  return [...out]
-}
-
-// code-identifier signals: camelCase | snake_case | foo( | `backticked` | /a/path.ext | bare file.ext. Only
-// the bare-filename branch needs the extension allowlist (config, so a non-TS project recognises its own
-// sources) — without it a bare `word.word` would match ordinary prose like "e.g".
-function identRe(extensions: string[]): RegExp {
-  const ext = extensions.join('|')
-  return new RegExp(`[a-z][A-Za-z0-9]*[A-Z][A-Za-z0-9]*|\\b[a-z]+_[a-z0-9_]+\\b|\\b\\w+\\(|\`[^\`]+\`|\\/[\\w./-]+\\.\\w+|\\b[\\w-]+\\.(${ext})\\b`, 'g')
-}
-// step-by-step how-to phrasing: numbered steps, or sequencing connectives that walk through mechanics.
-const STEP_LINE = /^\s*(\d+[.)]\s|[-*]\s*(first|then|next|finally)\b)|(^|[,;]\s*)(first|then|next|finally),/i
-// returns a one-line reason naming whichever low-altitude proxy(ies) tripped (length / identifier density /
-// step-by-step), or null when the body is at altitude.
-function altitude(body: string, cfg: LintConfig, ident: RegExp): string | null {
-  const a = cfg.altitude
-  const lines = body.split('\n')
-  const nb = lines.filter((l) => l.trim()).length
-  const chars = body.length
-  // identifiers and step phrasing are read from PROSE only — a fenced code sample is acknowledged code,
-  // not low-altitude narration, so it inflates length but not density.
-  let inFence = false, signals = 0, steps = 0
-  for (const l of lines) {
-    if (/^\s*```/.test(l)) { inFence = !inFence; continue }
-    if (inFence || !l.trim()) continue
-    signals += l.match(ident)?.length ?? 0
-    if (STEP_LINE.test(l)) steps++
-  }
-  const density = signals / Math.max(1, nb)
-  const why: string[] = []
-  if (nb > a.lineBudget || chars > a.charBudget) why.push(`${nb} non-blank lines / ${chars} chars over budget (${a.lineBudget}/${a.charBudget})`)
-  if (nb > a.sizeable && density > a.dense) why.push(`code-identifier density ${density.toFixed(2)}/line over ${a.dense}`)
-  if (nb > a.sizeable && steps >= a.steps) why.push(`${steps} step-by-step how-to lines`)
-  return why.length ? why.join('; ') : null
-}
-
 export async function specLint(): Promise<Finding[]> {
   const root = repoRoot()
   const cfg = loadConfig(root)
-  const ident = identRe(cfg.identifierExtensions)
-  const srcRe = sourceExtRe(cfg.sourceExtensions)
+  const governed = trackedSourceFiles(root, cfg.governedRoots, cfg)
   const specs = await loadSpecs()
   const out: Finding[] = []
 
-  // integrity + build the file -> owners map.
+  // integrity + build the file -> owners map. A relation's STRUCTURAL problems (a duplicate entry,
+  // bare/scoped mixing on one base path, a selector on a glob — all from parseRelation,
+  // [[code-anchor]]) are integrity errors: malformed edges block like broken ones.
   const owners = new Map<string, string[]>()
+  const claimed = 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)))
         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])
+      claimed.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])
     }
-    // one-govern: a node is source of truth for at most ONE file, so drift/eval/ack have a single
+    // one-govern: a node is source of truth for at most ONE file — DISTINCT base paths; several
+    // `path#symbol` selectors on the same file are one subject — so drift/eval/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)
@@ -148,7 +95,6 @@ export async function specLint(): Promise<Finding[]> {
   // 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
   // related, not govern (see [[governed-related]]). It carries coverage but never drift, never eval freshness.
-  const claimed = new Set<string>(owners.keys())
   for (const s of specs) for (const f of s.related) {
     if (!existsSync(join(root, f)))
       out.push({ level: 'error', rule: 'integrity', spec: s.id, file: f, msg: `spec '${s.id}' lists a missing related file: ${f}` })
@@ -234,33 +180,9 @@ export async function specLint(): Promise<Finding[]> {
     }
   }
 
-  // altitude: a body that re-narrates mechanics instead of stating contract/intent (WARN — soft budget).
-  for (const s of specs) {
-    const why = altitude(s.body, cfg, ident)
-    if (why) out.push({ level: 'warn', rule: 'altitude', spec: s.id, msg: `'${s.id}' body reads low-altitude (mechanics, not contract): ${why}` })
-  }
-
-  // breadth: a node with too many DIRECT children is altitude's structural twin — splitting a node to pass
-  // altitude shouldn't just relocate the sprawl into a wide flat fan-out (WARN — soft, advisory). Children
-  // are derived from the parent links loadSpecs already computes; no explicit child array to keep in sync.
-  const childCount = new Map<string, number>()
-  for (const s of specs) if (s.parent) childCount.set(s.parent, (childCount.get(s.parent) ?? 0) + 1)
-  for (const s of specs) {
-    const n = childCount.get(s.id) ?? 0
-    if (n >= cfg.maxChildren)
-      out.push({ level: 'warn', rule: 'breadth', spec: s.id, msg: `'${s.id}' has ${n} direct child nodes (>= ${cfg.maxChildren}) — is an intermediate grouping layer missing? (a flat list of genuine peers is sometimes right — ignore if so)` })
-  }
-
   // coverage: every governed source file must be claimed by at least one spec.
-  const governed = trackedSourceFiles(root, cfg.governedRoots, srcRe, cfg.testGlobs)
-  // no governed source found at all → make it a SELF-EXPLANATORY repair entrypoint, not a dead end. The two
-  // knobs governing this are BOTH web-tuned by default (extensions ts/tsx/js/jsx; roots this repo's own dirs),
-  // so a non-web adopter (Rust/Go/Python) hits zero source two ways: right dir but wrong extension, or an
-  // unset root. Naming BOTH knobs, echoing their CURRENT values (so the mismatch is visible — "searching .ts
-  // in a .py tree"), and stating the `lint`-key nesting (a top-level key silently no-ops) turns the warning
-  // into the fix. Concrete non-web extension examples so the repair is copy-pasteable, not a schema hunt.
   if (governed.length === 0)
-    out.push({ level: 'warn', rule: 'coverage', msg: `governing NOTHING — 0 source files matched extensions [${cfg.sourceExtensions.join(', ')}] under governedRoots [${cfg.governedRoots.join(', ')}]. Both knobs live under the "lint" key in spexcode.json (a top-level key is ignored): set governedRoots to your source dir(s) (e.g. ["src"]) AND sourceExtensions to your language (e.g. ["rs"] / ["go"] / ["py"]).` })
+    out.push({ level: 'warn', rule: 'coverage', msg: `governing NOTHING — 0 source candidates under governedRoots [${cfg.governedRoots.join(', ')}]; ${sourcePolicyDescription(cfg)}. Repair these knobs under the "lint" key in spexcode.json (top-level keys are ignored): governedRoots, sourceIncludeGlobs, sourceExcludeGlobs, testGlobs; sourceExtensions remains compatibility shorthand for include globs.` })
   for (const f of governed)
     if (!claimed.has(f)) out.push({ level: 'warn', rule: 'coverage', file: f, msg: `no spec governs: ${f}` })
 
@@ -276,55 +198,73 @@ export async function specLint(): Promise<Finding[]> {
     out.push({ level: 'warn', rule: 'owners', msg: `${over.length} file(s) are governed by > ${cfg.maxOwners} nodes — each holds more separately-specified functionality than one file should. Worst: ${top}. SPLIT the file so each governor owns its own module (or merge the nodes, or give it a single foundation owner + related:).` })
   }
 
-  // code anchors ([[code-anchor]]): a code: entry may pin one named unit (`path#symbol`). 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 intersect the unit's line range — extracted from the file AS
-  // OF that commit, by the extension's ONE designated extractor — is an anchor-drift ERROR unless a
-  // Spec-OK ack covers it. Resolution failures are never silent: a dead or ambiguous anchor, 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.
+  // 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
+  // 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)])
   const readyWarned = new Set<string>()
   for (const s of specs) {
-    for (const { path, anchor } of s.anchors) {
-      const x = extractorFor(regs, extOf(path))
-      if (!x) {
-        out.push({ level: 'error', rule: 'integrity', spec: s.id, file: path, msg: `'${s.id}' anchors ${path}#${anchor}, 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 #${anchor}` })
-        continue
-      }
-      const ready = x.ready()
-      if (ready !== true) {
-        // once per (extractor, reason), even across several anchored nodes — one repair, one message.
-        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
-      let units
-      try { units = x.extract(readFileSync(join(root, path), 'utf8'), path) } catch (e: any) {
-        out.push({ level: 'error', rule: 'integrity', spec: s.id, file: path, msg: `anchor ${path}#${anchor} ('${s.id}') is unverifiable — the current file does not parse: ${e?.message ?? e}` })
-        continue
-      }
-      const res = resolveAnchor(units, anchor)
-      if ('dead' in res) {
-        out.push({ level: 'error', rule: 'integrity', spec: s.id, file: path, msg: `dead anchor: ${path}#${anchor} ('${s.id}') names no unit on the current tree — the unit was deleted or renamed; update the spec's code: entry to follow it` })
-        continue
-      }
-      if ('ambiguous' in res) {
-        out.push({ level: 'error', rule: 'integrity', spec: s.id, file: path, msg: `ambiguous anchor: ${path}#${anchor} ('${s.id}') names ${res.ambiguous} same-named units in one file — an anchor must be unique; rename one unit` })
-        continue
-      }
-      if (res.ok.typeOnly)
-        out.push({ level: 'warn', rule: 'anchor', spec: s.id, file: path, msg: `${path}#${anchor} anchors a ${res.ok.kind} — anchoring a type is usually wrong (types reshape with every refactor); anchor the behaviour-bearing unit instead` })
-      const since = rowsFor(hidx, s.path)[0]?.hash || ''
-      const win = windowCommits(didx, since, path)
-      if (!win.length) continue
-      const hits = await anchorHitCommits(root, win, path, anchor, x)
-      const unparseable = hits.filter((h) => h.unparseable)
-      if (hits.length) {
+    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) {
+        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)` })
+          continue
+        }
+        const ready = x.ready()
+        if (ready !== true) {
+          // once per (extractor, reason), even across several anchored nodes — one repair, one message.
+          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()) {
+          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) {
+          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
+        }
+        // each selector resolves (or errors) on its own; only the live ones feed the window engine.
+        const live: string[] = []
+        for (const sym of selectors) {
+          const res = resolveAnchor(units, sym)
+          if ('dead' in res) {
+            out.push({ level: 'error', rule: 'integrity', spec: s.id, file: path, msg: `dead anchor: ${path}#${sym} ('${s.id}') names no unit on the current tree — the unit was deleted or renamed; update the spec's ${relation}: entry to follow it` })
+            continue
+          }
+          if ('ambiguous' in res) {
+            out.push({ level: 'error', rule: 'integrity', spec: s.id, file: path, msg: `ambiguous anchor: ${path}#${sym} ('${s.id}') names ${res.ambiguous} same-named units in one file — an anchor must be unique; rename one unit` })
+            continue
+          }
+          if (res.ok.typeOnly)
+            out.push({ level: 'warn', rule: 'anchor', spec: s.id, file: path, msg: `${path}#${sym} anchors a ${res.ok.kind} — anchoring a type is usually wrong (types reshape with every refactor); anchor the behaviour-bearing unit instead` })
+          live.push(sym)
+        }
+        if (!live.length) continue
+        const since = rowsFor(hidx, s.path)[0]?.hash || ''
+        const win = windowCommits(didx, since, path)
+        if (!win.length) continue
+        const hits = await anchorHitCommits(root, win, path, live, x)
+        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)` : ''
-        out.push({ level: 'error', rule: 'anchor-drift', spec: s.id, file: path, msg: `${path}#${anchor} 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` })
+        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
+          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)` })
       }
     }
   }
@@ -334,9 +274,15 @@ export async function specLint(): Promise<Finding[]> {
   // commit to the file counts iff it is NOT reachable from the spec's latest version (in-memory
   // parent-edge reachability, the equivalent of `rev-list <version>..HEAD -- <file>`), never a
   // log-position or timestamp guess.
+  // A selector-SCOPED code file keeps this file-level advisory by default (a miss still nudges); the
+  // committed `lint.scopedCodeMiss: "ignore"` silences ONLY this advisory for scoped entries — the
+  // anchor engine's verdicts above (hit = block, resolution failures = integrity) are untouched.
   for (const s of specs) {
-    for (const d of s.driftFiles)
+    const scopedPaths = new Set(s.codeScoped.map((e) => e.path))
+    for (const d of s.driftFiles) {
+      if (cfg.scopedCodeMiss === 'ignore' && scopedPaths.has(d.file)) continue
       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

package/spec-cli/src/login-page.ts

@@ -1,8 +1,15 @@
 // @@@ login page - the gateway's gate is a DESIGNED page, not the browser's Basic-auth dialog (which can't
 // be styled and feels like a 1998 intranet). Self-contained: inline CSS + SVG, zero external assets, so it
 // renders before anything is authorised. Dark, calm, a single password field; an error state when the
-// password is wrong. The form POSTs to /login (same-origin), which mints the auth cookie and redirects.
-export function loginPage(error = false): string {
+// password is wrong. The form POSTs to `action` (same-origin), which mints the auth cookie and redirects.
+// One page serves every gate: the single-project gateway's /login (the defaults) and the multi-project
+// hub's admin + per-project logins ([[gateway-hub]] passes action/heading/sub). Every option is
+// HTML-escaped at this sink — projectIds are path-derived, attacker-influencable strings.
+export function loginPage(error = false, opts: { action?: string; heading?: string; sub?: string } = {}): string {
+  const esc = (s: string) => s.replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c]!))
+  const action = esc(opts.action ?? '/login')
+  const heading = esc(opts.heading ?? 'Restricted access')
+  const sub = esc(opts.sub ?? 'This is a private agent workspace. Enter the access password to continue.')
   return `<!doctype html>
 <html lang="en">
 <head>
@@ -58,7 +65,7 @@ export function loginPage(error = false): string {
 </style>
 </head>
 <body>
-  <form class="card" method="POST" action="/login" autocomplete="off">
+  <form class="card" method="POST" action="${action}" autocomplete="off">
     <div class="mark">
       <svg viewBox="0 0 32 32" fill="none" xmlns="http://www.w3.org/2000/svg">
         <rect x="2" y="2" width="28" height="28" rx="8" fill="#0e1626" stroke="#3f6fe0" stroke-opacity="0.5"/>
@@ -66,8 +73,8 @@ export function loginPage(error = false): string {
       </svg>
       <b>Spex<span>Code</span></b>
     </div>
-    <h1>Restricted access</h1>
-    <p class="sub">This is a private agent workspace. Enter the access password to continue.</p>
+    <h1>${heading}</h1>
+    <p class="sub">${sub}</p>
     ${error ? '<div class="err">Incorrect password — try again.</div>' : ''}
     <label for="password">Password</label>
     <input id="password" name="password" type="password" autofocus required placeholder="••••••••••">