@stofone/dsh-agent-roster 0.9.2 → 0.10.1

package/CHANGELOG.md

@@ -4,6 +4,74 @@
 
 ## [Unreleased]
 
+## [0.10.1] - 2026-11-03
+
+### Docs
+
+- The Chinese README said `migrate` was "not implemented", listed one example library where there are
+  two, and had a file tree from before `roles/`, `roster.v2` and `compiled.v1` existed — docs that
+  describe last week's format read as current, which is worse than no docs.
+- Both READMEs now carry the same two sections: one-command v1→v2 migration (including why role names
+  are prefixed and why a colliding captain gets `-captain`), and feeding a failed round back into the
+  plan with `compile --run`.
+
+## [0.10.0] - 2026-11-03
+
+### Roles, rosters and compiled artifacts (v2)
+
+- **A roster is no longer one document doing four jobs.** Personas move to `roles/<dir>/AGENT.md`
+  (frontmatter for parameters, markdown body for the persona, optional `parts/`), assemblies stay in
+  `rosters/<id>/roster.yaml` (members are `name@x.y.z` references, the captain gets its own section),
+  and everything consumers read is a self-contained `dist/<id>-<ver>.json`.
+- **Assembly is part of the format**: `executionPrompt = join("\n\n", [body, ...parts, ...append])`,
+  implemented once in `lib/frontmatter.js#assemblePrompt`. The compiled artifact records character
+  count, block list and SHA-256 per prompt.
+- **The discriminator decides the version** — `dsh-agent-roster/role@1`, `/roster@2`, `/compiled@1`.
+  v1 is frozen; two formats never share a directory.
+- **Identity comes from the document**, so the "directory name must equal `id`" rule is replaced by a
+  stronger one: role names are unique within a library, and duplicate `name` is an error.
+- **`orchestration` is compiled as a declaration.** Stages and gates are validated (a gate's `after`
+  must name real stages, `by` must name a real member), the artifact marks
+  `status: "declaration"`, and every non-executed field is listed in `declarations[]`.
+- **New CLI**: `dsh-agent-roster compile --roster <dir> [--roles <dir>] [--write] [--json]`.
+- **Schema alignment tests**: `test/v2-schema.test.js` pins field sets, enums, limits and regexes to
+  `lib/format-v2.js`, and `test/examples-orchestration.test.js` compiles `examples-orchestration/` and fails if `dist/` drifts.
+- Design contract: [`docs/roster-v2.md`](./docs/roster-v2.md).
+- **Gates must be runnable.** Every gate carries at least one `verify` entry (`command`, `expectExit`);
+  a gate without one is rejected as `gate-unverifiable`, because a gate whose only criterion is a
+  sentence is judged by the person signing it.
+- **A construction plan, not an execution.** `compile` now also writes
+  `dist/<id>-<ver>.tasks.json` (`plan@1`): stages and gates flattened into cards with dependencies,
+  `executor: "captain"`, and `loop.onGateFailure` naming where a failed gate goes back to and how many
+  rounds it may take. The plugin never calls `agent_teams_create_task` — the plan is a drawing.
+
+### Migrating what already existed
+
+- **`migrate --dir <library> [--write]`** rewrites a v1 library in place: each member's
+  `systemPrompt` becomes the body of `roles/<roster>-<member>/AGENT.md`, the member turns into a
+  reference, the captain becomes a role file of its own, `capabilities.yaml` moves next to the
+  assembly, every roster is compiled into `dist/`, and the old flat directory is removed.
+  Without `--write` it only reports what it would do — it is the one command that deletes things.
+- **Role names carry the roster id prefix.** v2 requires role names to be unique per library; a
+  library whose 21 rosters all call their captain `lead` cannot have 21 files named `lead`. When the
+  captain collides with a member it gets a `-captain` suffix instead of being merged — they are two
+  personas and merging them would silently drop one.
+- **This repository's own archives were migrated**: `examples/` (2 rosters, 5 members, one captain)
+  and `orgs/agent-roster-collective/` (21 rosters, 63 members) now live as `roles/ + rosters/ + dist/`.
+- `maintainers` accepts handles (`STofone`) rather than the lowercase id pattern — migration must not
+  rename a person to satisfy a validator.
+- **Both layouts are readable**: the scanner, the document route and the writer accept
+  `<root>/<id>/roster.*` and `<root>/rosters/<id>/roster.*`, so a v1 library keeps working while it is
+  being migrated, and the panel shows v2 rosters through the same `rosterViewOf` shape.
+
+### An execution record feeds the next compile
+
+- **`run@1`** (`lib/run.js`): rounds → tasks → findings/commands, with unknown fields rejected.
+- **`compile --run <file>`** merges the previous round's failures into the retry card's description
+  (and stamps `round` on the plan). A failure that only lives on a red card never reaches the next
+  compile — which is how a gate becomes decoration.
+- The record is written by the captain session, not by the plugin: task ids belong to the team.
+
 ## [0.9.2] - 2026-11-03
 
 ### The member list is a table

