@stofone/dsh-agent-roster 0.9.1 → 0.10.0

package/CHANGELOG.md

@@ -4,6 +4,75 @@
 
 ## [Unreleased]
 
+## [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
+
+- **Four columns now line up across rows.** Each member row used to compute its own grid, so the
+  name / description / tool policy / model columns drifted from row to row and the list read as
+  separate blocks. `.rstr-members` owns the column widths and every row uses `subgrid`.
+- **One line per member at narrow widths**: name and role on the left, the policy pinned right,
+  description and model beneath — four lines instead of five, and nothing overlaps.
+- Member notes (aliases, declared skills, inherited fields) span the full row instead of pushing
+  the columns around.
+
 ## [0.9.1] - 2026-11-03
 
 ### Expansion stops clipping itself
@@ -376,7 +445,8 @@
 - 工具返回值含 `undefined` 键，运行时按 `value is not lossless JSON` 整次拒绝；缺失值统一写 `null`，
   且所有返回值先过 `lib/json.js#lossless`。
 
-[Unreleased]: https://github.com/dsh-agent-roster/dsh-agent-roster/compare/v0.9.1...main
+[Unreleased]: https://github.com/dsh-agent-roster/dsh-agent-roster/compare/v0.9.2...main
+[0.9.2]: https://github.com/dsh-agent-roster/dsh-agent-roster/releases/tag/v0.9.2
 [0.9.1]: https://github.com/dsh-agent-roster/dsh-agent-roster/releases/tag/v0.9.1
 [0.9.0]: https://github.com/dsh-agent-roster/dsh-agent-roster/releases/tag/v0.9.0
 [0.8.3]: https://github.com/dsh-agent-roster/dsh-agent-roster/releases/tag/v0.8.3

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 |
@@ -378,9 +451,10 @@ lib/              format, parse, validate, registry, bridge, verify, render, lib
 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
+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 +463,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

