spexcode 0.2.8 → 0.3.0

package/README.md

@@ -9,6 +9,13 @@
   <a href="https://spexcode.net"><img alt="docs" src="https://img.shields.io/badge/docs-spexcode.net-8957e5"></a>
 </p>
 
+<p>
+  <img alt="Linux" src="https://img.shields.io/badge/Linux-supported-success?logo=linux&logoColor=white">
+  <img alt="macOS" src="https://img.shields.io/badge/macOS-supported-success?logo=apple&logoColor=white">
+  <img alt="Windows: via WSL2" src="https://img.shields.io/badge/Windows-WSL2-success">
+  <img alt="database: git" src="https://img.shields.io/badge/database-git-f05032?logo=git&logoColor=white">
+</p>
+
 </div>
 
 Spec-driven development with AI agents in the loop. SpexCode keeps a versioned tree of specs inside
@@ -23,16 +30,17 @@ implementation from drifting apart.
 English | [中文](./docs/README.zh-CN.md) · Docs: [spexcode.net](https://spexcode.net) · License: MIT
 
 Quick links: [the model](#the-model) · [quick start](#quick-start) ·
-[agents](#working-with-agents) · [yatsu](#measuring-behavior-yatsu) · [config](#configuration)
+[agents](#working-with-agents) · [eval](#measuring-behavior-eval) · [config](#configuration)
 
 ## The model
 
 <div align="center"><img src="docs/sdd-tuxedo-pooh.png" alt="spec-driven development meme" width="260"></div>
 
 A spec node is a directory under `.spec/` containing a `spec.md`: frontmatter (title, status, a
-`code:` list of the files it governs) plus a prose body stating what that part of the system is
-supposed to do, right now. Nodes nest, so the tree mirrors how you think about the project rather
-than the file layout. The body has two parts. The short **raw source** states the intent; changing it takes explicit
+`code:` pointer to the file it governs, a `related:` list for files it references) plus a prose
+body stating what that part of the system is supposed to do, right now. Nodes nest, so the tree
+mirrors how you think about the project rather than the file layout. The body can split into two
+labelled parts. The short **raw source** states the intent; changing it takes explicit
 human approval (an agent can draft it, a human signs off). The **expanded spec** is the agent's
 detailed reading of that intent; it iterates freely but must always match the raw source.
 
@@ -41,7 +49,7 @@ detailed reading of that intent; it iterates freely but must always match the ra
 Two rules make this workable:
 
 1. **Git is the database.** There is no separate store. A node's version count is the number of
-   commits that touched its `spec.md`, its history view is `git log` on that file, and each version
+   commits that changed its `spec.md`, its history view is `git log` on that file, and each version
    is attributed to an agent session through a `Session:` commit trailer. This is also why a spec
    body always describes present intent and gets rewritten in place: changelog headings inside the
    body are banned (the linter enforces it), because git already keeps the history.
@@ -49,23 +57,23 @@ Two rules make this workable:
    code it justifies. When code moves without its spec, the linter flags it,
 
    ```
-   drift: spec-cli/src/board.ts is 1 commit(s) ahead of spec 'board-lean' (v8) — may be stale
+   drift: spec-cli/src/graph.ts is 1 commit(s) ahead of spec 'graph-lean' (v12) — may be stale
    ```
 
    and keeps flagging until the spec catches up.
 
 ## The optimization loop
 
-Specs, commits, and yatsu readings compose into one loop. The spec is the loss function: it states what you want, and
-it's the half a human signs off on. Commits are the optimizer. **yatsu**, the measurement
-subsystem, is the eval: it scores how far live behavior currently sits from the spec, and the
+Specs, commits, and evals compose into one loop. The spec is the loss function: it states what you
+want, and it's the half a human signs off on. Commits are the optimizer. **eval**, the measurement
+subsystem, scores how far live behavior currently sits from the spec, and the
 score's history lives in git like everything else.
 
 <img src="docs/readme-loop.png" alt="the spec/code optimization loop">
 
 It also settles where the human stands day to day: nobody reads a neural net by staring at its
 weights, and between merge gates you don't have to stare at agent diffs either. Attention goes to
-the spec and the eval readings; the diff gets read once, at merge time.
+the spec and the evals; the diff gets read once, at merge time.
 
 ## Quick start
 
@@ -76,20 +84,20 @@ 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 dashboard           # board UI on :5173, proxying to the backend
+spex serve ui            # dashboard on :5173, proxying to the backend
 ```
 
 `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 pre-commit
-hooks, and writes a managed block into `CLAUDE.md`/`AGENTS.md` so any agent working in the repo
+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.
 
 Then grow the tree:
 
 1. Edit `.spec/project/spec.md` to describe the project.
-2. Add child nodes for the parts you want governed, each with a `code:` list pointing at existing
-   files.
-3. Run `spex lint`. Coverage warnings list the source files no spec claims yet; that list is your
+2. Add child nodes for the parts you want governed, each with a `code:` entry pointing at an
+   existing file (`related:` for the files it touches but doesn't own).
+3. Run `spex spec lint`. Coverage warnings list the source files no spec claims yet; that list is your
    adoption TODO.
 
 You are not expected to hand-author all of this. The intended workflow is to have an agent do most
@@ -97,7 +105,7 @@ of the spec writing; `spex guide spec` prints the exact file format it needs.
 [Getting started](https://spexcode.net/getting-started/) on the docs site walks the setup end to
 end.
 
-<img src="docs/readme-board.png" alt="dashboard screenshot">
+<img src="docs/readme-graph.png" alt="dashboard screenshot">
 
 *SpexCode's own repo on its own board; the sessions top-left are agents building the tool.*
 
@@ -107,7 +115,7 @@ This part needs tmux and a logged-in [Claude Code](https://www.anthropic.com/cla
 on the machine.
 
 ```sh
-spex new "make the settings page remember the last tab" --node settings
+spex session new "make the settings page remember the last tab" --node settings
 ```
 
 launches a worker session in its own worktree on branch `node/settings-…`. The `--node` flag (or a
@@ -123,9 +131,9 @@ themselves use when they delegate.
 You supervise from outside — on the board, or with the same commands your agent uses:
 
 ```sh
-spex watch              # stream session transitions: launched / review / done / needs-input ...
-spex review settings    # commits ahead of trunk, merge-base diff, typecheck/lint gates
-spex merge settings     # gated merge into the trunk
+spex session watch              # stream session transitions: launched / review / done / needs-input ...
+spex session review settings    # commits ahead of trunk, merge-base diff, merge-conflict/lint gates
+spex session merge settings     # gated merge into the trunk
 spex session close settings
 ```
 
@@ -138,28 +146,29 @@ hook stamps the attribution; the materialized contract block carries the rest, s
 prompt stays task-only. More on this mode of working:
 [working with agents](https://spexcode.net/working-with-agents/).
 
-## Measuring behavior: yatsu
+## Measuring behavior: eval
 
-yatsu — short for **You As The Stupid User** — is the measuring half of
-[the loop](#the-optimization-loop): you measure behavior from the product's real surface, the way a
-clueless real end user would touch it, not through an internal helper or shortcut that makes the
-proof easy. A spec says what a part should do; a
-`yatsu.md` beside it says how to check. Each scenario is a plain description plus an expected
-result. yatsu itself runs nothing (no DSL, no runner). An agent runs the scenario however it can:
+eval is the measuring half of
+[the loop](#the-optimization-loop), built on the YATU discipline (**You As The User**): you measure
+behavior from the product's real surface, the way a real end user would touch it, not through an
+internal helper or shortcut that makes the
+proof easy. A spec says what a part should do; an
+`eval.md` beside it says how to check. Each scenario is a plain description plus an expected
+result. eval itself runs nothing (no DSL, no runner). An agent runs the scenario however it can:
 a test file, a real browser, or just clicking through by hand and screenshotting. It compares
-actual to expected and files the reading with evidence:
+actual to expected and files the eval with evidence:
 
 ```sh
-spex yatsu eval settings --scenario remembers-tab --pass --image proof.png
+spex eval add settings --scenario remembers-tab --pass --image evidence.png
 ```
 
-Readings live in a git-tracked ndjson next to the spec, so measurements get the same attribution
-and history as spec versions. Bug fixes are expected to bracket: file a failing reading that
-reproduces the bug, fix, then file a passing reading on the same scenario.
+Evals live in a git-tracked ndjson next to the spec, so measurements get the same attribution
+and history as spec versions. Bug fixes are expected to bracket: file a failing eval that
+reproduces the bug, fix, then file a passing eval on the same scenario.
 
 <img src="docs/readme-eval.png" alt="eval view screenshot">
 
-*The eval view: scenario readings on the left; the selected reading's expected result, staleness,
+*The eval view: scenario evals on the left; the selected eval's expected result, staleness,
 and recorded video evidence in the middle.*
 
 ## What's in the repo
@@ -168,14 +177,14 @@ and recorded video evidence in the middle.*
 |---|---|
 | `spec-cli` | The `spex` CLI and the HTTP backend (Hono, runs via tsx, no build step). Reads `.spec` and git live; owns the session state machine and the linter. |
 | `spec-dashboard` | React board: the node graph, per-node spec/history/issues panes, and a real terminal onto each live agent session. |
-| `spec-yatsu` | Scenario definitions, readings, evidence blobs. |
-| `spec-forge` | Read-only tracer that resolves a forge's open issues and PRs to the spec nodes they serve (GitHub today). An issue links itself with a `Spec: <node-id>` line in its body; a PR from a `node/<id>` branch links for free. |
+| `spec-eval` | Scenario definitions, evals, evidence. |
+| `spec-forge` | Read-only tracer that resolves a forge's open issues and PRs to the spec nodes they serve (GitHub and GitLab drivers today). An issue links itself with a `Spec: <node-id>` line in its body; a PR from a `node/<id>` branch links for free. |
 
 ## The linter
 
-`spex lint` checks the spec↔code graph and is the real gate (the git hook is fast local feedback):
+`spex spec lint` checks the spec↔code graph and is the real gate (the git hook is fast local feedback):
 
-- **integrity** (error): a `code:` path that doesn't exist
+- **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
@@ -183,20 +192,23 @@ and recorded video evidence in the middle.*
 - **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`,
+`related-drift`, `owners`, `confusable-id` as warns) — `spex guide spec` lists them all.
+
 ## Configuration
 
 `spexcode.json` (committed, portable: layout, lint budgets, dashboard identity, launcher names) and
-`spexcode.local.json` (gitignored, host-specific: absolute launcher paths, plus a `private: true`
-overlay for repos you use but don't own) cover every setting. No `spex config set` yet: you edit the two files by hand (or ask your agent
-to), and `spex guide config` documents every field. The other
-manuals are `spex guide` (the workflow), `spex guide spec`, and `spex guide yatsu`; `spex help`
-maps the commands.
+`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
+manuals are `spex guide` (the workflow), `spex guide spec`, `spex guide eval`, and
+`spex guide footprint`; `spex help` maps the commands.
 
 ## Contributing
 
 [`docs/CONTRIBUTING.md`](docs/CONTRIBUTING.md) gets you from a clone to a first merged change.
 [`docs/AGENT_GUIDE.md`](docs/AGENT_GUIDE.md) has the full mechanics of the node model and the
-reflexive config system.
+reflexive plugin system.
 
 ## Credit
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spexcode",
-  "version": "0.2.8",
+  "version": "0.3.0",
   "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",
@@ -13,8 +13,8 @@
     "spec-cli/bin",
     "spec-cli/templates",
     "spec-cli/hooks",
-    "spec-yatsu/src",
-    "!spec-yatsu/src/**/*.test.ts",
+    "spec-eval/src",
+    "!spec-eval/src/**/*.test.ts",
     "spec-forge/src",
     "!spec-forge/src/**/*.test.ts",
     "spec-dashboard/dist",

package/spec-cli/bin/spex.mjs

@@ -17,9 +17,9 @@ const cli = join(pkg, 'src', 'cli.ts')
 // while a merge conflict is being resolved in the checkout that hosts it, the source holds conflict
 // markers and tsx dies with a raw esbuild stacktrace — on EVERY call, including the Stop hook and an
 // agent's `spex session done`. Catch that one transient state up front: scan the source trees the CLI
-// imports (spec-cli ←→ spec-yatsu ←→ spec-forge), and if any file carries a marker, print one actionable
+// imports (spec-cli ←→ spec-eval ←→ spec-forge), and if any file carries a marker, print one actionable
 // line and exit 75 (EX_TEMPFAIL: transient, retry) instead of spawning tsx into the stacktrace.
-const srcRoots = [join(pkg, 'src'), join(pkg, '..', 'spec-yatsu', 'src'), join(pkg, '..', 'spec-forge', 'src')]
+const srcRoots = [join(pkg, 'src'), join(pkg, '..', 'spec-eval', 'src'), join(pkg, '..', 'spec-forge', 'src')]
 const conflicted = srcRoots.flatMap((root) => {
   if (!existsSync(root)) return []
   return readdirSync(root, { recursive: true })

package/spec-cli/hooks/dispatch.sh

@@ -13,7 +13,7 @@
 #
 # The old (1) GATE — an auto-materialize when the config content-hash moved — is RETIRED ([[commit-surgery]]):
 # a harness event is never a materialize trigger; the materialize anchors are git-native only (spex verbs,
-# session-worktree creation, and the pre-commit/post-checkout/post-merge hooks). .config edits are
+# 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

package/spec-cli/hooks/harness.sh

@@ -59,15 +59,35 @@ hp_field() {
 # the session id from a payload (both harnesses use session_id).
 # Codex hooks run inside ONE shared per-project app-server. That process can inherit the FIRST launched
 # session's SPEXCODE_SESSION_ID, so on codex the payload session_id (the acting thread id) must win and then
-# hp_store_dir aliases it to the governed record. Claude's payload id already equals its governed record id,
-# so preferring SPEXCODE_SESSION_ID there preserves the launcher's pinned id path.
+# hp_store_dir aliases it to the governed record. Claude's payload id equals its governed record id, so the
+# PAYLOAD is the acting identity; the inherited env is only a fallback for payload-less events. Env-first was
+# a live bug: a nested subagent (Task tool) inherits the parent's SPEXCODE_SESSION_ID, so with env winning,
+# every child tool call fired mark-active against the PARENT's record — the parent read `working` forever and
+# every park/done declaration was clobbered within seconds (measured). Same staleness class the codex branch
+# already guards against (payload-first below); claude now follows the same rule.
 hp_session_id() {
+  local pid
   case "$SPEXCODE_HARNESS" in
     codex) hp_field "$1" session_id ;;
-    *)     printf '%s' "${SPEXCODE_SESSION_ID:-$(hp_field "$1" session_id)}" ;;
+    *)     pid=$(hp_field "$1" session_id); printf '%s' "${pid:-$SPEXCODE_SESSION_ID}" ;;
   esac
 }
 
+# is THIS payload a tool call executed by an IN-PROCESS SUBAGENT (Claude's Task tool — a sub-conversation
+# inside the SAME harness process) rather than the session's own top-level agent? The subagent's payload
+# carries the PARENT's session_id/transcript_path (measured live, claude 2.1.207), so hp_session_id cannot
+# tell them apart — but the harness stamps every subagent-executed call with a top-level `agent_id`
+# (+ `agent_type`) field that a top-level call NEVER carries. The check is structural, never a heuristic:
+# scan ONLY the payload prefix before the first `"tool_input"` (every harness-stamped top-level field
+# precedes tool_input), and require the key shape `"agent_id":`. Inside a JSON string value every quote is
+# escaped (\"), so a bare-quoted `"agent_id"` followed by a colon in that prefix can only be the harness's
+# own stamp — a tool parameter literally NAMED agent_id (an MCP tool) sits inside tool_input, past the
+# truncation, and file/prompt content can never fake an unescaped quote. Codex payloads carry no such field
+# (its verified field set) so this never matches there. Echoes "1" when yes, else nothing.
+hp_is_subagent() {
+  printf '%s' "${1%%\"tool_input\"*}" | grep -q '"agent_id"[[:space:]]*:' && printf 1
+}
+
 # the per-PROJECT GLOBAL runtime dir (mirrors spec-cli/src/layout.ts `runtimeRoot`): <store>/projects/<enc>,
 # keyed by the project (dirname of the ABSOLUTE git-common-dir, so the answer is identical from main or any
 # worktree). The per-session dirs and the per-tree materialize slots (hp_tree_dir) live under it.
@@ -114,7 +134,7 @@ hp_store_dir() {
 
 # the TOOLCHAIN's own version fingerprint — the toolchain side of the content key. The materialized artifacts
 # are a function of (config content, toolchain), so a TOOLCHAIN update must move the key too, or an updated
-# deploy never self-heals its stale contract/shims/manifest until someone happens to edit .config (the field
+# deploy never self-heals its stale contract/shims/manifest until someone happens to edit .plugins (the field
 # lesson: a toolchain update does NOT self-heal). A source checkout answers with the git TREE hash of the
 # package dir (moves exactly when the toolchain's content moves, not on every repo commit); an npm install
 # (no .git) answers with the package.json hash (npm bumps the version). env-stripped git — a git hook's
@@ -127,7 +147,7 @@ hp_toolchain_version() {
 }
 
 # the deterministic content fingerprint of EVERYTHING the materialize is a function of: the EDITABLE config
-# roots (.config + config md/sh), the PERSISTED POLICY files (the MAIN checkout's spexcode.json +
+# roots (.plugins + plugin-system md/sh), the PERSISTED POLICY files (the MAIN checkout's spexcode.json +
 # spexcode.local.json — the `harnesses` set materialize reads via readConfig(mainCheckout)), and the
 # toolchain version above. Since the dispatch-gate retired ([[commit-surgery]] — materialize anchors on
 # git-native events only), this is a FRESHNESS STAMP materialize records after each pass, a diagnostic
@@ -138,7 +158,7 @@ hp_config_hash() {
   gcd=$(env -u GIT_DIR -u GIT_INDEX_FILE git rev-parse --path-format=absolute --git-common-dir 2>/dev/null) \
     || gcd=$(realpath "$(env -u GIT_DIR -u GIT_INDEX_FILE git rev-parse --git-common-dir 2>/dev/null)" 2>/dev/null)
   { hp_toolchain_version
-    find .spec/*/.config .spec/*/config \( -name '*.md' -o -name '*.sh' \) -type f -print0 2>/dev/null \
+    find .spec/*/.plugins .spec/*/plugin-system \( -name '*.md' -o -name '*.sh' \) -type f -print0 2>/dev/null \
       | sort -z | xargs -0 cat 2>/dev/null
     [ -n "$gcd" ] && cat "$(dirname "$gcd")/spexcode.json" "$(dirname "$gcd")/spexcode.local.json" 2>/dev/null
   } | sha256sum | cut -d' ' -f1

package/spec-cli/src/attach.ts

@@ -9,7 +9,7 @@ import { spawnSync } from 'node:child_process'
 import { networkInterfaces } from 'node:os'
 import { alive, apiBase, TMUX_SOCK } from './sessions.js'
 
-const AGENT_ALTERNATIVES = 'read the pane with `spex session capture`, drive it with `session send` / `session rawkey`'
+const AGENT_ALTERNATIVES = 'read the pane with `spex session show <SEL> --capture`, drive it with `session send` (plain text first; `--keys` only as a last resort)'
 
 // attach only makes sense on the machine that runs the tmux server — the backend's. The board the selector
 // resolved against IS that backend, so the test is: does the RESOLVED backend (see [[remote-client]]'s
@@ -41,7 +41,7 @@ An agent must not run it inside a turn (it freezes you); ${AGENT_ALTERNATIVES}.`
   }
   if (!(await alive(id))) {
     console.error(`spex session attach: ${id} is offline — no live tmux session to attach.
-Bring it back with \`spex session reopen ${id}\`, or read its record with \`spex ls ${id}\`.`)
+Bring it back with \`spex session resume ${id}\`, or read its record with \`spex session show ${id}\`.`)
     process.exit(1)
   }
   console.log(`attaching to ${id} — detach with C-b d (the session keeps running)`)