package/README.md

@@ -84,7 +84,7 @@ captain:                     # optional: what the captain (the session that crea
 
 JSON works too (`roster.json`); YAML and JSON are probed in the order `roster.yaml`, `roster.yml`, `roster.json`. Exactly one file per directory — a second one is reported, never silently picked.
 
-This package ships two example libraries in [`examples/`](./examples). `rosterDirs` is empty by
+This package ships two example libraries: [`examples/`](./examples) (v2, migrated from the v1 archives this repo grew up with) and [`examples-orchestration/`](./examples-orchestration) (v2, hand-written to show gates and a construction plan). `rosterDirs` is empty by
 default, meaning the global library above, which is empty in a fresh install — so the panel shows
 "0 rosters" until you create one in the UI. To look at the examples instead, point the CLI at them:
 
@@ -221,6 +221,79 @@ This file creates nothing. It does not write `team.json`, does not create member
 node bin/cli.mjs validate --dir orgs/agent-roster-collective
 ```
 
+## Roles, rosters and compiled artifacts (v2)
+
+v1 keeps everything in one `roster.yaml`: the persona sits in a YAML block scalar, the assembly protocol lives in plugin code, the captain is written twice, and identity comes from the directory name. v2 splits that into three layers, one authority each:
+
+```text
+roles/<any-dir>/AGENT.md     role: frontmatter is parameters, body is the persona, parts/ optional
+rosters/<id>/roster.yaml     assembly: members are references, the captain has its own section
+dist/<id>-<ver>.json         compiled: self-contained, hashable, the only thing consumers read
+```
+
+The discriminator decides the version — `dsh-agent-roster/role@1`, `dsh-agent-roster/roster@2`, `dsh-agent-roster/compiled@1`. Two formats never share a directory: v1 is frozen, and `roster migrate` (not yet built) rewrites it in place.
+
+Assembly is written into the format rather than hidden in code:
+
+```text
+executionPrompt = join("\n\n", [body, ...parts, ...member.append])
+```
+
+`assemblePrompt()` in `lib/frontmatter.js` is the only implementation, and the compiled artifact records the character count, the block list and a SHA-256 for every prompt, so "which text did this member actually get" is answerable without re-reading the sources.
+
+A gate must be runnable, not self-certified: every gate carries at least one `verify` entry (`command` + `expectExit`), and a gate without one is rejected at validation time (`gate-unverifiable`). `requires` stays, but only as prose for the human reading the verdict.
+
+`compile` also emits the construction plan — `dist/<id>-<ver>.tasks.json`:
+
+```json
+{ "kind": "dsh-agent-roster/plan@1", "executor": "captain",
+  "tasks": [ { "id": "build", "kind": "stage", "member": "fixer", "dependencies": [] },
+             { "id": "audit", "kind": "stage", "member": "reviewer", "dependencies": ["build"] },
+             { "id": "tests-pass", "kind": "gate", "member": "reviewer", "dependencies": ["audit"] } ],
+  "loop": { "onGateFailure": { "retry": "build", "maxRounds": 1 } } }
+```
+
+`executor: "captain"` is the whole point: the plugin never calls `agent_teams_create_task`, because writing team state belongs to the captain session. The plan is a drawing the captain builds from, not the plugin building for it.
+
+The example library in [`examples-orchestration/`](./examples-orchestration/) compiles end to end:
+
+```bash
+node bin/cli.mjs compile --roster examples-orchestration/rosters/core-review --write
+node bin/cli.mjs compile --roster examples-orchestration/rosters/core-review --json
+```
+
+`orchestration` is part of the format but is compiled with `status: "declaration"`: stages and gates are validated (a gate's `after` must name real stages, `by` must name a real member), yet nothing executes them. Declaring a field is not the same as proving it runs, so the artifact says which is which in `declarations[]`. The full contract — field ownership, assembly semantics, identity and uniqueness, migration rules — is in [`docs/roster-v2.md`](./docs/roster-v2.md); the schemas are [`schema/role.v1.schema.json`](./schema/role.v1.schema.json), [`schema/roster.v2.schema.json`](./schema/roster.v2.schema.json) and [`schema/compiled.v1.schema.json`](./schema/compiled.v1.schema.json).
+
+### From v1 to v2 in one command
+
+```bash
+node bin/cli.mjs migrate --dir examples            # 只出计划：要写哪些文件、能不能编译
+node bin/cli.mjs migrate --dir examples --write    # 原地重写：roles/ + rosters/ + dist/，删掉旧目录
+```
+
+Migration keeps personas verbatim: a member's `systemPrompt` becomes the body of
+`roles/<roster>-<member>/AGENT.md`, and the member turns into a reference. The captain stops being a
+loose field and becomes a role file of its own — `<roster>-<captain>-captain` when its name collides
+with a member, because those are two different personas and silently merging them would lose one.
+
+Role names carry the roster id prefix because v2 requires role names to be **unique per library**,
+and a library whose 21 rosters all call their captain `lead` cannot have 21 files with the same name.
+
+### Feeding a failed round back into the plan
+
+`compile --run <file>` reads an execution record (`run@1`) and appends the previous round's failures
+to the retry card's description:
+
+```bash
+node bin/cli.mjs compile --roster examples-orchestration/rosters/core-review \
+  --run examples-orchestration/dist/core-review-1.0.0.run.json
+```
+
+The record is written by whoever executes the plan (the captain session), not by the plugin: a task
+id belongs to the team, and the plugin never writes team state. What it does own is the merge — a
+failure that only exists on a red card never reaches the next compile, which is exactly how a gate
+turns into decoration.
+
 ## Tools
 
 | Tool | Purpose |
@@ -377,10 +450,12 @@ lib/              format, parse, validate, registry, bridge, verify, render, lib
                   config-view, json, http, write, service, teams-state, tools
 client.js         client plugin: sidebar entry, main panel (rosters/teams/health), settings section
 locale/           panel + listing dictionaries (en/zh)
-schema/           roster / capabilities / organization / registry v1 schemas (editor completion; kept aligned by tests)
-bin/cli.mjs       validate/list/version for CI
+schema/           roster v1 / role v1 / roster v2 / compiled v1 / capabilities / organization / registry
+                  schemas (editor completion; kept aligned by tests)
+bin/cli.mjs       validate/list/compile/migrate/registry for CI
 scripts/          host-smoke.mjs, client-smoke.mjs, check-locale.mjs (dev only, not shipped)
-examples/         two example libraries
+examples/         a v2 library migrated from the v1 archives
+examples-orchestration/  a v2 library with orchestration, gates and a construction plan
 orgs/             a worked example library with its own organization.yaml (21 rosters)
 test/             unit tests
 ```