@@ -217,6 +217,49 @@ 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 冻结，`roster 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)。
+
 ## 工具
 
 | 工具 | 作用 |
@@ -374,7 +417,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;
+}

package/client.js

@@ -468,6 +468,20 @@ window.__ModuleLoader__.load({
     /* ------------------------------------------------------------------ */
 
     function MemberBlock({ member }) {
+      // 四列由 .rstr-members 的 subgrid 统一给宽度：姓名 / 说明 / 策略 / 模型。
+      // 说明与策略即使为空也占位，否则后面的列会整体左移，表格就对不齐了。
+      const notes = [];
+      if (Array.isArray(member.aliases) && member.aliases.length > 0) {
+        notes.push(`${t("member.aliases")}: ${member.aliases.join(", ")}`);
+      }
+      if (Array.isArray(member.skills) && member.skills.length > 0) {
+        notes.push(`${t("member.skills")}: ${member.skills.join(", ")}（${t("member.skillsHint")}）`);
+      }
+      if (Array.isArray(member.inherited) && member.inherited.length > 0) {
+        notes.push(`inherited: ${member.inherited.join(", ")}`);
+      }
+      if (member.notes) notes.push(member.notes);
+
       return h(
         "div",
         { className: "rstr-member" },
@@ -477,33 +491,24 @@ window.__ModuleLoader__.load({
           h("strong", { className: "rstr-member-name" }, member.name),
           member.role ? h(Chip, null, member.role) : null,
         ),
-        member.description ? h("p", { className: "rstr-member-desc" }, member.description) : null,
-        Array.isArray(member.aliases) && member.aliases.length > 0
-          ? h("p", { className: "rstr-muted rstr-small" }, `${t("member.aliases")}: ${member.aliases.join(", ")}`)
-          : null,
+        h("p", { className: "rstr-member-desc" }, member.description ?? ""),
+        h(
+          "span",
+          { className: "rstr-member-policy" },
+          member.toolPolicy ? h(Chip, { tone: "policy" }, member.toolPolicy) : null,
+        ),
         h(
           "div",
           { className: "rstr-member-meta" },
-          member.toolPolicy ? h(Chip, { tone: "policy" }, member.toolPolicy) : null,
-          member.model ? h("span", null, `${t("member.model")}: ${member.model}`) : null,
-          member.reasoningEffort ? h("span", null, `${t("member.effort")}: ${member.reasoningEffort}`) : null,
+          member.model ? h("span", null, member.model) : null,
+          member.reasoningEffort ? h("span", null, member.reasoningEffort) : null,
           member.fallback ? h("span", null, `${t("member.fallback")}: ${member.fallback}`) : null,
           member.toolScope?.allow?.length
             ? h("span", null, `${t("member.tools")}: ${member.toolScope.allow.join(", ")}`)
             : null,
           h("span", { className: "rstr-muted" }, t("team.promptChars", { count: member.systemPromptChars })),
         ),
-        Array.isArray(member.skills) && member.skills.length > 0
-          ? h(
-              "p",
-              { className: "rstr-muted rstr-small" },
-              `${t("member.skills")}: ${member.skills.join(", ")}（${t("member.skillsHint")}）`,
-            )
-          : null,
-        Array.isArray(member.inherited) && member.inherited.length > 0
-          ? h("p", { className: "rstr-muted rstr-small" }, `inherited: ${member.inherited.join(", ")}`)
-          : null,
-        member.notes ? h("p", { className: "rstr-muted rstr-small" }, member.notes) : null,
+        notes.map((text, index) => h("p", { key: `note-${index}`, className: "rstr-member-note" }, text)),
       );
     }
 
@@ -2360,21 +2365,41 @@ window.__ModuleLoader__.load({
 
 /* ---- 成员块 ----------------------------------------------------------- */
 
-.rstr-members { display: flex; flex-direction: column; gap: 0; border-top: 1px dashed var(--dsw-alias-border-l1); }
+/* 成员是一张表：四列由容器统一给宽度（subgrid），否则每一行各算各的网格，
+   姓名 / 说明 / 策略 / 模型四列对不齐，读起来就是散的。 */
+.rstr-members {
+  display: grid;
+  grid-template-columns: minmax(120px, 172px) minmax(0, 1fr) 104px 244px;
+  column-gap: 14px;
+  border-top: 1px dashed var(--dsw-alias-border-l1);
+}
 .rstr-member {
   display: grid;
-  grid-template-columns: minmax(120px, 170px) minmax(0, 1fr) auto;
-  gap: 6px 16px;
+  grid-column: 1 / -1;
+  grid-template-columns: subgrid;
+  column-gap: 14px;
+  row-gap: 2px;
   align-items: baseline;
-  padding: 9px 4px;
+  padding: 10px 4px;
   border-bottom: 1px solid var(--dsw-alias-border-l1);
   min-width: 0;
 }
 .rstr-member:last-child { border-bottom: none; }
 .rstr-member-head { display: flex; align-items: baseline; gap: 8px; flex-wrap: wrap; min-width: 0; }
-.rstr-member-name { font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; font-size: 12px; font-weight: 600; color: var(--dsw-alias-label-primary); }
+.rstr-member-name { font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; font-size: 12px; font-weight: 600; color: var(--dsw-alias-label-primary); overflow: hidden; text-overflow: ellipsis; }
 .rstr-member-desc { margin: 0; font-size: 12px; color: var(--dsw-alias-label-secondary); min-width: 0; }
-.rstr-member-meta { display: flex; align-items: baseline; gap: 8px; flex-wrap: wrap; font-size: 11px; color: var(--dsw-alias-label-secondary); justify-self: end; font-variant-numeric: tabular-nums; }
+.rstr-member-policy { justify-self: start; min-width: 0; }
+.rstr-member-meta { display: flex; align-items: baseline; gap: 10px; flex-wrap: wrap; font-size: 11px; color: var(--dsw-alias-label-secondary); justify-self: end; font-variant-numeric: tabular-nums; }
+.rstr-member-note { grid-column: 1 / -1; margin: 0; font-size: 11px; color: var(--dsw-alias-label-secondary); }
+@media (max-width: 900px) {
+  /* 窄面板：姓名一行、策略贴右；说明与模型各占一整行。 */
+  .rstr-members { grid-template-columns: minmax(0, 1fr) auto; }
+  .rstr-member-head { grid-column: 1; grid-row: 1; }
+  .rstr-member-policy { grid-column: 2; grid-row: 1; justify-self: end; }
+  .rstr-member-desc { grid-column: 1 / -1; grid-row: 2; margin-top: 2px; }
+  .rstr-member-meta { grid-column: 1 / -1; grid-row: 3; justify-self: start; }
+  .rstr-member-note { grid-row: auto; }
+}
 
 /* ---- 队长块 ----------------------------------------------------------- */