spexcode 0.2.1 → 0.2.2

package/README.md

@@ -1,149 +1,193 @@
-<img src="docs/sdd-tuxedo-pooh.png" alt="Writing code vs. authoring a living, executable specification artifact" width="420">
+<img src="docs/sdd-tuxedo-pooh.png" alt="tuxedo pooh meme" width="420">
 
-English | [中文](./README.zh-CN.md)
+# SpexCode
 
-> Spec-driven development fails two ways: the spec drifts out of sync with the code, or it
-> bloats into stale ceremony. SpexCode keeps each spec short and current: rewritten in place
-> and versioned by git, not an accumulating changelog.
+Spec-driven development with AI agents in the loop. SpexCode keeps a versioned tree of specs inside
+your git repo, links every spec to the code it governs, and runs a session manager that dispatches
+coding agents into isolated worktrees. You review and merge; the tool keeps intent and
+implementation from drifting apart. (All screenshots below are this very repo on its own board.)
 
-**SpexCode** is a spec-driven, self-developing dev tool. Every part of a project becomes a versioned
-*spec node*: a `.spec/**/spec.md` whose body states the part's present intent. Git is the database:
-a node's version is its count of content commits, and "drift" is governed code that moved ahead of
-its spec. The `spex` CLI and the live dashboard read everything straight from git; there is no
-separate store.
+English | [中文](./README.zh-CN.md) · Docs: [spexcode.net](https://spexcode.net) · License: MIT
 
-- **[Using SpexCode](#using-spexcode)** — adopt the `spex` CLI and drive it through your coding agent to govern *your own* project.
-- **[Contributing to SpexCode](#contributing-to-spexcode)** — hack on the tool itself, in this repo.
-- **[Working with agents →](https://spexcode.net/working-with-agents/)** — the longer write-up on the docs site.
+Quick links: [the model](#the-model) · [quick start](#quick-start) ·
+[agents](#working-with-agents) · [yatsu](#measuring-behavior-yatsu) · [config](#configuration)
 
----
+## The model
 
-## Using SpexCode
+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
+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.
 
-You set SpexCode up once (`npm i -g spexcode`, then `spex init` in your repo). After that, the main
-way to use it is by talking to your coding agent. You describe what you want in plain language
-(*"add a spec node for the auth flow", "extract specs for this package", "dispatch a worker to
-implement Y"*) and the agent runs the `spex` CLI for you while you supervise on the board. The
-manual CLI below is the substrate; your agent is the daily interface.
+<img src="docs/readme-node.png" alt="spec node popup">
 
-That works because a freshly launched agent already knows SpexCode. `spex init` materializes the
-contract (the spec-node ritual, the commit-before-declare gate, the merge style) into a
-`<!-- spexcode -->` managed block in your repo's `CLAUDE.md`/`AGENTS.md`, which
-**[Claude Code](https://www.anthropic.com/claude-code)** and **Codex** auto-discover as always-on
-context. From there the agent self-serves detail on demand from the built-in manual: `spex guide`
-(the workflow), `spex guide spec` / `spex guide yatsu` (the file formats), and `spex guide config`
-(every `spexcode.json` setting). You can tell it *"run `spex guide config` and set me up a
-launcher"*.
+Two rules make this workable:
 
-The docs site covers this in full: **[working with agents](https://spexcode.net/working-with-agents/)**
-for the agent-driven workflow, **[getting started](https://spexcode.net/getting-started/)** for the
-setup end to end.
+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
+   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.
+2. **Spec and code land together.** A change is one commit that updates both the `spec.md` and the
+   code it justifies. When code moves without its spec, the linter flags it,
 
-> **It's also just plain tooling.** Strip the agent away and the core is still useful on its own:
-> spec files versioned by git, checked by `spex lint` and shown on a read-only dashboard. No AI,
-> nothing to run but Node and git. The vibe-coding path sits on top of that; it doesn't replace it.
+   ```
+   drift: spec-cli/src/board.ts is 1 commit(s) ahead of spec 'board-lean' (v8) — may be stale
+   ```
 
-> **Requirements.** Core: **Node ≥ 22** and **git**. Driving SpexCode through an agent (or
-> dispatching workers onto your nodes) also needs **tmux** and an authenticated **Claude Code or
-> Codex** on your PATH. Those agents run commands on your machine, so read
-> [`SECURITY.md`](./docs/SECURITY.md) before exposing the backend.
+   and keeps flagging until the spec catches up.
 
-### Set it up
+## The optimization loop
 
-Install the published CLI once, then adopt it in any project:
+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
+score's history lives in git like everything else.
 
-```sh
-npm i -g spexcode      # installs the `spex` command (needs Node ≥ 22)
-cd ~/my-app
-spex init              # additive — never restructures your code
-```
+<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.
 
-`spex init` is additive: it seeds a starter **`.spec/`** tree (a root `project` node plus the
-`.config` plugins that define the dev flow), a starter **`spexcode.json`**, and the per-clone
-**git hooks** (a `pre-commit` hook that runs **spec-lint**, blocking on broken spec↔code links, and
-**main-guard**, which blocks direct commits to `main`, plus a `prepare-commit-msg` hook that stamps
-each commit's session attribution). It also **materializes** the harness artifacts that make the
-agent path work: the `<!-- spexcode -->` contract block in `CLAUDE.md`/`AGENTS.md`, and the
-`.claude/` / `.codex/` shims (the `settings.json` hooks) a self-launched agent discovers. Those
-artifacts are generated and gitignored; they are regenerated on each machine, never committed.
+## Quick start
 
-Then make it yours — either ask your agent to, or do it by hand: edit `.spec/project/spec.md` to
-describe the project, point `spexcode.json`'s `lint.governedRoots` at your real source dir(s), and
-check the graph:
+Requires Node ≥ 22 and git. This part is plain tooling — no AI involved yet.
 
 ```sh
-spex lint              # the "coverage" warnings are your adoption TODO list
+npm i -g spexcode        # installs the `spex` command
+cd your-repo
+spex init                # seeds .spec/, installs git hooks, renders the agent contract
+spex serve               # API backend on :8787
+spex dashboard           # board UI on :5173, proxying to the backend
 ```
 
-### Configure it
+`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
+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
+   adoption TODO.
 
-Two optional JSON files at the repo root hold every setting, split by portability:
+You are not expected to hand-author all of this. The intended workflow is to have an agent do most
+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.
 
-- **`spexcode.json`** — *committed, portable*: layout, dashboard identity (`title` + `icon`), lint
-  budgets, and launcher **names**. Facts that are true for the project.
-- **`spexcode.local.json`** — *gitignored, host-specific*: absolute launcher command paths,
-  cert/secret paths, and the private-overlay switch (`private: true`, which makes `spex materialize`
-  leave zero trace in the tracked tree — ignores go to the local git exclude, not the committed
-  `.gitignore` — so you can run SpexCode on a repo you share but don't own). Facts that are true for
-  one machine.
+<img src="docs/readme-board.png" alt="dashboard screenshot">
 
-There is no `spex config set` — you (or your agent) edit the files directly. **`spex guide config`**
-is the authoritative manual for every field and which of the two files it belongs in.
+*SpexCode's own repo on its own board; the sessions top-left are agents building the tool.*
 
-### Run it
+## Working with agents
 
-Start the backend and the dashboard, then open the board:
+This part needs tmux and a logged-in [Claude Code](https://www.anthropic.com/claude-code) or Codex
+on the machine.
 
 ```sh
-spex serve          # the backend (API + sessions), on :8787
-spex dashboard      # the board UI on :5173, proxying /api to the backend
+spex new "make the settings page remember the last tab" --node settings
 ```
 
-Open <http://localhost:5173>.
+launches a worker session in its own worktree on branch `node/settings`. The worker reads the
+governing spec before touching code, 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
+themselves. The merge stays with the manager: when you fire it, the session's own agent runs the
+actual `git merge`, so conflicts land on the one who knows the work. The same dispatch is a
+button on the dashboard (the new-session box on the board); the command form is what agents
+themselves use when they delegate.
 
-Both ports are flags (`spex serve --port 8788`, `spex dashboard --port 5174 --api-port 8788`), so
-you can run several projects' boards side by side; the working directory picks which project each
-serves. Give each tab its own identity in that project's `spexcode.json`: `dashboard.title` names it
-and `dashboard.icon` sets the favicon — an emoji (`"🔭"`), an Iconify name (`"mdi:rocket-launch"`),
-or a URL.
+You supervise from outside — on the board, or with the same commands your agent uses:
 
-Day to day (the commands your agent runs for you — and that you can run yourself):
+```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 close settings
+```
 
-| 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` / `config` manuals |
-| `spex board` | dump the current board state as JSON |
+Independent tasks run in parallel. Each worker is isolated in its own worktree, git serializes the
+merges, and a pre-commit guard blocks direct commits on the trunk, so everything flows through
+reviewable node branches.
 
----
+The process is enforced by mechanism, not prompt engineering: the backend creates the branch and a
+hook stamps the attribution; the materialized contract block carries the rest, so your dispatch
+prompt stays task-only. More on this mode of working:
+[working with agents](https://spexcode.net/working-with-agents/).
 
-## Contributing to SpexCode
+## Measuring behavior: yatsu
 
-This repository *is* the SpexCode source, and it dogfoods itself: every change to the tool lands as
-a spec node merged into `main`. Set up a checkout:
+yatsu is the measuring half of [the loop](#the-optimization-loop). 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:
+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:
 
 ```sh
-git clone https://github.com/shuxueshuxue/spexcode && cd spexcode
-npm --prefix spec-cli install
-npm --prefix spec-dashboard install
-npm run hooks          # install the per-clone git hooks (main-guard + the session-stamp hook)
+spex yatsu eval settings --scenario remembers-tab --pass --image proof.png
 ```
 
-The development loop runs from source, with hot reload (`npm run web`, as opposed to an installed
-user's `spex dashboard`):
+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.
 
-```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
-```
+<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,
+and recorded video evidence in the middle.*
+
+## What's in the repo
+
+| Package | Role |
+|---|---|
+| `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. |
+
+## The linter
+
+`spex 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
+- **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
+
+## 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.
+
+## Status
 
----
+SpexCode develops itself with itself: the `.spec/` tree in this repo is the tool's own spec, and
+every change to the tool lands through the same worker/manager loop it implements. The dashboard
+you install is the one it was built on. Known warts: `spex session new --help`
+doesn't print help, it creates a session named `--help` (dispatch with `spex new`). And the
+altitude lint currently reports forty-odd warnings against this repo's own specs; I haven't had
+time to pay that down.
+The first public write-up was posted on the [LINUX DO](https://linux.do) community — thanks for
+the first round of discussion there.
 
-## Credits
+## Contributing
 
-SpexCode was first introduced publicly on [LINUX DO](https://linux.do) — thanks to the community
-there for the first round of discussion and feedback.
+[`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.
 
 ## License
 

package/README.zh-CN.md

@@ -1,134 +1,169 @@
-<img src="docs/sdd-tuxedo-pooh.png" alt="写代码 vs. 维护一份活的、可执行的规格文档" width="420">
+<img src="docs/sdd-tuxedo-pooh.png" alt="tuxedo pooh 梗图" width="420">
 
-[English](./README.md) | 中文
+# SpexCode
 
-> Spec 驱动开发通常死于两种方式:spec 和代码脱节,或者膨胀成一堆过时的仪式文档。SpexCode 让每个
-> spec 保持简短、保持当前态:原地重写,由 git 记版本,不做累积式的 changelog。
+把 AI agent 纳入回路的 spec 驱动开发。SpexCode 在你的 git 仓库里维护一棵带版本的 spec 树,把每个
+spec 和它管辖的代码链接起来,并运行一个会话管理器,把 coding agent 派进相互隔离的 worktree。你负责
+review 和 merge;工具负责让意图和实现不分家。(下面所有截图都是这个仓库自己跑在自己看板上的样子。)
 
-**SpexCode** 是一个 spec 驱动、用自己开发自己的开发工具。项目的每个部分都是一个带版本的
-*spec 节点*,即一个 `.spec/**/spec.md`,正文描述这个部分当前的意图。git 就是数据库:节点的版本号
-是它的内容 commit 数,"drift" 指被管辖的代码走到了 spec 前面。`spex` CLI 和实时看板直接从 git
-读取这一切,没有第二份存储。
+[English](./README.md) | 中文 · 文档:[spexcode.net](https://spexcode.net) · License: MIT
 
-- **[使用 SpexCode](#使用-spexcode)**:安装 `spex` CLI,通过你的 coding agent 治理*你自己的*项目。
-- **[参与开发](#参与开发)**:在本仓库里改进工具本身。
-- **[Working with agents →](https://spexcode.net/working-with-agents/)**:文档站上更完整的介绍。
+快捷入口:[模型](#模型) · [快速开始](#快速开始) · [agent](#和-agent-一起工作) ·
+[yatsu](#测量行为yatsu) · [配置](#配置)
 
----
+## 模型
 
-## 使用 SpexCode
+一个 spec 节点就是 `.spec/` 下的一个目录,里面有一个 `spec.md`:frontmatter(title、status、
+声明管辖文件的 `code:` 清单)加一段正文,描述系统这一部分当前应该做什么。节点可以嵌套,所以这棵树
+对应你对项目的理解方式,而不是文件布局。正文分两个部分。很短的 **raw source** 写意图,改它需要
+人的明确认可,agent 起草、人拍板的也算;**expanded spec** 是 agent 对这个意图的详细展开,自由
+迭代,但必须始终和 raw source 一致。
 
-SpexCode 只需要设置一次(`npm i -g spexcode`,然后在你的仓库里 `spex init`)。之后的主要用法是和
-你的 coding agent 对话:用自然语言说你要什么(*"给鉴权流程加一个 spec 节点""把这个包的 spec
-提取出来""派一个 worker 去实现 Y"*),agent 替你执行 `spex` CLI,你在看板上盯进度。下面的手动
-CLI 是底座,agent 才是日常界面。
+<img src="docs/readme-node.png" alt="节点弹窗">
 
-这套之所以成立,是因为新启动的 agent 已经认识 SpexCode。`spex init` 会把整套约定(spec 节点流程、
-先 commit 再声明完成、merge 方式)生成到仓库 `CLAUDE.md`/`AGENTS.md` 里的 `<!-- spexcode -->`
-托管块中,**[Claude Code](https://www.anthropic.com/claude-code)** 和 **Codex** 启动时自动读到。
-更细的内容 agent 自己按需查内置手册:`spex guide`(工作流)、`spex guide spec` /
-`spex guide yatsu`(文件格式)、`spex guide config`(`spexcode.json` 的全部配置项)。你可以直接
-对它说*"跑一下 `spex guide config`,帮我配好 launcher"*。
+两条规则让这套东西成立:
 
-完整的说明在文档站:**[working with agents](https://spexcode.net/working-with-agents/)** 讲
-agent 驱动的用法,**[getting started](https://spexcode.net/getting-started/)** 从头到尾走一遍安装。
+1. **git 就是数据库。** 没有第二份存储。节点的版本号是碰过它 `spec.md` 的 commit 数,历史视图就是
+   这个文件的 `git log`,每一版通过 `Session:` commit trailer 归属到写它的 agent 会话。也因为这样,
+   spec 正文永远只描述当前意图、原地重写:正文里禁止出现 changelog 标题(linter 强制),历史 git
+   已经记了。
+2. **spec 和代码一起落地。** 一次改动就是一个 commit,同时更新 `spec.md` 和它所解释的代码。代码
+   要是脱开 spec 单独动了,linter 会标出来,
 
-> **抛开 agent,它也是一套普通工具。** 核心部分单独用也成立:git 记版本的 spec 文件,`spex lint`
-> 检查,只读看板展示。不含 AI,除了 Node 和 git 什么都不用跑。vibe coding 的玩法建立在这层之上,
-> 不是替代它。
+   ```
+   drift: spec-cli/src/board.ts is 1 commit(s) ahead of spec 'board-lean' (v8) — may be stale
+   ```
 
-> **环境要求。** 核心:**Node ≥ 22** 和 **git**。要通过 agent 驱动(或者往节点上派 worker),
-> 还需要 **tmux** 和 PATH 里已登录的 **Claude Code 或 Codex**。这些 agent 会在你的机器上执行
-> 命令,对外暴露后端之前请先读 [`SECURITY.md`](./docs/SECURITY.md)。
+   一直标到 spec 跟上为止。
 
-### 安装
+## 优化循环
 
-装一次发布版 CLI,然后在任何项目里接入:
+spec、commit、yatsu 读数,这几样合起来是一个循环。spec 是损失函数:定义你要什么,这一半由人拍板。commit 是优化器。
+**yatsu** 是测量子系统,负责评估:量出当前行为离 spec 还有多远,分数的历史照样存在 git 里。
 
-```sh
-npm i -g spexcode      # 安装 spex 命令(需要 Node ≥ 22)
-cd ~/my-app
-spex init              # 纯增量,不会动你的代码结构
-```
+<img src="docs/readme-loop.zh.png" alt="优化循环示意">
+
+它也决定了人平时站在哪:没有人靠盯权重去读神经网络,两次 merge 之间同样不必盯着 agent 的 diff。
+注意力放在 spec 和 eval 读数上;diff 只在 merge 的时候读一次。
 
-`spex init` 是增量式的:生成一棵起始 **`.spec/`** 树(根 `project` 节点,加上定义开发流程的
-`.config` 插件)、一份起始 **`spexcode.json`**、每个 clone 各自的 **git hooks**(`pre-commit`
-跑 **spec-lint**,spec↔code 链接坏了会拦下;**main-guard** 拦截直接向 `main` 的提交;
-`prepare-commit-msg` 给每个 commit 盖 session 归属戳)。同时生成 agent 路径需要的产物:
-`CLAUDE.md`/`AGENTS.md` 里的 `<!-- spexcode -->` 契约块,以及 `.claude/`、`.codex/` 的
-settings hooks。这些产物是生成物,已被 gitignore,每台机器各自重新生成,不进版本库。
+## 快速开始
 
-然后把它变成你的项目,让 agent 改或者自己动手都行:编辑 `.spec/project/spec.md` 描述项目,把
-`spexcode.json` 的 `lint.governedRoots` 指向真实源码目录,再检查一遍:
+需要 Node ≥ 22 和 git。这一步是普通工具,还不涉及 AI。
 
 ```sh
-spex lint              # coverage 警告就是你的接入 TODO 清单
+npm i -g spexcode        # 安装 spex 命令
+cd your-repo
+spex init                # 生成 .spec/、安装 git hooks、渲染 agent 契约
+spex serve               # API 后端,:8787
+spex dashboard           # 看板 UI,:5173,代理到后端
 ```
 
-### 配置
+`spex init` 是增量式的,在任何已有 git 仓库上可用,不会覆盖你的文件:生成根节点
+`.spec/project/spec.md`、一份起始 `spexcode.json`、pre-commit hooks,并向 `CLAUDE.md`/`AGENTS.md`
+写入一个托管块,让任何在这个仓库里工作的 agent 自己发现这套工作流。
+
+然后把树长起来:
+
+1. 编辑 `.spec/project/spec.md`,描述项目。
+2. 给想管辖的部分加子节点,每个带一个指向现有文件的 `code:` 清单。
+3. 跑 `spex lint`。coverage 警告列出还没有 spec 认领的源文件,那就是你的接入 TODO。
 
-仓库根目录两个可选的 JSON 文件承载全部设置,按可移植性分开:
+这些不需要你全部手写。预期的用法是让 agent 完成大部分 spec 写作;`spex guide spec` 会打印它需要的
+确切文件格式。完整的安装过程见文档站的
+[getting started](https://spexcode.net/getting-started/)。
 
-- **`spexcode.json`**:提交进仓库,可移植。布局、看板标识(`title` + `icon`)、lint 预算、
-  launcher 的**名字**。对整个项目成立的事实。
-- **`spexcode.local.json`**:gitignore,单机。launcher 命令的绝对路径、证书和密钥路径、私有覆盖
-  开关(`private: true`,让 `spex materialize` 在被跟踪的文件里不留任何痕迹,ignore 写进本地
-  git exclude 而不是提交的 `.gitignore`,适合你参与但不拥有的仓库)。只对这台机器成立的事实。
+<img src="docs/readme-board.png" alt="看板截图">
 
-没有 `spex config set`,你(或你的 agent)直接编辑文件。每个字段的含义、该放哪个文件,
-**`spex guide config`** 是权威手册。
+*SpexCode 自己的仓库跑在自己的看板上;左上角那些会话就是正在造它的 agent。*
 
-### 运行
+## 和 agent 一起工作
 
-启动后端和看板,打开页面:
+这一步需要 tmux 和本机已登录的 [Claude Code](https://www.anthropic.com/claude-code) 或 Codex。
 
 ```sh
-spex serve          # 后端(API + sessions),:8787
-spex dashboard      # 看板 UI,:5173,/api 代理到后端
+spex new "让设置页记住上次打开的标签" --node settings
 ```
 
-打开 <http://localhost:5173>。
+会在 `node/settings` 分支的独立 worktree 里启动一个 worker 会话。worker 动代码之前先读管辖 spec,
+做出改动,把 spec 正文改写到和实现一致,把两者一起 commit(hook 自动盖 `Session:` 戳),然后提出
+merge 并停下。worker 不自己 merge。合并留在管理者手里:你按下 merge 时,实际的 git merge 由这个
+会话自己的 agent 执行,冲突落在最懂这份活的人手里。同样的派工在看板网页上就是一个按钮(board 的
+new-session 输入框);命令行形态是 agent 之间互相委派时用的。
 
-两个端口都是参数(`spex serve --port 8788`、`spex dashboard --port 5174 --api-port 8788`),
-多个项目的看板可以并排跑,工作目录决定各自服务哪个项目。每个标签页的身份在各自项目的
-`spexcode.json` 里配:`dashboard.title` 定名字,`dashboard.icon` 定 favicon,emoji(`"🔭"`)、
-Iconify 名字(`"mdi:rocket-launch"`)或 URL 都行。
+你在外面督工,用看板,或者用 agent 也在用的这几条命令:
 
-日常命令(agent 替你跑,你也可以自己跑):
+```sh
+spex watch              # 实时输出会话状态变化:launched / review / done / needs-input ...
+spex review settings    # 领先 trunk 的 commit、merge-base diff、typecheck/lint 门
+spex merge settings     # 有门禁的 merge 入 trunk
+spex session close settings
+```
 
-| 命令 | 作用 |
-| --- | --- |
-| `spex lint` | 检查 spec↔code 图:coverage、drift、living 规则 |
-| `spex watch` | 实时输出 session / 看板的状态变化 |
-| `spex guide` | 打印完整工作流,以及 `spec.md` / `yatsu.md` / `config` 手册 |
-| `spex board` | 以 JSON 输出当前看板状态 |
+相互独立的任务并行跑。每个 worker 隔离在自己的 worktree 里,merge 由 git 序列化,pre-commit 守卫
+拦截对 trunk 的直接提交,所以一切都从可 review 的 node 分支流过。
 
----
+流程靠机制强制,不靠提示词工程:后端建分支、hook 盖归属戳,其余规则由 materialize 出的契约块承载,
+所以派工提示词只需要写任务本身。这套工作方式的长版本:
+[working with agents](https://spexcode.net/working-with-agents/)。
 
-## 参与开发
+## 测量行为:yatsu
 
-这个仓库就是 SpexCode 的源码,而且它 dogfood 自己:工具的每个改动都以 spec 节点的形式合入
-`main`。搭一个开发环境:
+yatsu 就是[优化循环](#优化循环)里负责测量的那一半。spec 说这部分应该做什么;旁边的 `yatsu.md` 说怎么验。每条
+scenario 就是一段普通描述加一个期望结果。yatsu 自己什么都不跑(没有 DSL,也没有 runner)。agent
+用顺手的方式执行场景:测试文件、真实浏览器,或者干脆手点一遍截个图。把实际结果和期望对比,连证据
+一起把读数记档:
 
 ```sh
-git clone https://github.com/shuxueshuxue/spexcode && cd spexcode
-npm --prefix spec-cli install
-npm --prefix spec-dashboard install
-npm run hooks          # 安装每个 clone 各自的 git hooks(main-guard + session 戳)
+spex yatsu eval settings --scenario remembers-tab --pass --image proof.png
 ```
 
-开发循环直接跑源码,带热重载(开发用 `npm run web`,区别于安装用户的 `spex dashboard`):
+读数存在 spec 旁边一个 git 跟踪的 ndjson 里,所以测量和 spec 版本享有同样的归属和历史。修 bug 要求
+成对:先记一条复现 bug 的 fail 读数,修掉,再在同一条 scenario 上记一条 pass。
 
-```sh
-npm run api            # 后端 :8787,spec-cli/src 改动即热重载
-npm run web            # Vite 起看板(HMR),/api 代理到 :8787
-```
+<img src="docs/readme-eval.png" alt="eval 视图截图">
 
----
+*eval 视图:左侧是各 scenario 的读数;中间是选中读数的期望结果、过期原因和录屏证据。*
 
-## 致谢
+## 仓库里有什么
+
+| 包 | 职责 |
+|---|---|
+| `spec-cli` | `spex` CLI 和 HTTP 后端(Hono,tsx 直跑,无构建步骤)。实时读 `.spec` 和 git;会话状态机和 linter 都在这里。 |
+| `spec-dashboard` | React 看板:节点图、每个节点的 spec/history/issues 面板,以及连到每个活跃 agent 会话的真终端。 |
+| `spec-yatsu` | scenario 定义、读数、证据文件。 |
+| `spec-forge` | 只读追踪器,把 forge 上的 open issue 和 PR 解析到它们服务的 spec 节点(目前支持 GitHub)。issue 在正文里写一行 `Spec: <node-id>` 即完成链接;从 `node/<id>` 分支开的 PR 自动链接。 |
+
+## linter
+
+`spex lint` 检查 spec↔code 图,它才是真正的门(git hook 只是快速的本地反馈):
+
+- **integrity**(error):`code:` 指向不存在的路径
+- **living**(error):spec 正文里出现 changelog 标题
+- **altitude**(warn):正文从契约层滑落成实现细节堆。常见的味道是一串编号步骤,或者满屏函数名;
+  spec 正文还能读得下去,靠的就是这条
+- **coverage**(warn):没被认领的源文件
+- **drift**(warn):被管辖的代码在 spec 最后一版之后又改了,实时从 git 推导
+
+## 配置
+
+`spexcode.json`(提交进仓库,可移植:布局、lint 预算、看板标识、launcher 名字)和
+`spexcode.local.json`(gitignore,单机:launcher 绝对路径,以及给你参与但不拥有的仓库用的
+`private: true` 覆盖)承载全部设置。暂时没有 `spex config set`:两个文件直接手改(或让 agent 改),每个字段的文档在
+`spex guide config`。其他手册:`spex guide`(工作流)、`spex guide spec`、
+`spex guide yatsu`;`spex help` 列出全部命令。
+
+## 现状
+
+SpexCode 用它自己开发自己:这个仓库的 `.spec/` 树就是工具自身的 spec,对工具的每个改动都走它
+自己实现的那套 worker/manager 循环落地。你装到的看板就是造它用的那块。已知的坑:`spex session new --help`
+不会打印帮助,而是真的创建一个叫 `--help` 的会话(派工请用 `spex new`)。另外 altitude lint 现在
+对这个仓库自己的 spec 报着四十多条警告,我还没腾出手来清。首次公开介绍发在
+[LINUX DO](https://linux.do) 社区,感谢佬友们的第一轮讨论。
+
+## 参与开发
 
-SpexCode 的首次公开介绍发在 [LINUX DO](https://linux.do),感谢佬友们的第一轮讨论和反馈。
+[`docs/CONTRIBUTING.md`](docs/CONTRIBUTING.md) 带你从 clone 到第一个合入的改动。
+[`docs/AGENT_GUIDE.md`](docs/AGENT_GUIDE.md) 有节点模型和反身配置系统的完整机制。
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spexcode",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "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",

package/spec-cli/bin/spex.mjs

@@ -2,7 +2,7 @@
 // @@@ spex launcher - this repo has no build step, so the installed `spex` bin shells to tsx to
 // run the TypeScript CLI directly. After `npm link` (or a global install) `spex lint` works anywhere.
 import { spawn } from 'node:child_process'
-import { existsSync } from 'node:fs'
+import { existsSync, readdirSync, readFileSync } from 'node:fs'
 import { createRequire } from 'node:module'
 import { fileURLToPath } from 'node:url'
 import { dirname, join } from 'node:path'
@@ -12,6 +12,29 @@ import { dirname, join } from 'node:path'
 // `spex` work from any cwd (agents, git hooks) against this package's code, operating on the cwd.
 const pkg = join(dirname(fileURLToPath(import.meta.url)), '..') // spec-cli/
 const cli = join(pkg, 'src', 'cli.ts')
+
+// @@@ mid-merge guard - no build step means every spex call parses this package's live TypeScript, so
+// 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
+// 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 conflicted = srcRoots.flatMap((root) => {
+  if (!existsSync(root)) return []
+  return readdirSync(root, { recursive: true })
+    .filter((f) => /\.(ts|tsx|js|mjs)$/.test(String(f)))
+    .map((f) => join(root, String(f)))
+    .filter((path) => {
+      try { return /^<{7} /m.test(readFileSync(path, 'utf8')) } catch { return false }
+    })
+})
+if (conflicted.length) {
+  console.error('spex: paused mid-merge — unresolved conflict markers in the source spex runs:')
+  for (const f of conflicted) console.error(`  ${f}`)
+  console.error('spex executes this TypeScript directly (no build step); resolve the merge, then retry. (exit 75)')
+  process.exit(75)
+}
 // tsx lives in spec-cli/node_modules in the dev monorepo, but npm may hoist it above the installed
 // `spexcode` package in a real consumer project. Try local candidates first, then let Node resolve upward
 // from spec-cli so project-local and global installs work the same way.