@@ -389,7 +464,7 @@ test/             unit tests
 
 Verified on this machine:
 
-- `npm test` — 240/240 passing (format, parse, validate, registry, paths, bridge, verify buckets, digests and provenance, roster diff, capability requirements and the capability gate, library organization, registry schema, lossless JSON, write plan/apply, all routes, panel snapshot and hints, dictionary consistency, tool contracts, client loader contract, library snapshot, config view, package manifest, declared fields and captain block, schema/constant alignment, remote registry and one-click install).
+- `npm test` — 286/286 passing (format, parse, validate, registry, paths, bridge, verify buckets, digests and provenance, roster diff, capability requirements and the capability gate, library organization, registry schema, lossless JSON, write plan/apply, all routes, panel snapshot and hints, dictionary consistency, tool contracts, client loader contract, library snapshot, config view, package manifest, declared fields and captain block, schema/constant alignment, the v2 role/roster/compiled layers and their schema alignment, v1→v2 migration, run records feeding the plan, remote registry and one-click install).
 - `npm run smoke` — `apply()` registers all six tools through a real `defineTool` from a DSH bundle; `roster_list` / `roster_show` / `roster_create` / `roster_verify` / `roster_diff` execute, every output survives `lossless` checks, `path` overrides are honored, effect disposal runs cleanly. The same command then loads `client.js` against a stubbed module table and asserts the three slot registrations, style injection and effect disposal.
 - CLI: `validate --dir examples` returns exit 0 over both example libraries.
 - Installed into a real profile with the plugin manager (`plugin_manager install_bundle` against this directory → `link:` dependency + bundle entry); the profile re-reads the linked files on restart.

