spexcode 0.2.0 → 0.2.2

package/README.md

@@ -1,146 +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">
 
-> 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,
-> versioned by git, never an accumulating changelog.
+# SpexCode
 
-**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 — and **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. A `spex` CLI plus a live dashboard read all of it straight from git; there is no
-separate store.
+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.)
 
-- **[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 deeper narrative on the docs site, behind this landing.
+English | [中文](./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)
 
-## Using SpexCode
+## The model
 
-You set SpexCode up once — `npm i -g spexcode` then `spex init` in your repo — and after that the primary
-way you 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.
+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.
 
-That works because a freshly-launched agent **already knows SpexCode**. `spex init` materializes the whole
-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 (no `--append-system-prompt`, nothing to wire). 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 literally say *"run `spex guide
-config` and set me up a launcher"* and it will.
+<img src="docs/readme-node.png" alt="spec node popup">
 
-For the full narrative — the three pillars of driving SpexCode by talking to your agent (agent
-self-learning via the materialized block + `spex guide`, config, and the init artifacts) — see
-**[working with agents](https://spexcode.net/working-with-agents/)** on the docs site;
-**[getting started](https://spexcode.net/getting-started/)** walks the setup end to end. This README is
-the concise landing; the site goes deep.
+Two rules make this workable:
 
-> **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, and nothing
-> to run but Node and git. The vibe-coding path sits *on top* of that; it doesn't replace it.
+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,
 
-> **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
-> — and those agents run commands on your machine, so read [`SECURITY.md`](./docs/SECURITY.md) before
-> exposing the backend.
+   ```
+   drift: spec-cli/src/board.ts is 1 commit(s) ahead of spec 'board-lean' (v8) — may be stale
+   ```
 
-### Set it up
+   and keeps flagging until the spec catches up.
 
-Install the published CLI once, then adopt it in any project:
+## 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
+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.
+
+## Quick start
+
+Requires Node ≥ 22 and git. This part is plain tooling — no AI involved yet.
 
 ```sh
-npm i -g spexcode      # installs the `spex` command (needs Node ≥ 22)
-cd ~/my-app
-spex init              # additive — never restructures your code
+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
 ```
 
-`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 — regenerated on each machine, never committed.
+`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.
+
+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.
+
+<img src="docs/readme-board.png" alt="dashboard screenshot">
+
+*SpexCode's own repo on its own board; the sessions top-left are agents building the tool.*
 
-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:
+## Working with agents
+
+This part needs tmux and a logged-in [Claude Code](https://www.anthropic.com/claude-code) or Codex
+on the machine.
 
 ```sh
-spex lint              # the "coverage" warnings are your adoption TODO list
+spex new "make the settings page remember the last tab" --node settings
 ```
 
-### Configure it
+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.
 
-Two optional JSON files at the repo root hold every setting, split by portability — pick the right one and
-that's the whole discipline:
+You supervise from outside — on the board, or with the same commands your agent uses:
 
-- **`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.
+```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
+```
 
-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.
+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.
 
-### Run it
+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/).
 
