spexcode 0.2.1 → 0.2.3

package/README.md

@@ -1,149 +1,204 @@
-<img src="docs/sdd-tuxedo-pooh.png" alt="Writing code vs. authoring a living, executable specification artifact" width="420">
+<div align="center">
 
-English | [中文](./README.zh-CN.md)
+<img src="docs/banner.png" alt="SpexCode" width="720">
 
-> 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.
+<p>
+  <a href="https://www.npmjs.com/package/spexcode"><img alt="npm" src="https://img.shields.io/npm/v/spexcode?logo=npm&logoColor=white&color=cb3837"></a>
+  <img alt="license: MIT" src="https://img.shields.io/badge/license-MIT-2f81f7">
+  <img alt="node &ge; 22" src="https://img.shields.io/badge/node-%E2%89%A5%2022-3fb950?logo=nodedotjs&logoColor=white">
+  <a href="https://spexcode.net"><img alt="docs" src="https://img.shields.io/badge/docs-spexcode.net-8957e5"></a>
+</p>
 
-**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.
+</div>
 
-- **[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.
+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.)
 
----
+[![This repo's spec tree, grown from its own git history](docs/spec-tree-hero.gif)](https://spexcode.net/assets/spec-tree-growth.mp4)
 
-## Using SpexCode
+<sub>▶ This repo's own spec tree, replayed from its git history — 160 spec nodes growing over three weeks. Click for the [full video](https://spexcode.net/assets/spec-tree-growth.mp4).</sub>
 
-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.
+English | [中文](./docs/README.zh-CN.md) · Docs: [spexcode.net](https://spexcode.net) · License: MIT
 
-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"*.
+Quick links: [the model](#the-model) · [quick start](#quick-start) ·
+[agents](#working-with-agents) · [yatsu](#measuring-behavior-yatsu) · [config](#configuration)
 
-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.
+## The model
 
-> **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.
+<div align="center"><img src="docs/sdd-tuxedo-pooh.png" alt="spec-driven development meme" width="260"></div>
 
-> **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.
+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.
 
-### Set it up
+<img src="docs/readme-node.png" alt="spec node popup">
 
-Install the published CLI once, then adopt it in any project:
+Two rules make this workable:
 
-```sh
-npm i -g spexcode      # installs the `spex` command (needs Node ≥ 22)
-cd ~/my-app
-spex init              # additive — never restructures your code
-```
+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,
+
+   ```
+   drift: spec-cli/src/board.ts is 1 commit(s) ahead of spec 'board-lean' (v8) — 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
+score's history lives in git like everything else.
 
-`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.
+<img src="docs/readme-loop.png" alt="the spec/code optimization loop">
 
-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:
+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
-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:
 
-Two optional JSON files at the repo root hold every setting, split by portability:
+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.
 
-- **`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.
+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.
 
-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.
+<img src="docs/readme-board.png" alt="dashboard screenshot">
 
-### Run it
+*SpexCode's own repo on its own board; the sessions top-left are agents building the tool.*
 
-Start the backend and the dashboard, then open the board:
+## 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 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 — 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:
+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.
+
+## 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.
 
-## Credits
+## Credit
 
-SpexCode was first introduced publicly on [LINUX DO](https://linux.do) — thanks to the community
-there for the first round of discussion and feedback.
+First introduced on the [LINUX DO](https://linux.do) community — thanks to everyone there for the first round of discussion.
 
 ## License
 

package/package.json

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

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)
+}