package/README.zh.md

@@ -82,7 +82,7 @@ captain:                     # 可选：记录队长（＝创建团队的那个
 
 JSON 也可以（`roster.json`）。同一目录下按 `roster.yaml` → `roster.yml` → `roster.json` 顺序探测，**只认一份**；出现第二份会报诊断，绝不静默挑一份。
 
-本包自带两份示例档案库（[`examples/`](./examples)）。`rosterDirs` 默认留空，也就是上面那座全局库；
+本包自带两份示例档案库：[`examples/`](./examples)（v2，由本仓历史档案迁移而来）与 [`examples-orchestration/`](./examples-orchestration)（v2，手写，用来演示门与施工图）。`rosterDirs` 默认留空，也就是上面那座全局库；
 新装时它是空的，所以面板一开始显示「0 份档案」——在面板里新建一份即可（目录会自动创建）。想先看示例库：
 
 ```bash
@@ -217,6 +217,71 @@ rosters:
 node bin/cli.mjs validate --dir orgs/agent-roster-collective
 ```
 
+## 角色 / 组装 / 编译产物（v2）
+
+v1 把一切都塞进一份 `roster.yaml`：人设住在 YAML 块标量里，拼装协议藏在插件代码里，队长写两遍，身份靠目录名。v2 把它拆成三层，每层只有一个权威：
+
+```text
+roles/<任意目录>/AGENT.md     角色：frontmatter 是参数，正文是人设，parts/ 可选
+rosters/<id>/roster.yaml      组装：成员是引用，队长独立成段
+dist/<id>-<ver>.json          编译产物：自包含、可哈希，消费者只看它
+```
+
+判别键决定版本——`dsh-agent-roster/role@1`、`dsh-agent-roster/roster@2`、`dsh-agent-roster/compiled@1`。同一目录不允许两种格式共存：v1 冻结，`migrate` 负责原地重写。
+
+拼装写进格式，而不是藏在代码里：
+
+```text
+executionPrompt = join("\n\n", [body, ...parts, ...member.append])
+```
+
+`lib/frontmatter.js` 的 `assemblePrompt()` 是唯一实现；编译产物为每份人设记录字符数、块清单与 SHA-256，所以「这名成员到底拿到了哪段文字」不必回头读源文件就能回答。
+
+门必须能被跑，而不是自己给自己盖章：每个门至少带一条 `verify`（`command` + `expectExit`），没有判据的门在校验阶段就被拒（`gate-unverifiable`）。`requires` 保留，但只是给读结论的人看的说明。
+
+`compile` 还会产出施工图 `dist/<id>-<ver>.tasks.json`：
+
+```json
+{ "kind": "dsh-agent-roster/plan@1", "executor": "captain",
+  "tasks": [ { "id": "build", "kind": "stage", "member": "fixer", "dependencies": [] },
+             { "id": "audit", "kind": "stage", "member": "reviewer", "dependencies": ["build"] },
+             { "id": "tests-pass", "kind": "gate", "member": "reviewer", "dependencies": ["audit"] } ],
+  "loop": { "onGateFailure": { "retry": "build", "maxRounds": 1 } } }
+```
+
+`executor: "captain"` 就是关键：插件从不调用 `agent_teams_create_task`，因为写团队状态的能力属于队长会话。施工图是给队长照着建的图，不是插件替队长建。
+
+[`examples-orchestration/`](./examples-orchestration/) 里的示例库可端到端编译：
+
+```bash
+node bin/cli.mjs compile --roster examples-orchestration/rosters/core-review --write
+node bin/cli.mjs compile --roster examples-orchestration/rosters/core-review --json
+```
+
+`orchestration` 是格式的一部分，但编译时标 `status: "declaration"`：阶段与门会被校验（门的 `after` 必须指向真实阶段，`by` 必须指向真实成员），但没有任何东西执行它。能声明不等于已被证明会运行，所以产物在 `declarations[]` 里逐条说明谁属于哪一类。完整契约——字段归宿、拼装语义、身份与唯一性、迁移规则——见 [`docs/roster-v2.md`](./docs/roster-v2.md)；schema 见 [`schema/role.v1.schema.json`](./schema/role.v1.schema.json)、[`schema/roster.v2.schema.json`](./schema/roster.v2.schema.json)、[`schema/compiled.v1.schema.json`](./schema/compiled.v1.schema.json)。
+
+### 从 v1 到 v2，一条命令
+
+```bash
+node bin/cli.mjs migrate --dir examples            # 只出计划：要写哪些文件、能不能编译
+node bin/cli.mjs migrate --dir examples --write    # 原地重写：roles/ + rosters/ + dist/，删掉旧目录
+```
+
+迁移逐字保留人设：成员的 `systemPrompt` 原文成为 `roles/<档案>-<成员>/AGENT.md` 的正文，成员本身变成引用。队长不再是一个散字段，而是自己的角色文件——与成员同名时得到 `-captain` 后缀，因为那是两份人设，悄悄合并会丢掉一份。
+
+角色名带档案 id 前缀，是因为 v2 要求同库角色名唯一：一座库里 21 套组装都叫自己的队长 `lead`，不可能有 21 个同名文件。
+
+### 把失败的一轮喂回施工图
+
+`compile --run <文件>` 读执行回执（`run@1`），把上一轮的失败并进重试卡的 description：
+
+```bash
+node bin/cli.mjs compile --roster examples-orchestration/rosters/core-review \
+  --run examples-orchestration/dist/core-review-1.0.0.run.json
+```
+
+回执由执行施工图的队长会话写，不由插件写：任务 id 属于团队，插件从不写团队状态。插件负责的是合并——只活在红卡上的失败，下一次编译就消失了，门也就变成了装饰。
+
 ## 工具
 
 | 工具 | 作用 |