-Start the backend and the dashboard, then open the board:
+## Measuring behavior: yatsu
+
+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
-spex serve          # the backend (API + sessions), on :8787
-spex dashboard      # the board UI on :5173, proxying /api to the backend
+spex yatsu eval settings --scenario remembers-tab --pass --image proof.png
 ```
 
-Open <http://localhost:5173>.
+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.
 
-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,
-nothing to download.
+<img src="docs/readme-eval.png" alt="eval view screenshot">
 
-Day to day (the commands your agent runs for you — and that you can run yourself):
+*The eval view: scenario readings on the left; the selected reading's expected result, staleness,
+and recorded video evidence in the middle.*
 
-| 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 |
+## What's in the repo
 
-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.
+| 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
 
-## Contributing to SpexCode
+`spex lint` checks the spec↔code graph and is the real gate (the git hook is fast local feedback):
 
-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:
+- **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
 
-```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)
-```
+## Configuration
 
-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`:
+`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.
 
-```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
-```
+## 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.
+
+## 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.
 
 ## License
 

package/README.zh-CN.md

@@ -0,0 +1,170 @@
+<img src="docs/sdd-tuxedo-pooh.png" alt="tuxedo pooh 梗图" width="420">
+
+# SpexCode
+
+把 AI agent 纳入回路的 spec 驱动开发。SpexCode 在你的 git 仓库里维护一棵带版本的 spec 树,把每个
+spec 和它管辖的代码链接起来,并运行一个会话管理器,把 coding agent 派进相互隔离的 worktree。你负责
+review 和 merge;工具负责让意图和实现不分家。(下面所有截图都是这个仓库自己跑在自己看板上的样子。)
+
+[English](./README.md) | 中文 · 文档:[spexcode.net](https://spexcode.net) · License: MIT
+
+快捷入口:[模型](#模型) · [快速开始](#快速开始) · [agent](#和-agent-一起工作) ·
+[yatsu](#测量行为yatsu) · [配置](#配置)
+
+## 模型
+
+一个 spec 节点就是 `.spec/` 下的一个目录,里面有一个 `spec.md`:frontmatter(title、status、
+声明管辖文件的 `code:` 清单)加一段正文,描述系统这一部分当前应该做什么。节点可以嵌套,所以这棵树
+对应你对项目的理解方式,而不是文件布局。正文分两个部分。很短的 **raw source** 写意图,改它需要
+人的明确认可,agent 起草、人拍板的也算;**expanded spec** 是 agent 对这个意图的详细展开,自由
+迭代,但必须始终和 raw source 一致。
+
+<img src="docs/readme-node.png" alt="节点弹窗">
+
+两条规则让这套东西成立:
+
+1. **git 就是数据库。** 没有第二份存储。节点的版本号是碰过它 `spec.md` 的 commit 数,历史视图就是
+   这个文件的 `git log`,每一版通过 `Session:` commit trailer 归属到写它的 agent 会话。也因为这样,
+   spec 正文永远只描述当前意图、原地重写:正文里禁止出现 changelog 标题(linter 强制),历史 git
+   已经记了。
+2. **spec 和代码一起落地。** 一次改动就是一个 commit,同时更新 `spec.md` 和它所解释的代码。代码
+   要是脱开 spec 单独动了,linter 会标出来,
+
+   ```
+   drift: spec-cli/src/board.ts is 1 commit(s) ahead of spec 'board-lean' (v8) — may be stale
+   ```
+
+   一直标到 spec 跟上为止。
+
+## 优化循环
+
+spec、commit、yatsu 读数,这几样合起来是一个循环。spec 是损失函数:定义你要什么,这一半由人拍板。commit 是优化器。
+**yatsu** 是测量子系统,负责评估:量出当前行为离 spec 还有多远,分数的历史照样存在 git 里。
+
+<img src="docs/readme-loop.zh.png" alt="优化循环示意">
+
+它也决定了人平时站在哪:没有人靠盯权重去读神经网络,两次 merge 之间同样不必盯着 agent 的 diff。
+注意力放在 spec 和 eval 读数上;diff 只在 merge 的时候读一次。
+
+## 快速开始
+
+需要 Node ≥ 22 和 git。这一步是普通工具,还不涉及 AI。
+
+```sh
+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。
+
+这些不需要你全部手写。预期的用法是让 agent 完成大部分 spec 写作;`spex guide spec` 会打印它需要的
+确切文件格式。完整的安装过程见文档站的
+[getting started](https://spexcode.net/getting-started/)。
+
+<img src="docs/readme-board.png" alt="看板截图">
+
+*SpexCode 自己的仓库跑在自己的看板上;左上角那些会话就是正在造它的 agent。*
+
+## 和 agent 一起工作
+
+这一步需要 tmux 和本机已登录的 [Claude Code](https://www.anthropic.com/claude-code) 或 Codex。
+
+```sh
+spex new "让设置页记住上次打开的标签" --node settings
+```
+
+会在 `node/settings` 分支的独立 worktree 里启动一个 worker 会话。worker 动代码之前先读管辖 spec,
+做出改动,把 spec 正文改写到和实现一致,把两者一起 commit(hook 自动盖 `Session:` 戳),然后提出
+merge 并停下。worker 不自己 merge。合并留在管理者手里:你按下 merge 时,实际的 git merge 由这个
+会话自己的 agent 执行,冲突落在最懂这份活的人手里。同样的派工在看板网页上就是一个按钮(board 的
+new-session 输入框);命令行形态是 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
+```
+
+相互独立的任务并行跑。每个 worker 隔离在自己的 worktree 里,merge 由 git 序列化,pre-commit 守卫
+拦截对 trunk 的直接提交,所以一切都从可 review 的 node 分支流过。
+
+流程靠机制强制,不靠提示词工程:后端建分支、hook 盖归属戳,其余规则由 materialize 出的契约块承载,
+所以派工提示词只需要写任务本身。这套工作方式的长版本:
+[working with agents](https://spexcode.net/working-with-agents/)。
+
+## 测量行为:yatsu
+
+yatsu 就是[优化循环](#优化循环)里负责测量的那一半。spec 说这部分应该做什么;旁边的 `yatsu.md` 说怎么验。每条
+scenario 就是一段普通描述加一个期望结果。yatsu 自己什么都不跑(没有 DSL,也没有 runner)。agent
+用顺手的方式执行场景:测试文件、真实浏览器,或者干脆手点一遍截个图。把实际结果和期望对比,连证据
+一起把读数记档:
+
+```sh
+spex yatsu eval settings --scenario remembers-tab --pass --image proof.png
+```
+
+读数存在 spec 旁边一个 git 跟踪的 ndjson 里,所以测量和 spec 版本享有同样的归属和历史。修 bug 要求
+成对:先记一条复现 bug 的 fail 读数,修掉,再在同一条 scenario 上记一条 pass。
+
+<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) 社区,感谢佬友们的第一轮讨论。
+
+## 参与开发
+
+[`docs/CONTRIBUTING.md`](docs/CONTRIBUTING.md) 带你从 clone 到第一个合入的改动。
+[`docs/AGENT_GUIDE.md`](docs/AGENT_GUIDE.md) 有节点模型和反身配置系统的完整机制。
+
+## License
+
+[MIT](./LICENSE)。

package/package.json

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

package/spec-cli/src/attach.ts

@@ -0,0 +1,50 @@
+// @@@ session attach - the HUMAN escape hatch into a worker: every session is just a tmux session on the
+// backend's private socket, and the most direct way to see or rescue one is to sit in it. This verb is the
+// sanctioned foreground `tmux attach` — no programmatic exception-handling ambition, the user fixes it by
+// being there. It is deliberately the ONE session verb that does NOT route through the backend
+// ([[remote-client]]'s exception): a terminal cannot be brokered over HTTP, and attaching a tmux CLIENT to
+// the same server is tmux's native multi-client support, not a second actor on the socket. That makes it
+// LOCAL-only by nature — the guards below fail loud (never degrade) when the premise doesn't hold.
+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`'
+
+// 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
+// ladder — flag / worker env / cwd record / fallback) point at this machine? Loopback and any address this
+// host owns count as local; anything else (a tailnet/LAN IP of another box, a hostname we can't claim)
+// fails loud with the reason and the remote-capable alternatives, never a silent local fallback onto a
+// tmux socket that holds no sessions.
+export async function assertLocalBackend(): Promise<void> {
+  const base = await apiBase()
+  let host: string
+  try { host = new URL(base).hostname } catch { host = '' }
+  const mine = new Set(['localhost', '127.0.0.1', '::1', '[::1]'])
+  for (const addrs of Object.values(networkInterfaces())) for (const a of addrs ?? []) mine.add(a.address)
+  if (mine.has(host)) return
+  console.error(`spex session attach: attach is LOCAL-only, and the resolved backend is another machine (${base}).
+The tmux session lives on THAT machine — a terminal can't be attached over HTTP. Either run attach there
+(e.g. over ssh), or ${AGENT_ALTERNATIVES} — those work remotely.`)
+  process.exit(2)
+}
+
+// foreground takeover of the session's real tmux window; returns only via detach (C-b d) or the session
+// ending. Interactive and blocking by design — a caller without a terminal (an agent inside its turn, a
+// pipe) is refused up front and pointed at the remote-capable verbs instead of tmux's bare "not a terminal".
+export async function attachSession(id: string): Promise<never> {
+  if (!process.stdin.isTTY || !process.stdout.isTTY) {
+    console.error(`spex session attach: attach is INTERACTIVE and needs a terminal — it blocks until you detach.
+An agent must not run it inside a turn (it freezes you); ${AGENT_ALTERNATIVES}.`)
+    process.exit(2)
+  }
+  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}\`.`)
+    process.exit(1)
+  }
+  console.log(`attaching to ${id} — detach with C-b d (the session keeps running)`)
+  const r = spawnSync('tmux', ['-u', '-L', TMUX_SOCK, 'attach-session', '-t', id], { stdio: 'inherit' })
+  process.exit(r.status ?? 1)
+}