spexcode 0.2.1 → 0.2.3

package/spec-yatsu/src/scenariofresh.ts

@@ -1,3 +1,4 @@
+import { spawn } from 'node:child_process'
 import { gitA, headSha } from '../../spec-cli/src/git.js'
 import { parseScenarios } from './yatsu.js'
 
@@ -25,49 +26,118 @@ function blockContent(src: string): Map<string, string> {
   return m
 }
 
-// the file's content-versions newest-first, each { hash, blocks }. Skips a version we can't read (git show
-// '') so an unreadable blob never fabricates a remove+re-add diff.
-async function fileVersions(root: string, headPath: string): Promise<{ hash: string; blocks: Map<string, string> }[]> {
-  // --follow + --name-only pairs each commit with the path the file had THERE, so `git show <hash>:<pathAtCommit>`
-  // works across reparents (yatsu.md moves when its node does). `-M` keeps a rename+edit's content.
-  const log = await gitA(['-C', root, '-c', 'core.quotePath=false', 'log', '-M', '--follow', `--format=${RS}%H`, '--name-only', '--', headPath])
-  const out: { hash: string; blocks: Map<string, string> }[] = []
-  for (const rec of log.split(RS)) {
-    const lines = rec.split('\n').map((l) => l.trim()).filter(Boolean)
-    if (!lines.length) continue
-    const hash = lines[0]
-    const pathAt = lines.slice(1).find((l) => l.endsWith('/yatsu.md') || l === 'yatsu.md') ?? headPath
-    const content = await gitA(['-C', root, 'show', `${hash}:${pathAt}`])
-    if (!content) continue
-    out.push({ hash, blocks: blockContent(content) })
+const ZERO = '0'.repeat(40)   // the null OID a delete/add carries on its absent side
+const EMPTY: Map<string, string> = new Map()
+
+// content-addressed: a blob OID -> its canonical per-scenario block map. Git objects are IMMUTABLE, so this
+// memo never needs invalidation and is shared across every root — a per-worktree build reuses the blocks main
+// already parsed, which is what lets a worktree's freshness build stay cheap instead of re-reading everything.
+const blockByOid = new Map<string, Map<string, string>>()
+
+// ONE `git log --raw` walk over all yatsu.md → per head-path version chain [{hash, oid}], newest-first,
+// rename-followed via the `alias` idiom (git.ts buildIndex): the newest sighting of a path IS its head path;
+// an `R` row remaps the older `from` path onto that head. The raw row carries the new blob OID directly, so
+// no per-version path resolution and no `git show`. --full-history is REQUIRED: default pathspec
+// history-simplification prunes commits off HEAD's first-parent chain, but in this repo every spec edit lands
+// via a --no-ff merge of a node branch, so those pruned commits ARE the scenario edits — dropping them would
+// under-report staleness (a stale reading judged fresh). Merge commits emit no raw diff row, so they add no
+// version (exactly as the old `--follow` did).
+async function fileChains(root: string, wanted: Set<string>): Promise<Map<string, { hash: string; oid: string }[]>> {
+  const chains = new Map<string, { hash: string; oid: string }[]>()
+  const alias = new Map<string, string>()
+  const out = await gitA(['-C', root, '-c', 'core.quotePath=false', 'log',
+    '--raw', '--no-abbrev', '--full-history', '-M', `--format=${RS}%H`, '--', '*yatsu.md'])
+  for (const rec of out.split(RS)) {
+    const nl = rec.indexOf('\n')
+    if (nl < 0) continue
+    const hash = rec.slice(0, nl)
+    if (!hash) continue
+    for (const line of rec.slice(nl + 1).split('\n')) {
+      if (line[0] !== ':') continue           // `:<oldmode> <newmode> <oldoid> <newoid> <status>\t<path>[\t<path2>]`
+      const tab = line.indexOf('\t')
+      if (tab < 0) continue
+      const meta = line.slice(1, tab).split(' ')
+      const oid = meta[3], rename = meta[4][0] === 'R' || meta[4][0] === 'C'
+      const paths = line.slice(tab + 1).split('\t')
+      const to = rename ? paths[1] : paths[0]   // the path on the newer side of this commit
+      let head = alias.get(to)
+      if (head === undefined) { head = to; alias.set(to, to) }
+      let arr = chains.get(head); if (!arr) { arr = []; chains.set(head, arr) }
+      arr.push({ hash, oid })
+      if (rename && paths[0] !== to) { alias.set(paths[0], head); alias.delete(to) }   // older history calls it `from`
+    }
   }
-  return out
+  for (const k of [...chains.keys()]) if (!wanted.has(k)) chains.delete(k)   // keep only the head paths asked for
+  return chains
 }
 
-// per-scenario change-commits for one file: walk versions newest->oldest, attribute a commit to every
-// scenario whose block differs from the next-older version (undefined on either side = add/remove = a change).
-async function scenarioCommits(root: string, headPath: string): Promise<Map<string, string[]>> {
-  const versions = await fileVersions(root, headPath)
+// per-scenario change-commits for one file's version chain: newest->oldest, attribute a commit to every
+// scenario whose canonical block differs from the next-older version (undefined either side = add/remove = a
+// change). A ZERO-oid (delete) version is dropped — it carries no readable content, matching the old
+// `git show ''` skip; a pure rename (R100, oid == the older version's oid) diffs to no change for free.
+function scenarioCommits(chain: { hash: string; oid: string }[]): Map<string, string[]> {
   const commits = new Map<string, string[]>()
   const push = (name: string, hash: string) => { const a = commits.get(name); if (a) a.push(hash); else commits.set(name, [hash]) }
-  for (let i = 0; i < versions.length; i++) {
-    const cur = versions[i].blocks
-    const older = versions[i + 1]?.blocks ?? new Map<string, string>()
+  const real = chain.filter((v) => v.oid !== ZERO)
+  for (let i = 0; i < real.length; i++) {
+    const cur = blockByOid.get(real[i].oid) ?? EMPTY
+    const older = i + 1 < real.length ? (blockByOid.get(real[i + 1].oid) ?? EMPTY) : EMPTY
     for (const name of new Set([...cur.keys(), ...older.keys()])) {
-      if (cur.get(name) !== older.get(name)) push(name, versions[i].hash)
+      if (cur.get(name) !== older.get(name)) push(name, real[i].hash)
     }
   }
   return commits
 }
 
+// read MANY blobs in ONE `git cat-file --batch` process (vs one `git show` per blob). Feeds the OIDs on
+// stdin, parses the `<oid> <type> <size>\n<payload>\n` records byte-accurately (size is bytes; blobs are
+// UTF-8). A `<oid> missing` line yields no entry. Env-stripped like git.ts's helpers (a stray GIT_DIR would
+// misroute repo discovery); kept here beside its only caller — a general git-seam primitive if a second
+// caller ever wants one.
+function catFileBatch(root: string, oids: string[]): Promise<Map<string, string>> {
+  const out = new Map<string, string>()
+  if (!oids.length) return Promise.resolve(out)
+  return new Promise((resolve, reject) => {
+    const env = { ...process.env }
+    delete env.GIT_DIR; delete env.GIT_WORK_TREE; delete env.GIT_INDEX_FILE; delete env.GIT_OBJECT_DIRECTORY
+    const p = spawn('git', ['-C', root, 'cat-file', '--batch'], { env })
+    const chunks: Buffer[] = []
+    p.stdout.on('data', (c: Buffer) => chunks.push(c))
+    p.on('error', reject)
+    p.on('close', () => {
+      const buf = Buffer.concat(chunks)
+      let i = 0
+      while (i < buf.length) {
+        const nl = buf.indexOf(0x0a, i)
+        if (nl < 0) break
+        const header = buf.toString('utf8', i, nl)
+        i = nl + 1
+        if (header.endsWith(' missing')) continue   // unknown OID — no payload follows
+        const size = Number(header.slice(header.lastIndexOf(' ') + 1))
+        if (!Number.isFinite(size)) break
+        out.set(header.slice(0, header.indexOf(' ')), buf.toString('utf8', i, i + size))
+        i += size + 1   // payload + its trailing newline
+      }
+      resolve(out)
+    })
+    p.stdin.on('error', () => { /* EPIPE if git exits early; the close handler reports what arrived */ })
+    p.stdin.write(oids.join('\n') + '\n')
+    p.stdin.end()
+  })
+}
+
+// TWO git subprocesses for the whole index (was F logs + V shows): one `--raw` log for the rename-followed
+// chains, one `cat-file --batch` for every distinct blob not already memoized. Then a pure in-memory diff.
 async function build(root: string, yatsuPaths: string[]): Promise<ScenarioIndex> {
-  const idx: ScenarioIndex = new Map()
-  const CONC = 8   // bound the git-show fan-out; the whole index is built once per HEAD then cached
-  for (let i = 0; i < yatsuPaths.length; i += CONC) {
-    const batch = yatsuPaths.slice(i, i + CONC)
-    const done = await Promise.all(batch.map((p) => scenarioCommits(root, p)))
-    batch.forEach((p, j) => idx.set(p, done[j]))
+  const chains = await fileChains(root, new Set(yatsuPaths))
+  const need = new Set<string>()
+  for (const chain of chains.values()) for (const v of chain) if (v.oid !== ZERO && !blockByOid.has(v.oid)) need.add(v.oid)
+  if (need.size) {
+    const blobs = await catFileBatch(root, [...need])
+    for (const [oid, src] of blobs) blockByOid.set(oid, blockContent(src))
   }
+  const idx: ScenarioIndex = new Map()
+  for (const p of yatsuPaths) idx.set(p, scenarioCommits(chains.get(p) ?? []))   // every asked path gets an entry (empty if untracked)
   return idx
 }
 

package/spec-yatsu/src/sidecar.ts

@@ -5,9 +5,14 @@ import { readFileSync, appendFileSync, existsSync } from 'node:fs'
 // on disk with status:'note'; render stays tolerant of them, the CLI no longer mints them.)
 export type Verdict = { status: 'pass' | 'fail'; note?: string }
 
-export type EvidenceKind = 'image' | 'transcript' | 'video'
-// one piece of a reading's evidence: a content-addressed blob (`hash`) tagged by `kind`. `video` is a
-// screenshot with a time axis — the same content-addressed blob, distinguished only by this tag.
+// The evidence-kind taxonomy ([[evidence-kind-taxonomy]]) is a MEDIA/RENDER type — how a blob's bytes are
+// shown — kept ORTHOGONAL to the step-map AXIS (which is derived from the kind, not welded to it): `image`
+// (a still), `transcript` (free-form text), `video` (a screenshot with a time axis), `data` (a structured
+// machine export — a JSON/metrics dump — rendered as a validatable data block, not flattened into scrolling
+// transcript text). A `data` reading is honest about being structured: it can be parsed and checked, and it
+// is derived from CONTENT (isJsonBlob), never from which filing flag was used.
+export type EvidenceKind = 'image' | 'transcript' | 'video' | 'data'
+// one piece of a reading's evidence: a content-addressed blob (`hash`) tagged by `kind`.
 export type Evidence = { hash: string; kind: EvidenceKind }
 
 // A reading's evidence is a LIST of typed entries — N images and/or a video (with its step-timeline) and/or
@@ -41,6 +46,23 @@ export function evidenceOf(r: { evidence?: Evidence[]; blob?: string | null; blo
   return []
 }
 
+// Is this blob STRUCTURED DATA (a machine export — a JSON object/array) rather than free-form transcript
+// text? The `data` evidence kind ([[evidence-kind-taxonomy]]) is derived from CONTENT, never from which
+// filing flag was used: a hyperfine `--export-json`, an API payload, a metrics dump is data, and flattening
+// it into a scrolling transcript loses that it can be structurally validated and rendered as a data block.
+// Sniffed cheaply and self-contained (no deps): a text blob (no NUL) whose trimmed body brackets as an
+// object/array AND parses to one; anything else (plain logs, terminal text) is not data. This is the ONE
+// predicate both the blob MIME sniff (application/json) and the CLI `--result` kind derive from, so the
+// stored kind and the served Content-Type always agree.
+export function isJsonBlob(b: Buffer): boolean {
+  if (!b.length || b.includes(0)) return false           // empty or binary → not JSON text
+  if (b.length > 4_000_000) return false                 // don't parse an unbounded blob just to sniff a type
+  const s = b.toString('utf8').trim()
+  const open = s[0], close = s[s.length - 1]
+  if (!((open === '{' && close === '}') || (open === '[' && close === ']'))) return false
+  try { const v = JSON.parse(s); return v !== null && typeof v === 'object' } catch { return false }
+}
+
 // a RETRACTION is the sanctioned inverse of a filing — itself an appended event, never a deleted line
 // (the sidecar stays append-only; git shows who retracted what, when). `retracts` is the target reading's
 // `ts` within `scenario` (its natural key). Deliberately NO `evaluator` field: an old reader's line filter

package/spec-yatsu/src/timeline.ts

@@ -1,33 +1,53 @@
-// step-timeline — the map from a moment in a video reading's clip to a named step. SpexCode owns only
-// this FORMAT (a tiny data contract any userland emitter satisfies — a Playwright reporter, a WebDriver
-// listener, a computer-use hand narrating as it drives); aligning the emitter's clock to the clip is the
-// emitter's own job. The timeline rides as a second content-addressed blob on the reading, never a new
-// ndjson column beyond the one hash.
+// step-timeline — the map from a POSITION on a piece of evidence's own axis to a named step. SpexCode owns
+// only this FORMAT (a tiny data contract any userland emitter satisfies — a Playwright reporter, a WebDriver
+// listener, a computer-use hand narrating as it drives, a CLI run stamping line numbers); aligning the
+// emitter's positions to the evidence is the emitter's own job. The map rides as a second content-addressed
+// blob on the reading, never a new ndjson column beyond the one hash.
+//
+// The step is anchored to the evidence's OWN axis, tagged by `axis`: `time` (ms, a video), `frame` (a still
+// SEQUENCE by index), `line` (a transcript by line number), `index` (a bare action ordinal). The set is
+// OPEN by convention — an unknown axis is legal and a reader renders its positions as bare numbers. `stepAt`
+// (last step at or before a position) is axis-agnostic and unchanged.
 
-export type TimelineEvent = { tMs: number; step: string; node?: string }
-export type StepTimeline = { v: 1; events: TimelineEvent[] }
+export type TimelineEvent = { at: number; step: string; node?: string }
+export type StepTimeline = { v: 2; axis: string; events: TimelineEvent[] }
 
-const EVENT_KEYS = new Set(['tMs', 'step', 'node'])
+// legacy v1 is the TIME axis with `tMs` as the position — read losslessly, normalized to the axis-tagged
+// shape (`axis: 'time'`, `at: tMs`). Kept forever: an emitter that only knew `{ v: 1, events: [{ tMs }] }`
+// still files a valid video step-map.
+export type LegacyTimelineEvent = { tMs: number; step: string; node?: string }
+export type LegacyStepTimeline = { v: 1; events: LegacyTimelineEvent[] }
 
-// validate LOUD — every violation named, [] when well-formed. The key set is closed (like the yatsu.md
-// scenario schema): a malformed timeline is rejected at filing time, never silently reshaped.
+const V2_EVENT_KEYS = new Set(['at', 'step', 'node'])
+const V1_EVENT_KEYS = new Set(['tMs', 'step', 'node'])
+
+// validate LOUD — every violation named, [] when well-formed. Both schema versions are accepted: v1 (legacy
+// time axis, `tMs`) and v2 (axis-tagged, `at`). The key set is closed per version (like the yatsu.md
+// scenario schema): a malformed timeline is rejected at filing time, never silently reshaped. The `axis`
+// string itself is open — only its ABSENCE is an error, never an unrecognized value.
 export function validateTimeline(raw: unknown): string[] {
-  if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) return ['timeline must be a JSON object { v, events }']
-  const errs: string[] = []
+  if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) return ['timeline must be a JSON object { v, axis, events }']
   const o = raw as Record<string, unknown>
-  for (const k of Object.keys(o)) if (k !== 'v' && k !== 'events') errs.push(`unknown field \`${k}\` (allowed: v, events)`)
-  if (o.v !== 1) errs.push('`v` must be 1')
+  if (o.v !== 1 && o.v !== 2) return ['`v` must be 1 (legacy time axis) or 2 (axis-tagged)']
+  const errs: string[] = []
+  const v2 = o.v === 2
+  const posKey = v2 ? 'at' : 'tMs'
+  const rootKeys = v2 ? new Set(['v', 'axis', 'events']) : new Set(['v', 'events'])
+  const evKeys = v2 ? V2_EVENT_KEYS : V1_EVENT_KEYS
+  for (const k of Object.keys(o)) if (!rootKeys.has(k)) errs.push(`unknown field \`${k}\` (allowed: ${[...rootKeys].join(', ')})`)
+  if (v2 && (typeof o.axis !== 'string' || !o.axis.trim())) errs.push('`axis` must be a non-empty string (e.g. time, frame, line, index)')
   if (!Array.isArray(o.events)) { errs.push('`events` must be an array'); return errs }
   let prev = -Infinity
   o.events.forEach((e, i) => {
     if (typeof e !== 'object' || e === null || Array.isArray(e)) { errs.push(`events[${i}] must be an object`); return }
     const ev = e as Record<string, unknown>
-    for (const k of Object.keys(ev)) if (!EVENT_KEYS.has(k)) errs.push(`events[${i}]: unknown field \`${k}\` (allowed: tMs, step, node)`)
-    if (typeof ev.tMs !== 'number' || !Number.isFinite(ev.tMs) || ev.tMs < 0) {
-      errs.push(`events[${i}].tMs must be a finite number ≥ 0`)
+    for (const k of Object.keys(ev)) if (!evKeys.has(k)) errs.push(`events[${i}]: unknown field \`${k}\` (allowed: ${[...evKeys].join(', ')})`)
+    const pos = ev[posKey]
+    if (typeof pos !== 'number' || !Number.isFinite(pos) || pos < 0) {
+      errs.push(`events[${i}].${posKey} must be a finite number ≥ 0`)
     } else {
-      if (ev.tMs < prev) errs.push(`events[${i}].tMs is out of order (the list is ordered by time)`)
-      prev = ev.tMs
+      if (pos < prev) errs.push(`events[${i}].${posKey} is out of order (the list is ordered by position)`)
+      prev = pos
     }
     if (typeof ev.step !== 'string' || !ev.step.trim()) errs.push(`events[${i}].step must be a non-empty string`)
     if (ev.node !== undefined && (typeof ev.node !== 'string' || !ev.node.trim())) errs.push(`events[${i}].node must be a non-empty string when present`)
@@ -35,12 +55,22 @@ export function validateTimeline(raw: unknown): string[] {
   return errs
 }
 
-// the whole of "which step is this moment": the last event at or before T; null before the first event
-// (a plain player moment, no step to name — graceful, never an error).
-export function stepAt(events: TimelineEvent[], tMs: number): TimelineEvent | null {
+// normalize any VALID timeline (v1 or v2) to the axis-tagged shape every reader uses: v1 IS the time axis
+// with `tMs` as the position. Call only on input `validateTimeline` accepted. This is the whole of the
+// lossless back-compat: an old v1 blob and a new `{ v: 2, axis: 'time' }` render identically.
+export function normalizeTimeline(raw: unknown): { axis: string; events: TimelineEvent[] } {
+  const o = (raw ?? {}) as Record<string, any>
+  const events: any[] = Array.isArray(o.events) ? o.events : []
+  if (o.v === 1) return { axis: 'time', events: events.map((e) => ({ at: e.tMs, step: e.step, ...(e.node ? { node: e.node } : {}) })) }
+  return { axis: typeof o.axis === 'string' ? o.axis : 'time', events: events.map((e) => ({ at: e.at, step: e.step, ...(e.node ? { node: e.node } : {}) })) }
+}
+
+// the whole of "which step is this position": the last event at or before `pos`; null before the first event
+// (a plain moment, no step to name — graceful, never an error). Axis-agnostic — `pos` is on the events' axis.
+export function stepAt(events: TimelineEvent[], pos: number): TimelineEvent | null {
   let hit: TimelineEvent | null = null
   for (const e of events) {
-    if (e.tMs <= tMs) hit = e
+    if (e.at <= pos) hit = e
     else break
   }
   return hit

package/README.zh-CN.md

@@ -1,135 +0,0 @@
-<img src="docs/sdd-tuxedo-pooh.png" alt="写代码 vs. 维护一份活的、可执行的规格文档" width="420">
-
-[English](./README.md) | 中文
-
-> Spec 驱动开发通常死于两种方式:spec 和代码脱节,或者膨胀成一堆过时的仪式文档。SpexCode 让每个
-> spec 保持简短、保持当前态:原地重写,由 git 记版本,不做累积式的 changelog。
-
-**SpexCode** 是一个 spec 驱动、用自己开发自己的开发工具。项目的每个部分都是一个带版本的
-*spec 节点*,即一个 `.spec/**/spec.md`,正文描述这个部分当前的意图。git 就是数据库:节点的版本号
-是它的内容 commit 数,"drift" 指被管辖的代码走到了 spec 前面。`spex` CLI 和实时看板直接从 git
-读取这一切,没有第二份存储。
-
-- **[使用 SpexCode](#使用-spexcode)**:安装 `spex` CLI,通过你的 coding agent 治理*你自己的*项目。
-- **[参与开发](#参与开发)**:在本仓库里改进工具本身。
-- **[Working with agents →](https://spexcode.net/working-with-agents/)**:文档站上更完整的介绍。
-
----
-
-## 使用 SpexCode
-
-SpexCode 只需要设置一次(`npm i -g spexcode`,然后在你的仓库里 `spex init`)。之后的主要用法是和
-你的 coding agent 对话:用自然语言说你要什么(*"给鉴权流程加一个 spec 节点""把这个包的 spec
-提取出来""派一个 worker 去实现 Y"*),agent 替你执行 `spex` CLI,你在看板上盯进度。下面的手动
-CLI 是底座,agent 才是日常界面。
-
-这套之所以成立,是因为新启动的 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/)** 从头到尾走一遍安装。
-
-> **抛开 agent,它也是一套普通工具。** 核心部分单独用也成立:git 记版本的 spec 文件,`spex lint`
-> 检查,只读看板展示。不含 AI,除了 Node 和 git 什么都不用跑。vibe coding 的玩法建立在这层之上,
-> 不是替代它。
-
-> **环境要求。** 核心:**Node ≥ 22** 和 **git**。要通过 agent 驱动(或者往节点上派 worker),
-> 还需要 **tmux** 和 PATH 里已登录的 **Claude Code 或 Codex**。这些 agent 会在你的机器上执行
-> 命令,对外暴露后端之前请先读 [`SECURITY.md`](./docs/SECURITY.md)。
-
-### 安装
-
-装一次发布版 CLI,然后在任何项目里接入:
-
-```sh
-npm i -g spexcode      # 安装 spex 命令(需要 Node ≥ 22)
-cd ~/my-app
-spex init              # 纯增量,不会动你的代码结构
-```
-
-`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` 指向真实源码目录,再检查一遍:
-
-```sh
-spex lint              # coverage 警告就是你的接入 TODO 清单
-```
-
-### 配置
-
-仓库根目录两个可选的 JSON 文件承载全部设置,按可移植性分开:
-
-- **`spexcode.json`**:提交进仓库,可移植。布局、看板标识(`title` + `icon`)、lint 预算、
-  launcher 的**名字**。对整个项目成立的事实。
-- **`spexcode.local.json`**:gitignore,单机。launcher 命令的绝对路径、证书和密钥路径、私有覆盖
-  开关(`private: true`,让 `spex materialize` 在被跟踪的文件里不留任何痕迹,ignore 写进本地
-  git exclude 而不是提交的 `.gitignore`,适合你参与但不拥有的仓库)。只对这台机器成立的事实。
-
-没有 `spex config set`,你(或你的 agent)直接编辑文件。每个字段的含义、该放哪个文件,
-**`spex guide config`** 是权威手册。
-
-### 运行
-
-启动后端和看板,打开页面:
-
-```sh
-spex serve          # 后端(API + sessions),:8787
-spex dashboard      # 看板 UI,:5173,/api 代理到后端
-```
-
-打开 <http://localhost:5173>。
-
-两个端口都是参数(`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 替你跑,你也可以自己跑):
-
-| 命令 | 作用 |
-| --- | --- |
-| `spex lint` | 检查 spec↔code 图:coverage、drift、living 规则 |
-| `spex watch` | 实时输出 session / 看板的状态变化 |
-| `spex guide` | 打印完整工作流,以及 `spec.md` / `yatsu.md` / `config` 手册 |
-| `spex board` | 以 JSON 输出当前看板状态 |
-
----
-
-## 参与开发
-
-这个仓库就是 SpexCode 的源码,而且它 dogfood 自己:工具的每个改动都以 spec 节点的形式合入
-`main`。搭一个开发环境:
-
-```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 戳)
-```
-
-开发循环直接跑源码,带热重载(开发用 `npm run web`,区别于安装用户的 `spex dashboard`):
-
-```sh
-npm run api            # 后端 :8787,spec-cli/src 改动即热重载
-npm run web            # Vite 起看板(HMR),/api 代理到 :8787
-```
-
----
-
-## 致谢
-
-SpexCode 的首次公开介绍发在 [LINUX DO](https://linux.do),感谢佬友们的第一轮讨论和反馈。
-
-## License
-
-[MIT](./LICENSE)。