@@ -362,11 +427,13 @@ lib/              format / parse / validate / registry / bridge / verify / rende
                   config-view / json / http / write / service / teams-state / tools
 client.js         客户端半边：左侧栏图标 + 主面板（档案/团队/体检）+ 设置页小节
 locale/           面板与列表词典（en/zh）
-schema/           roster / capabilities / organization / registry v1 schema（编辑器补全用，与校验器由测试对齐）
-bin/cli.mjs       validate / list / version，给 CI 用
+schema/           roster v1 / role v1 / roster v2 / compiled v1 / capabilities / organization / registry
+                  schema（编辑器补全用，与校验器由测试对齐）
+bin/cli.mjs       validate / list / compile / migrate / registry，给 CI 用
 scripts/          host-smoke.mjs、client-smoke.mjs、check-locale.mjs（开发用，不随包发布）
-examples/         两座示例档案库
-orgs/             带 organization.yaml 的示例库（21 套档案）
+examples/         由历史 v1 档案迁移来的 v2 库（roles/ + rosters/ + dist/）
+examples-orchestration/  手写的 v2 库：编排、门与施工图
+orgs/             带 organization.yaml 的示例库（21 套 v2 档案）
 test/             单测
 ```
 
@@ -374,7 +441,7 @@ test/             单测
 
 本机已验证：
 
-- `npm test` —— 240/240 通过（格式、解析、校验、扫描、路径、桥接、核对四桶、摘要与溯源、档案差异、能力要求与能力闸门、档案库组织、索引 schema、无损 JSON、写入计划与执行、六条路由、快照与提示、两本词典一致、工具契约、客户端加载器契约、包清单、配置视图、样式 token 约束、声明层字段与队长段、schema 与常量对齐）。
+- `npm test` —— 286/286 通过（格式、解析、校验、扫描、路径、桥接、核对四桶、摘要与溯源、档案差异、能力要求与能力闸门、档案库组织、索引 schema、无损 JSON、写入计划与执行、六条路由、快照与提示、两本词典一致、工具契约、客户端加载器契约、包清单、配置视图、样式 token 约束、声明层字段与队长段、schema 与常量对齐、v2 角色/组装/编译三层及其 schema 对齐、v1→v2 迁移、执行回执并入施工图）。
 - `npm run smoke` —— 用真实 DSH bundle 的 `defineTool` 注册六个工具，逐个调用：输出全部通过无损校验、`path` 覆盖生效、释放干净；同一条命令随后用桩模块表加载 `client.js`，断言三处槽位注册、样式只注入一次、effect 可回收。
 - CLI：`validate --dir examples` 对两座示例库退出码 0。
 - 用插件管理器真的装进了本机 profile（`plugin_manager install_bundle` 指向本仓库 → `link:` 依赖 + bundle 条目），重启后按链接读取本仓库文件。

package/bin/cli.mjs

@@ -11,8 +11,10 @@
  *   dsh-agent-roster registry validate --file index/registry.json [--json]
  *   dsh-agent-roster registry fetch    --file index/registry.json [--local-only]
  *   dsh-agent-roster registry sync     --file index/registry.json [--write]
+ *   dsh-agent-roster compile --roster rosters/money-lab [--roles roles] [--run run.json] [--write] [--json]
+ *   dsh-agent-roster migrate --dir examples [--write] [--json]
  */
-import { readFileSync, writeFileSync } from "node:fs";
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import nodePath from "node:path";
 
 import { resolveDirSpec } from "../lib/home.js";
@@ -20,6 +22,10 @@ import { scanRosterLibrary } from "../lib/registry.js";
 import { renderRosterList } from "../lib/render.js";
 import { REGISTRY_KIND } from "../lib/format.js";
 import { fetchCollection, readRegistryFile } from "../lib/remote.js";
+import { compileRosterAt } from "../lib/compile2.js";
+import { migrateLibrary } from "../lib/migrate.js";
+import { compilePlan } from "../lib/plan.js";
+import { mergeRunIntoPlan, validateRun } from "../lib/run.js";
 
 const pkg = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
 
@@ -29,6 +35,8 @@ const USAGE = `用法：
   dsh-agent-roster registry validate --file <路径>   校验公共索引（registry）
   dsh-agent-roster registry fetch --file <路径>      逐条确认 collection 真的能取到
   dsh-agent-roster registry sync --file <路径>       按仓库实际内容重算 roster 列表
