spexcode 0.4.0 → 0.4.3

package/README.md

@@ -80,17 +80,34 @@ the spec and the evals; the diff gets read once, at merge time.
 Requires Node ≥ 22 and git. This part is plain tooling — no AI involved yet.
 
 ```sh
-npm i -g spexcode        # installs the `spex` command
+npm i -g spexcode                              # installs the `spex` command
 cd your-repo
-spex init                # seeds .spec/, installs git hooks, materializes the agent contract
-spex serve               # API backend on :8787
-spex serve ui            # dashboard on :5173, proxying to the backend
+spex init --harness claude,codex,opencode,pi   # seeds .spec/, installs hooks, materializes the agent contracts
 ```
 
-`spex init` is additive. It works on any existing git repo and never overwrites your files: it
-creates a root `.spec/project/spec.md` and a starter `spexcode.json`, installs the git hooks, and
-writes a managed block into `CLAUDE.md`/`AGENTS.md` so any agent working in the repo
-discovers the workflow on its own.
+That's the whole adoption. The example lists all the built-in harnesses — remove the ones you don't
+use: `--harness` is required, has no default, and takes any one id or comma-separated subset.
+`spex init` is additive: it works on any existing git repo and never
+overwrites your files — it creates a root `.spec/project/spec.md` and a starter `spexcode.json`,
+installs the git hooks, and writes the selected harness's managed contract, so any agent working in
+the repo discovers the workflow on its own.
+
+When you want the live board — the graph, sessions, evals — start the runtime:
+
+```sh
+spex serve       # this project's backend — prints its URL, registers itself for your user
+spex dashboard   # once per user, any directory: the one dashboard — open the URL it prints
+```
+
+Run `spex serve` from each project you want online. Every backend registers itself, and the single
+`spex dashboard` finds them all — backends already running and ones you start later, in any order.
+`/projects` switches and manages projects; each project's board lives under `/p/:id/`. There is no
+per-project dashboard process and no port pairing to remember: if a port is taken, give that
+backend its own with `spex serve --port <n>`, and trust the URL each command prints.
+
+Those are installed-user commands. Contributors working from this source checkout use `npm run api`
+for the reloadable backend and `npm run web` for the Vite/HMR frontend; see
+[Contributing](#contributing).
 
 Then grow the tree:
 
@@ -115,11 +132,11 @@ This part needs tmux and a logged-in [Claude Code](https://www.anthropic.com/cla
 on the machine.
 
 ```sh
-spex session new "make the settings page remember the last tab" --node settings
+spex session new "[[settings]] make the settings page remember the last tab"
 ```
 
-launches a worker session in its own worktree on branch `node/settings-…`. The `--node` flag (or a
-`[[settings]]` mention in the prompt, same effect) sets the branch name and board attribution; the
+launches a worker session in its own worktree on branch `node/settings-…`. The prompt's first
+`[[settings]]` mention sets the branch name and board attribution; the
 worker still finds and reads the governing spec itself before touching code. It makes the change,
 rewrites the spec body to match, commits
 both (a hook stamps the `Session:` trailer), then proposes a merge and stops. Workers never merge
@@ -186,21 +203,24 @@ and recorded video evidence in the middle.*
 
 - **integrity** (error): a `code:` or `related:` path that doesn't exist
 - **living** (error): a changelog heading in a spec body
-- **altitude** (warn): a body that slid from contract prose into an implementation dump. The usual
-  smell is a numbered step list or a wall of function names; this rule is why spec bodies stay
-  short enough to actually read
 - **coverage** (warn): unclaimed source files
 - **drift** (warn): governed code changed after its spec's last version, derived live from git
 
-plus naming and ownership rules (`one-govern`, `id-format`, `mention` as errors; `breadth`,
+plus naming and ownership rules (`one-govern`, `id-format`, `mention` as errors;
 `related-drift`, `owners`, `confusable-id` as warns) — `spex guide spec` lists them all.
 
+`spex doctor` is the opt-in, read-only health diagnosis. Its altitude and breadth checks report bodies that
+look like implementation dumps and nodes with wide child fan-out, with per-node evidence and repair, without
+putting heuristic judgment in the lint or commit gate.
+
 ## Configuration
 
-`spexcode.json` (committed, portable: layout, lint budgets, dashboard identity, launcher names) and
+`spexcode.json` (committed, portable: layout, lint policy, doctor health budgets, project dashboard identity, launcher names) and
 `spexcode.local.json` (gitignored, host-specific: absolute launcher paths, cert paths) cover every
 setting. There is no imperative settings verb: you edit the two files by hand (or ask your agent
-to), and `spex guide settings` documents every field. The other
+to), and `spex guide settings` documents every field. The Projects admin UI writes a project's icon back
+to that same `dashboard.icon` field; the global gateway icon is the one separate host fact at
+`$SPEXCODE_HOME/config.json` `gateway.icon`, never copied into a repo. The other
 manuals are `spex guide` (the workflow), `spex guide spec`, `spex guide eval`, and
 `spex guide footprint`; `spex help` maps the commands.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spexcode",
-  "version": "0.4.0",
+  "version": "0.4.3",
   "type": "module",
   "description": "SpexCode — a spec-driven, self-developing dev tool. The `spex` CLI + spec server reads the .spec tree and its git history, and serves the dashboard.",
   "license": "MIT",
@@ -18,6 +18,9 @@
     "spec-forge/src",
     "!spec-forge/src/**/*.test.ts",
     "spec-dashboard/dist",
+    "spec-dashboard/src/reviewFilters.js",
+    "spec-dashboard/src/reviewQuery.js",
+    "spec-dashboard/src/session.js",
     "README.md"
   ],
   "engines": {
@@ -26,16 +29,17 @@
   "scripts": {
     "api": "cd spec-cli && npm run serve",
     "web": "cd spec-dashboard && npm run dev",
-    "lint": "cd spec-cli && npm run -s lint",
+    "lint": "node scripts/sync-init-plugins.mjs --check && cd spec-cli && npm run -s lint",
+    "sync:init-plugins": "node scripts/sync-init-plugins.mjs --write",
+    "test:init-plugins": "node --test scripts/sync-init-plugins.test.mjs",
     "hooks": "bash scripts/install-hooks.sh",
-    "prepack": "node scripts/prepack.mjs",
-    "postinstall": "node -e \"try{require('fs').readdirSync('node_modules/node-pty/prebuilds').forEach(d=>{try{require('fs').chmodSync('node_modules/node-pty/prebuilds/'+d+'/spawn-helper',0o755)}catch{}})}catch{}\""
+    "prepack": "node scripts/sync-init-plugins.mjs --check && node scripts/prepack.mjs"
   },
   "dependencies": {
     "@hono/node-server": "^1.13.7",
     "@hono/node-ws": "^1.0.4",
     "hono": "^4.6.14",
-    "node-pty": "^1.0.0",
+    "node-pty": "^1.1.0",
     "tsx": "^4.19.2"
   },
   "devDependencies": {

package/spec-cli/README.md

@@ -29,31 +29,38 @@ Adopt it in your project — `spex init` is **additive**, it never restructures
 
 ```sh
 cd ~/my-app
-spex init              # seed .spec/, a starter spexcode.json, and git hooks — nothing destructive
+spex init --harness claude  # seed .spec/, starter config, hooks, and the agent contract
 # 1. edit .spec/project/spec.md to describe your project
 # 2. point spexcode.json's  lint.governedRoots  at your real source dir(s)
-spex lint              # the "coverage" warnings are your adoption TODO list
+spex spec lint         # the "coverage" warnings are your adoption TODO list
 ```
 
-Run it. The backend and the dashboard are **two commands on two ports**, so several projects can run
-side by side on one host (the cwd picks which project is served):
+Run one backend from every project you want online. Each successful `spex serve` publishes its
+endpoint to the current user's host registry; additional projects only need a free backend port:
 
 ```sh
-spex serve --port 8788                       # the backend (API + sessions) for THIS repo
-spex dashboard --port 5174 --api-port 8788   # the board UI, pointed at that backend
+spex serve              # this project's backend (API + sessions), default :8787
+# In another project: spex serve --port 8788
 ```
 
-Then open <http://localhost:5174>. With no flags, `spex serve` defaults to `:8787` and `spex dashboard`
-to `:5173`.
+In another shell, start the host gateway/UI once for the current user:
+
+```sh
+spex dashboard          # shared dashboard, default :5173
+```
+
+Open <http://localhost:5173/projects>. The gateway automatically discovers backends already running
+and those started later. `/projects` is the global project switcher and management surface; project
+dashboards live under `/p/:id/`. There is no per-project UI process or API/UI port pairing.
 
 Day to day:
 
 | command | what it does |
 | --- | --- |
-| `spex lint` | check the spec↔code graph — coverage, drift, and the living-body rules |
-| `spex watch` | stream session / board transitions as they happen |
-| `spex guide` | print the full workflow, plus the `spec.md` / `yatsu.md` file-format manuals |
-| `spex board` | dump the current board state as JSON |
+| `spex spec lint` | check the spec↔code graph — coverage, drift, and the living-body rules |
+| `spex session watch` | stream session transitions as they happen |
+| `spex guide` | print the setup workflow; topics cover the `spec.md` and `eval.md` formats |
+| `spex graph --json` | dump the current assembled view as JSON |
 
 The spec tree is ground truth and git is its database: every change is a `spec.md` node, **rewritten in
 place** (never a `## vN` changelog) and versioned by its commits.
@@ -72,14 +79,16 @@ npm --prefix spec-dashboard install
 npm run hooks          # install the per-clone git hooks (main-guard + the session-stamp hook)
 ```
 
-The development loop runs from source, with hot-reload — this is what `npm run web` is for, as opposed
-to an installed user's `spex dashboard`:
+The development loop runs from source with hot reload:
 
 ```sh
 npm run api            # backend on :8787, hot-reloads on spec-cli/src changes
 npm run web            # the dashboard via Vite (HMR), proxying /api → :8787
 ```
 
+These are contributor-only source commands. Installed users run `spex serve` in each project and one
+`spex dashboard` for the host; they do not run the Vite development server.
+
 The contribution ritual in one breath: branch `node/<id>` off `main`, make the code change **and** its
 `spec.md` *together*, commit, then `spex session done --propose merge` — a human performs the `--no-ff`
 merge. That ritual, the spec-node model, the lint rules, and the reflexive config system are all spelled

package/spec-cli/hooks/dispatch.sh

@@ -16,12 +16,14 @@
 # session-worktree creation, and the pre-commit/post-checkout/post-merge hooks). .plugins edits are
 # git-transactional: they take effect at the commit/checkout/merge that carries them, like any other source.
 set -u
-# args: `<harness> <Event>`. A harness id as $1 (claude|codex|plugin) is consumed; otherwise we keep $1 as the
-# event and default the harness to claude — so a stale shim still written as `dispatch.sh <Event>` keeps working.
-# `plugin` is the bundle form ([[plugin-harness]]): it parses payloads as the claude family in harness.sh (z-code/
-# Claude share Claude's tool names + file_path), so it joins the claude branch there via the default case.
+# args: `<harness> <Event>`. A harness id as $1 (claude|codex|opencode|pi|plugin) is consumed; otherwise we keep
+# $1 as the event and default the harness to claude — so a stale shim still written as `dispatch.sh <Event>`
+# keeps working. `plugin` is the bundle form ([[plugin-harness]]), `opencode` the generated event-bus plugin
+# ([[opencode-harness]]), and `pi` the generated extension ([[pi-harness]]): all three SYNTHESIZE claude-shaped
+# payloads (Claude tool names + file_path), so they join the claude branch in harness.sh via the default case —
+# no parse arm of their own.
 harness=claude
-case "${1:-}" in claude|codex|plugin) harness="$1"; shift ;; esac
+case "${1:-}" in claude|codex|opencode|pi|plugin) harness="$1"; shift ;; esac
 event="${1:?usage: dispatch.sh <harness> <Event>}"
 export SPEXCODE_HARNESS="$harness"
 # the harness.sh path (the adapter's shell mirror) — sibling of this script; hook handlers source it, and we

package/spec-cli/hooks/harness.sh

@@ -1,14 +1,17 @@
 #!/usr/bin/env bash
 # @@@ harness.sh - the SHELL face of the [[harness-adapter]] (spec-cli/src/harness.ts). The hook scripts run
 # as pure shell, so they cannot import the TS adapter; this sourced library is its mirror. dispatch.sh sources
-# it and exports SPEXCODE_HARNESS (claude|codex) — baked into the shim by each adapter, so a hook learns its
+# it and exports SPEXCODE_HARNESS (claude|codex|opencode) — baked into the shim by each adapter, so a hook learns its
 # harness deterministically, never by sniffing the payload shape. EVERY harness-divergent payload-parse lives
 # HERE; the hook scripts stay harness-agnostic and just call hp_* (the one place Claude's tool names appear in
 # shell, plus codex's Bash-command mapping). The session-id + global-store resolution is harness-agnostic and
 # lives here too, so the six hooks no longer each repeat the git-common-dir → project-key dance.
-# SPEXCODE_HARNESS is claude|codex|plugin: `plugin` is the bundle form ([[plugin-harness]]) and its host (z-code/
-# Claude) shares Claude's payload shape, so every `case "$SPEXCODE_HARNESS"` below routes it through the claude
-# branch via the default case — there is no separate `plugin)` arm to maintain.
+# SPEXCODE_HARNESS is claude|codex|opencode|pi|plugin: `plugin` is the bundle form ([[plugin-harness]]) and its
+# host (z-code/Claude) shares Claude's payload shape; `opencode`'s generated plugin ([[opencode-harness]]) and
+# `pi`'s generated extension ([[pi-harness]]) SYNTHESIZE claude-shaped payloads by construction — so every
+# `case "$SPEXCODE_HARNESS"` below routes all three through the claude branch via the default case; only codex
+# keeps parse arms of its own.
+
 
 # the string value of a top-level JSON string field (first match). Harness-agnostic — both harnesses' payloads
 # carry session_id / tool_name as plain string fields. $1 = payload, $2 = field name. The value is scanned as a
@@ -182,8 +185,9 @@ hp_is_ask() {
 hp_ask_note() { hp_field "$1" question; }
 
 # the CODE file(s) a payload touches, mapped to the trigger the spec hooks key on. $2 = mode:
-#   access  → the file being READ or edited ([[spec-first]] fires on any code touch)
-#   mutate  → the file being EDITED      ([[spec-of-file]] fires only on a mutation)
+#   read    → the file being READ         ([[spec-first]] gates the first GOVERNED read)
+#   mutate  → the file being EDITED       ([[spec-of-file]] fires only on a mutation)
+#   access  → either operation
 # Echoes the path(s), ONE PER LINE — a codex multi-file apply_patch (several `*** Update File:` markers)
 # touches several files in one tool call, so every consuming hook iterates the lines. Echoes nothing when the
 # payload is not a code touch of that mode. The harness divergence:
@@ -196,13 +200,18 @@ hp_code_path() {
   tool=$(hp_tool "$payload")
   case "$SPEXCODE_HARNESS" in
     codex)
-      case "$tool" in apply_patch|Bash) ;; *) return 0 ;; esac
+      case "$mode:$tool" in
+        read:Bash|mutate:apply_patch|mutate:Bash|access:apply_patch|access:Bash) ;;
+        *) return 0 ;;
+      esac
       _hp_codex_cmd_path "$(hp_field "$payload" command)" "$mode"
       ;;
     *)
       case "$mode" in
+        read)   case "$tool" in Read) ;; *) return 0 ;; esac ;;
         mutate) case "$tool" in Edit|Write|NotebookEdit) ;; *) return 0 ;; esac ;;
-        *)      case "$tool" in Read|Edit|Write|NotebookEdit) ;; *) return 0 ;; esac ;;
+        access) case "$tool" in Read|Edit|Write|NotebookEdit) ;; *) return 0 ;; esac ;;
+        *) return 0 ;;
       esac
       local p; p=$(hp_field "$payload" file_path); [ -n "$p" ] || p=$(hp_field "$payload" notebook_path)
       printf '%s' "$p"
@@ -228,12 +237,14 @@ _hp_codex_cmd_path() {
   cmd=$(printf '%s' "$1" | awk '{gsub(/\\n/,"\n"); gsub(/\\t/,"\t")}1')
   case "$cmd" in
     *apply_patch*|*applypatch*|*'*** Add File:'*|*'*** Update File:'*|*'*** Delete File:'*)
+      [ "$mode" = read ] && return 0
       printf '%s\n' "$cmd" | sed -n 's/^\*\*\* \(Add\|Update\|Delete\) File: \(.*\)$/\2/p' | sed 's/[[:space:]]*$//'
       return 0 ;;
   esac
   local is_mutate=0
   case "$cmd" in *' >> '*|*' > '*|*' >>'*|*' >'*|*' tee '*|*'sed -i'*|*' dd '*) is_mutate=1 ;; esac
   [ "$mode" = mutate ] && [ "$is_mutate" = 0 ] && return 0
+  [ "$mode" = read ] && [ "$is_mutate" = 1 ] && return 0
   printf '%s\n' "$cmd" | tr ' \t' '\n\n' | grep -E '^[^-].*[/.][A-Za-z0-9_]+' | grep -vE '^(apply_patch|applypatch)$' | tail -1
 }
 

package/spec-cli/src/anchors.ts

@@ -7,8 +7,9 @@ import { gitA, type DriftIndex, ancestorsOf, inAncestors, ackCoverFor } from './
 // Everything below the entry parse splits into two layers:
 //   - the LANGUAGE SEAM: pure extractors (content, filename) -> Unit[] — no git, no cache, no fs.
 //     Each extension maps to exactly ONE designated extractor; there is NO cross-tier fallback.
-//   - the LANGUAGE-AGNOSTIC ENGINE: blob-oid memo, anchor resolution (dead/ambiguous), diff-hunk ∩
-//     unit-range intersection over the drift window. It never knows which language it is measuring.
+//   - the LANGUAGE-AGNOSTIC ENGINE: file-revision memo (keyed by Git object id), anchor resolution
+//     (dead/ambiguous), diff-hunk ∩ unit-range intersection over the drift window. It never knows
+//     which language it is measuring.
 
 export type Unit = { name: string; kind: string; start: number; end: number; typeOnly?: boolean }
 
@@ -27,8 +28,44 @@ export type Extractor = {
 export type CodeEntry = { path: string; anchor: string | null }
 export function parseCodeEntry(raw: string): CodeEntry {
   const i = raw.indexOf('#')
-  if (i < 0) return { path: raw, anchor: null }
-  return { path: raw.slice(0, i), anchor: raw.slice(i + 1).trim() || null }
+  if (i < 0) return { path: raw.trim(), anchor: null }
+  return { path: raw.slice(0, i).trim(), anchor: raw.slice(i + 1).trim() || null }
+}
+
+// ---- relation parsing: ONE structured path+selector grammar for code: AND related: ----
+// A relation's raw rows group per base path: a row is bare (`path`, whole-file — today's semantics,
+// unchanged) or scoped (`path#symbol`), and any number of scoped rows on the SAME base file fold into
+// one entry whose selectors are OR'd (a commit hitting any counts once; no selector-count cap — the
+// benchmark roster's 1–3 was an annotation rubric, never product syntax). STRUCTURAL verdicts live
+// here, pure and loud: an exact duplicate row, mixing bare with selectors on one base path, and a
+// selector on a glob are all `problems` the caller turns into integrity errors. Filesystem/git
+// verdicts (existence, directories, dead/ambiguous units, extractor readiness) stay the caller's —
+// this parser never touches fs.
+export type RelationEntry = { path: string; selectors: string[] }
+export type RelationParse = { entries: RelationEntry[]; problems: string[] }
+export function parseRelation(raws: string[], relation: 'code' | 'related'): RelationParse {
+  const order: string[] = []
+  const byPath = new Map<string, { bare: boolean; selectors: string[] }>()
+  const problems: string[] = []
+  for (const raw of raws) {
+    const { path, anchor } = parseCodeEntry(raw)
+    let e = byPath.get(path)
+    if (!e) { e = { bare: false, selectors: [] }; byPath.set(path, e); order.push(path) }
+    if (anchor === null) {
+      if (e.bare) problems.push(`${relation}: lists '${path}' twice — drop the duplicate entry`)
+      e.bare = true
+    } else if (e.selectors.includes(anchor)) {
+      problems.push(`${relation}: lists selector '${path}#${anchor}' twice — drop the duplicate`)
+    } else e.selectors.push(anchor)
+  }
+  for (const path of order) {
+    const e = byPath.get(path)!
+    if (e.bare && e.selectors.length)
+      problems.push(`${relation}: mixes bare '${path}' with '${path}#…' selectors — one base path is either whole-file or selector-scoped, never both; drop one form`)
+    if (e.selectors.length && path.includes('*'))
+      problems.push(`${relation}: '${path}#${e.selectors[0]}' puts a selector on a glob — a selector scopes ONE real file`)
+  }
+  return { entries: order.map((p) => ({ path: p, selectors: byPath.get(p)!.selectors })), problems }
 }
 
 // ---- extractor: ts-ast (the designated extractor for the JS family) ----
@@ -114,9 +151,20 @@ export type LangSpec = {
   id: string
   extensions: string[]
   // column-0 declaration patterns; capture group 1 = the unit name (or the declarator list when declList)
-  decls: { re: RegExp; kind: string; typeOnly?: boolean; classOpener?: boolean; declList?: boolean }[]
+  decls: {
+    re: RegExp
+    kind: string
+    typeOnly?: boolean
+    classOpener?: boolean
+    declList?: boolean
+    scopeOpener?: boolean
+    memberOf?: { parentKind: string; kind: string }
+  }[]
   // class-member pattern, active while inside a classOpener's balanced-bracket body (name -> Class.name)
   member?: { re: RegExp; blacklist?: RegExp }
+  // indentation-significant languages use declaration nesting for qualified names and ranges. The
+  // declaration regexes remain language data; this only selects a generic boundary strategy.
+  indentScopes?: { decorator?: RegExp }
   // a column-0 line matching this ENDS the previous unit (comment-aware so trailing comment blocks
   // attach to the NEXT unit, not the previous one)
   boundary: RegExp
@@ -136,12 +184,72 @@ function declNames(head: string): string[] {
   return segs.map((s) => s.match(/^\s*([A-Za-z_$][\w$]*)\s*(?::|=|$)/)?.[1]).filter((x): x is string => !!x)
 }
 
+const indentation = (line: string): number => {
+  let n = 0
+  for (const ch of line) {
+    if (ch === ' ') n++
+    else if (ch === '\t') n += 8 - (n % 8)
+    else break
+  }
+  return n
+}
+
+function extractIndentScoped(content: string, spec: LangSpec): Unit[] {
+  const lines = content.split('\n')
+  type ScopedUnit = Unit & { declaration: number; indent: number }
+  const units: ScopedUnit[] = []
+  const scopes: { indent: number; name: string; kind: string }[] = []
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i]
+    if (!line.trim() || /^\s*#/.test(line)) continue
+    const indent = indentation(line)
+    while (scopes.length && scopes[scopes.length - 1].indent >= indent) scopes.pop()
+    for (const d of spec.decls) {
+      const m = line.match(d.re)
+      if (!m) continue
+      const local = m[1]
+      const name = [...scopes.map((s) => s.name), local].join('.')
+      const parent = scopes[scopes.length - 1]
+      const kind = d.memberOf && parent?.kind === d.memberOf.parentKind ? d.memberOf.kind : d.kind
+      let start = i + 1
+      if (spec.indentScopes?.decorator) {
+        for (let j = i - 1; j >= 0; j--) {
+          if (indentation(lines[j]) !== indent || !spec.indentScopes.decorator.test(lines[j])) break
+          start = j + 1
+        }
+      }
+      units.push({ name, kind, start, end: i + 1, declaration: i, indent, ...(d.typeOnly ? { typeOnly: true } : {}) })
+      if (d.scopeOpener) scopes.push({ indent, name: local, kind: d.kind })
+      break
+    }
+  }
+
+  for (const unit of units) {
+    let boundary: number | null = null
+    for (let i = unit.declaration + 1; i < lines.length; i++) {
+      const line = lines[i]
+      if (!line.trim()) continue
+      const indent = indentation(line)
+      if (/^\s*#/.test(line)) {
+        if (indent <= unit.indent && boundary === null) boundary = i
+        continue
+      }
+      if (indent <= unit.indent) { boundary ??= i; break }
+      boundary = null
+    }
+    unit.end = Math.max(unit.start, (boundary ?? lines.length) )
+  }
+  return units.map(({ declaration: _declaration, indent: _indent, ...unit }) => unit)
+}
+
 export function heuristicExtractor(spec: LangSpec): Extractor {
   return {
     id: spec.id,
     claims: (ext) => spec.extensions.includes(ext),
     ready: () => true,
     extract(content) {
+      if (spec.indentScopes) return extractIndentScoped(content, spec)
       const lines = content.split('\n')
       const units: Unit[] = []
       let cls: string | null = null, depth = 0
@@ -200,12 +308,32 @@ export const JS_LANG_R5B: LangSpec = {
   boundary: /^(?:[A-Za-z_$]|\/\/|\/\*)/,
 }
 
+// Python is a LangSpec DATA row over the same generic engine: declaration names come from patterns;
+// significant indentation supplies lexical qualification and ranges. It is intentionally structural,
+// not a Python runtime or full grammar (the user-facing boundary is documented by [[code-anchor]]).
+const PY_ID = String.raw`[\p{ID_Start}_][\p{ID_Continue}_]*`
+export const PYTHON_LANG: LangSpec = {
+  id: 'heuristic-python',
+  extensions: ['py', 'pyi'],
+  decls: [
+    {
+      re: new RegExp(`^\\s*(?:async\\s+)?def\\s+(${PY_ID})\\s*\\(`, 'u'),
+      kind: 'function',
+      scopeOpener: true,
+      memberOf: { parentKind: 'class', kind: 'method' },
+    },
+    { re: new RegExp(`^\\s*class\\s+(${PY_ID})(?:\\s*\\(|\\s*:)`, 'u'), kind: 'class', scopeOpener: true },
+  ],
+  indentScopes: { decorator: /^\s*@/ },
+  boundary: /^\S/,
+}
+
 // ---- registry: extension -> its ONE designated extractor ----
 // The registry's shape is the Extractor INTERFACE, not any engine: a future language row may be a
 // heuristicExtractor(LangSpec) or a web-tree-sitter extractor carrying its own wasm-grammar/query
 // config — whatever the implementation needs rides inside its own factory, never in the registry.
 export function extractors(root: string): Extractor[] {
-  return [tsAstExtractor(root)]
+  return [tsAstExtractor(root), ...[PYTHON_LANG].map(heuristicExtractor)]
 }
 // first claiming extractor IS the designation (the registry order defines it); null = no anchor support
 // for this language yet (lint ERRORS — the remedy is a LangSpec data row, or dropping the anchor).
@@ -229,24 +357,24 @@ export function resolveAnchor(units: Unit[], symbol: string): AnchorResolution {
 
 // ---- the historical hit engine (language-agnostic; batch short-lived git, no resident process) ----
 
-// units of a file AS OF a commit, memoized by (blob oid, extractor id) — a blob is immutable, so the
-// memo never invalidates; distinct file versions in a window are few. 'absent' = no blob at that commit;
-// 'unparseable' = the extractor rejected that version's content (the caller treats it conservatively).
-type BlobUnits = { units: Unit[] } | { absent: true } | { unparseable: string }
-const unitMemo = new Map<string, BlobUnits>()
+// units of a file AS OF a commit, memoized by (Git object id, extractor id). File content identified by
+// an object id is immutable, so the memo never invalidates; distinct file revisions in a window are few.
+// 'absent' = no file at that commit; 'unparseable' = the extractor rejected that revision's content.
+type FileRevisionUnits = { units: Unit[] } | { absent: true } | { unparseable: string }
+const fileRevisionUnitMemo = new Map<string, FileRevisionUnits>()
 const MEMO_MAX = 4096
-async function unitsAt(root: string, commit: string, path: string, x: Extractor): Promise<BlobUnits> {
+async function unitsAtFileRevision(root: string, commit: string, path: string, x: Extractor): Promise<FileRevisionUnits> {
   const oid = (await gitA(['-C', root, 'rev-parse', `${commit}:${path}`])).trim()
   if (!oid) return { absent: true }
   const key = `${oid}\0${x.id}`
-  const hit = unitMemo.get(key)
+  const hit = fileRevisionUnitMemo.get(key)
   if (hit) return hit
-  const text = await gitA(['-C', root, 'cat-file', 'blob', oid])
-  let v: BlobUnits
-  try { v = { units: x.extract(text, path) } } catch (e: any) { v = { unparseable: e?.message ?? String(e) } }
-  if (unitMemo.size >= MEMO_MAX) unitMemo.clear()
-  unitMemo.set(key, v)
-  return v
+  const text = await gitA(['-C', root, 'cat-file', 'blob', oid]) // dead-words-ok: git plumbing — 'blob' is Git's object type, not product vocabulary
+  let result: FileRevisionUnits
+  try { result = { units: x.extract(text, path) } } catch (e: any) { result = { unparseable: e?.message ?? String(e) } }
+  if (fileRevisionUnitMemo.size >= MEMO_MAX) fileRevisionUnitMemo.clear()
+  fileRevisionUnitMemo.set(key, result)
+  return result
 }
 
 // post-image line ranges of one commit's diff to one file (`@@ -a,b +c,d @@`, --unified=0). d>0 → lines
@@ -280,21 +408,26 @@ export function windowCommits(idx: DriftIndex, sinceHash: string, path: string):
   return (idx.fileCommits.get(path) ?? []).filter((h) => !inAncestors(idx, base, h) && !cover.some((a) => inAncestors(idx, a, h)))
 }
 
-// which window commits TOUCHED the anchored unit: the commit's --unified=0 hunks intersect the unit's
-// line range extracted from the file AS IT EXISTED AT THAT COMMIT (never from HEAD — units later renamed
-// or moved still attribute correctly). A version whose content the extractor cannot parse is a
-// CONSERVATIVE hit (`unparseable` set) — over-warn, never silently skip.
-export type AnchorHit = { commit: string; unparseable?: string }
-export async function anchorHitCommits(root: string, win: string[], path: string, symbol: string, x: Extractor): Promise<AnchorHit[]> {
+// which window commits TOUCHED any of the anchored units: the commit's --unified=0 hunks intersect a
+// unit's line range extracted from the file AS IT EXISTED AT THAT COMMIT (never from HEAD — units later
+// renamed or moved still attribute correctly). Several selectors are OR — a commit appears ONCE, with
+// `selectors` naming exactly which units its hunks intersected (so diagnostics can attribute the hit).
+// A version whose content the extractor cannot parse is a CONSERVATIVE hit for every selector
+// (`unparseable` set) — over-warn, never silently skip.
+export type AnchorHit = { commit: string; selectors: string[]; unparseable?: string }
+export async function anchorHitCommits(root: string, win: string[], path: string, symbols: string[], x: Extractor): Promise<AnchorHit[]> {
   const hits: AnchorHit[] = []
   for (const c of win) {
-    const at = await unitsAt(root, c, path, x)
+    const at = await unitsAtFileRevision(root, c, path, x)
     if ('absent' in at) continue // file not in that commit's tree — nothing of the anchor to touch
-    if ('unparseable' in at) { hits.push({ commit: c, unparseable: at.unparseable }); continue }
-    const ranges = at.units.filter((u) => u.name === symbol)
-    if (!ranges.length) continue // unit didn't exist under this name at that commit
+    if ('unparseable' in at) { hits.push({ commit: c, selectors: [...symbols], unparseable: at.unparseable }); continue }
+    const bySym = symbols
+      .map((sym) => ({ sym, ranges: at.units.filter((u) => u.name === sym) }))
+      .filter((s) => s.ranges.length) // a unit absent under this name at that commit can't be touched
+    if (!bySym.length) continue
     const hunks = await hunksAt(root, c, path)
-    if (hunks.some(([a, b]) => ranges.some((u) => a <= u.end && u.start <= b))) hits.push({ commit: c })
+    const touched = bySym.filter((s) => hunks.some(([a, b]) => s.ranges.some((u) => a <= u.end && u.start <= b))).map((s) => s.sym)
+    if (touched.length) hits.push({ commit: c, selectors: touched })
   }
   return hits
 }