+  dsh-agent-roster compile --roster <目录>            把 v2 组装编译成自包含产物（不写盘）
+  dsh-agent-roster migrate --dir <目录>               把 v1 档案原地迁成 v2（roles/ + rosters/ + dist/）
   dsh-agent-roster --version         输出版本号
 
 选项：
@@ -37,7 +45,10 @@ const USAGE = `用法：
   --file <path>             registry 文件（registry 子命令用）
   --local-only              fetch 只验本仓库登记的 collection（CI 里用，不依赖外网）
   --write                   sync 把重算结果写回文件
-  --json                    以 JSON 输出（validate 与 list 都支持）
+  --roster <path>           v2 组装目录（compile 用）
+  --run <path>              执行回执（compile 用；把上一轮失败并入重试卡）
+  --roles <path>            角色库目录（compile 用；缺省按 rosters/<id> 推同级的 roles/）
+  --json                    以 JSON 输出（validate / list / compile 都支持）
   --help                    显示本帮助
 `;
 
@@ -53,6 +64,9 @@ function parseArgs(argv) {
     file: null,
     localOnly: false,
     write: false,
+    roster: null,
+    roles: null,
+    run: null,
   };
   for (let index = 0; index < argv.length; index += 1) {
     const arg = argv[index];
@@ -71,6 +85,21 @@ function parseArgs(argv) {
       if (value === undefined) throw new UsageError("--file 需要一个路径");
       options.file = value;
       index += 1;
+    } else if (arg === "--roster") {
+      const value = argv[index + 1];
+      if (value === undefined) throw new UsageError("--roster 需要一个路径");
+      options.roster = value;
+      index += 1;
+    } else if (arg === "--run") {
+      const value = argv[index + 1];
+      if (value === undefined) throw new UsageError("--run 需要一个路径");
+      options.run = value;
+      index += 1;
+    } else if (arg === "--roles") {
+      const value = argv[index + 1];
+      if (value === undefined) throw new UsageError("--roles 需要一个路径");
+      options.roles = value;
+      index += 1;
     } else if (arg === "--known-policy") {
       const value = argv[index + 1];
       if (value === undefined) throw new UsageError("--known-policy 需要一个 id");
@@ -112,6 +141,8 @@ async function main(argv) {
     process.stdout.write(`${pkg.name} ${pkg.version}\n`);
     return 0;
   }
+  if (options.command === "compile") return runCompile(options);
+  if (options.command === "migrate") return runMigrate(options);
   if (options.command === "registry") {
     if (options.file === null) {
       process.stderr.write(`registry 子命令需要 --file\n\n${USAGE}`);
@@ -201,6 +232,136 @@ async function main(argv) {
  * - `fetch` 确认索引里写的每份档案真的存在（本仓库的走本地文件，其余走网络）；
  * - `sync` 用仓库实际内容重算 `rosters` 与 `generatedAt`，把人肉维护改成机器盖章。
  */
+/**
+ * 编译一份 v2 组装。
+ *
+ * 三条约定：
+ * 1. 默认**不写盘**——编译是纯函数，`--write` 才落 `dist/`；
+ * 2. 有 error 就是退出码 1，警告不影响；
+ * 3. 产物是消费者唯一入口：桥接层与面板不需要再解析源文件。
+ */
+async function runCompile(options) {
+  if (options.roster === null) {
+    process.stderr.write(`compile 需要 --roster\n\n${USAGE}`);
+    return 2;
+  }
+  const rosterDir = nodePath.resolve(process.cwd(), options.roster);
+  const parent = nodePath.dirname(rosterDir);
+  const root = options.roles === null && nodePath.basename(parent) === "rosters" ? nodePath.dirname(parent) : null;
+  const rolesDir =
+    options.roles === null
+      ? root === null
+        ? nodePath.join(parent, "roles")
+        : nodePath.join(root, "roles")
+      : nodePath.resolve(process.cwd(), options.roles);
+
+  const result = compileRosterAt(rosterDir, {
+    rolesDir,
+    knownToolPolicies: options.knownPolicies.length > 0 ? options.knownPolicies : null,
+    source: { repo: ownRepo(), ref: "main" },
+  });
+
+  const diagnostics = [...(result.diagnostics ?? [])];
+  const planResult = result.compiled === null ? { plan: null, diagnostics: [] } : compilePlan(result.compiled);
+  let plan = planResult.plan;
+  diagnostics.push(...planResult.diagnostics);
+  let feedback = [];
+  if (options.run !== null) {
+    const runPath = nodePath.resolve(process.cwd(), options.run);
+    let runValue = null;
+    try {
+      runValue = JSON.parse(readFileSync(runPath, "utf8"));
+    } catch (error) {
+      diagnostics.push({ severity: "error", code: "run-unreadable", path: "", file: options.run, reason: `读不到执行回执：${error?.message ?? error}` });
+    }
+    if (runValue !== null) {
+      const validation = validateRun(runValue, { file: options.run });
+      diagnostics.push(...validation.diagnostics);
+      if (validation.ok) {
+        const merged = mergeRunIntoPlan(plan, validation.run);
+        plan = merged.plan;
+        feedback = merged.feedback;
+      }
+    }
+  }
+  const errors = diagnostics.filter((item) => item.severity === "error");
+
+  if (options.json) {
+    process.stdout.write(
+      `${JSON.stringify(
+        {
+          plugin: pkg.name,
+          version: pkg.version,
+          rolesDir,
+          rosterDir,
+          ok: result.ok,
+          compiled: result.compiled,
+          plan: plan === null ? null : planResult.plan,
+          diagnostics,
+        },
+        null,
+        2,
+      )}\n`,
+    );
+    return errors.length > 0 ? 1 : 0;
+  }
+
+  if (!result.ok || result.compiled === null) {
+    process.stderr.write(`编译失败：${nodePath.basename(rosterDir)}\n`);
+    for (const item of diagnostics) process.stderr.write(`${formatDiagnostic(item)}\n`);
+    return 1;
+  }
+
+  const compiled = result.compiled;
+  const chars = compiled.members.reduce((sum, item) => sum + item.promptStats.chars, 0);
+  process.stdout.write(
+    `产物 ${compiled.source.roster}@${compiled.source.version}  成员 ${compiled.members.length}  ` +
+      `人设合计 ${chars} 字符  声明 ${compiled.declarations.length} 项  targets ${compiled.targets.join(",") || "-"}\n`,
+  );
+  if (compiled.captain !== null) {
+    process.stdout.write(`  队长 ${compiled.captain.role ?? "-"}  persona ${compiled.captain.personaChars} 字符\n`);
+  }
+  if (compiled.orchestration !== null) {
+    process.stdout.write(
+      `  编排 ${compiled.orchestration.shape ?? "-"}  stages ${compiled.orchestration.stages.length}  ` +
+        `gates ${compiled.orchestration.gates.length}  status ${compiled.orchestration.status}\n`,
+    );
+  }
+  if (plan !== null) {
+    const gates = plan.tasks.filter((task) => task.kind === "gate").length;
+    const loop = plan.loop.onGateFailure;
+    process.stdout.write(
+      `  施工图 ${plan.tasks.length} 张卡  门 ${gates}  executor ${plan.executor}  ` +
+        `重试回到 ${loop.retry ?? "-"}（最多 ${loop.maxRounds} 轮）\n`,
+    );
+  }
+  if (feedback.length > 0) {
+    process.stdout.write(`  回执 上一轮失败 ${feedback.length} 张卡，已并入重试卡\n`);
+  }
+  for (const member of compiled.members) {
+    process.stdout.write(
+      `  ${member.name.padEnd(24)} ${member.role.padEnd(24)} ${String(member.promptStats.chars).padStart(5)} 字符  ` +
+        `${member.promptStats.sha256.slice(0, 12)}\n`,
+    );
+  }
+  for (const item of diagnostics) process.stdout.write(`${formatDiagnostic(item)}\n`);
+
+  if (options.write) {
+    const outDir = nodePath.join(root ?? parent, "dist");
+    mkdirSync(outDir, { recursive: true });
+    const outFile = nodePath.join(outDir, `${compiled.source.roster}-${compiled.source.version}.json`);
+    writeFileSync(outFile, `${JSON.stringify(compiled, null, 2)}\n`);
+    process.stdout.write(`  已写出 ${nodePath.relative(process.cwd(), outFile) || outFile}\n`);
+    if (plan !== null) {
+      const planFile = nodePath.join(outDir, `${compiled.source.roster}-${compiled.source.version}.tasks.json`);
+      writeFileSync(planFile, `${JSON.stringify(plan, null, 2)}\n`);
+      process.stdout.write(`  已写出 ${nodePath.relative(process.cwd(), planFile) || planFile}\n`);
+    }
+  }
+
+  return 0;
+}
+
 async function runRegistry(options) {
   const file = nodePath.resolve(process.cwd(), options.file);
   const output = (text) => process.stdout.write(`${text}\n`);
@@ -333,3 +494,68 @@ function isOwnCollection(collection, own) {
 }
 
 process.exitCode = await main(process.argv.slice(2));
+
+/**
+ * `migrate`：把一座 v1 档案库原地迁到 v2 布局。
+ *
+ * 默认只出计划（要写哪些文件、编译能不能过），`--write` 才真的落盘；这是唯一一个会删旧目录
+ * 的命令，所以默认不动手。
+ */
+function runMigrate(options) {
+  const dirs = options.dirs.length > 0 ? options.dirs : [""];
+  const knownToolPolicies = options.knownPolicies.length > 0 ? options.knownPolicies : null;
+  let rc = 0;
+  const reports = [];
+  for (const dir of dirs) {
+    const rootDir = resolveDirSpec(dir, process.cwd());
+    const report = migrateLibrary(rootDir, { write: options.write, knownToolPolicies, source: { repo: ownRepo(), ref: "main" } });
+    reports.push({ dir, rootDir, report });
+    if (report.diagnostics.some((item) => item.severity === "error")) rc = 1;
+    if (options.json) continue;
+    process.stdout.write(`${options.write ? "迁移" : "迁移计划（未写盘）"}  ${rootDir}\n`);
+    if (report.entries.length === 0) process.stdout.write("  没有找到 v1 档案（每个子目录里的 roster.yaml）\n");
+    for (const entry of report.entries) {
+      const extra = [entry.hasCaptain ? "含队长" : null, entry.capabilities ? "能力要求" : null].filter(Boolean).join(" · ");
+      process.stdout.write(`  ${entry.id}@${entry.version}  成员 ${entry.memberCount}  文件 ${entry.files.length}${extra ? `  ${extra}` : ""}\n`);
+      if (!options.write) {
+        for (const file of entry.files) process.stdout.write(`    + ${file.path}\n`);
+      }
+    }
+    if (options.write) {
+      process.stdout.write(`  写入 ${report.written.length} 个文件，删除 ${report.removed.length} 个旧目录，编译 ${report.compiled.length} 份\n`);
+    }
+    for (const item of report.diagnostics) process.stdout.write(`  ${formatDiagnostic(item)}\n`);
+  }
+  if (options.json) {
+    process.stdout.write(
+      `${JSON.stringify(
+        {
+          plugin: pkg.name,
+          version: pkg.version,
+          write: options.write,
+          reports: reports.map((item) => ({
+            dir: item.dir,
+            rootDir: item.rootDir,
+            write: item.report.write,
+            entries: item.report.entries.map((entry) => ({
+              id: entry.id,
+              version: entry.version,
+              from: entry.from,
+              files: entry.files.map((file) => file.path),
+              memberCount: entry.memberCount,
+              hasCaptain: entry.hasCaptain,
+              capabilities: entry.capabilities,
+            })),
+            written: item.report.written,
+            removed: item.report.removed,
+            compiled: item.report.compiled,
+            diagnostics: item.report.diagnostics,
+          })),
+        },
+        null,
+        2,
+      )}\n`,
+    );
+  }
+  return rc;
+}