@stofone/dsh-agent-roster 0.7.0 → 0.8.0

package/CHANGELOG.md

@@ -4,6 +4,39 @@
 
 ## [Unreleased]
 
+## [0.8.0] - 2026-11-02
+
+### Library organization (new root file)
+
+- **`organization.yaml`** — an optional file at the library root, beside the roster directories.
+  It declares which rosters belong to the library, their status (`active` | `archived`) and where
+  they came from. It is the only file allowed to sit at the root, and it still cannot create
+  anything: no teams, no members, no `agent_teams_add_member` arguments.
+- **Three-way cross-check against the disk**, surfaced as diagnostics the panel already renders:
+  declared but missing → **error**, present but undeclared → **warn**, declared `archived` but
+  still in the library → **info**. Archiving is a declaration, not a deletion.
+- **`roster_list` and `dsh-agent-roster validate` show it** (`organization=<id>`, the counts, and
+  per-file `organization` / `organizationCheck` in `--json`);
+  `schema/organization.v1.schema.json` covers the file for editor-side validation.
+- **`orgs/agent-roster-collective/`** ships as a worked example: 21 self-authored rosters
+  (63 members) covering review, incident response, data, docs, release, research and more.
+- **`security-audit/capabilities.yaml`** in that example shows the two-file library: a roster plus
+  its declared requirements, with `onMissing: degraded` so a deployment without the policy still
+  builds the team but reports the gap instead of pretending it passed.
+
+### Registry schema (new file)
+
+- **`schema/registry.v1.schema.json`** — the shipped `index/registry.json` pointed at a schema that
+  did not exist, so editors had nothing to lint against. The file now exists, mirrors
+  `lib/remote.js#validateRegistry`, and `test/registry-schema.test.js` keeps the two aligned
+  (field sets, id/repo/ref/path patterns, collection and roster limits).
+
+### Removed
+
+- **`INDEX_KIND`** (`dsh-agent-roster-index/v1`). Nothing ever produced that document: a registry
+  collection already carries its `rosters` list, and `registry sync` recomputes it from the
+  repository. Keeping a second manifest format would have been a second source of truth.
+
 ## [0.7.0] - 2026-11-02
 
 ### Honest verification (issue #2)
@@ -263,6 +296,7 @@
 - 工具返回值含 `undefined` 键，运行时按 `value is not lossless JSON` 整次拒绝；缺失值统一写 `null`，
   且所有返回值先过 `lib/json.js#lossless`。
 
-[Unreleased]: https://github.com/STofone/dsh-agent-roster/compare/v0.7.0...main
+[Unreleased]: https://github.com/STofone/dsh-agent-roster/compare/v0.8.0...main
+[0.8.0]: https://github.com/STofone/dsh-agent-roster/releases/tag/v0.8.0
 [0.7.0]: https://github.com/STofone/dsh-agent-roster/releases/tag/v0.7.0
 [0.2.0]: https://github.com/STofone/dsh-agent-roster/releases/tag/v0.2.0

package/README.md

@@ -187,6 +187,40 @@ Behaviour: under `onMissing: refuse` (default) `roster_create` emits **no** `age
 
 The sibling file has its own JSON Schema: [`schema/capabilities.v1.schema.json`](./schema/capabilities.v1.schema.json), kept aligned with `lib/capabilities.js` by `test/capabilities.test.js`.
 
+## Library organization (`organization.yaml`)
+
+A roster answers *who the members are*; it cannot answer **which rosters belong together, which one is production and which is retired**. When a library holds twenty archives from different sources, the directory listing stops being an index. An optional file at the **library root** declares that, and nothing else:
+
+```yaml
+kind: dsh-agent-roster-organization/v1
+organization: agent-roster-collective   # must equal the directory name
+title: 团队档案合集
+maintainers: [STofone]
+rosters:
+  - {id: api-design, title: API 设计评审组, status: active, origin: 本项目自撰}
+  - {id: legacy-team, status: archived}
+```
+
+Placement matters: the file sits **next to** the roster directories, not inside one. It is a table of contents for the library, so it is the only file allowed at the root — scatter a `foo.yaml` there and the scanner still warns `unexpected-file`.
+
+The declaration is mechanically checked against disk, and the three outcomes are deliberately different severities:
+
+| Situation | Code | Severity | Why |
+|---|---|---|---|
+| declared, directory missing | `organization-roster-missing` | **error** | the organization page is lying — worse than no page |
+| directory present, not declared | `organization-roster-undeclared` | warn | someone added a roster around the index; it still loads |
+| declared `archived`, directory still there | `organization-roster-archived` | info | archiving is a statement, not a delete |
+
+`organization` must equal the directory name, exactly like `roster` does: position is identity, and two ids for one library would make every diagnostic ambiguous. Unknown keys are rejected — a field nobody can check is another way to look green.
+
+This file creates nothing. It does not write `team.json`, does not create members, and never reaches `agent_teams_add_member`. Its JSON Schema is [`schema/organization.v1.schema.json`](./schema/organization.v1.schema.json), kept aligned with `lib/organization.js` by `test/organization.test.js`.
+
+**A worked example ships in this repository:** [`orgs/agent-roster-collective/`](./orgs/agent-roster-collective/) holds 21 rosters (63 members) covering API review, incident response, data quality, database migration, localization, security audit, performance, frontend, docs, release, support triage, recruiting, market research, finance reconciliation, contract review, content ops, regression testing, model evaluation, SRE on-call, literature review and product discovery. Every roster is a three-person team with a captain, and each was written for this repository (no upstream text is copied). Validate it with:
+
+```bash
+node bin/cli.mjs validate --dir orgs/agent-roster-collective
+```
+
 ## Tools
 
 | Tool | Purpose |
@@ -274,6 +308,8 @@ repository's `index/registry.json`, and anyone who subscribes can see them in th
 - **Pulling**: writes are idempotent and report one of `created`, `updated` (explicit overwrite), `unchanged`
   (same content, nothing written) or `conflict` (the local copy differs and is **not** overwritten by default).
   Conflicts are yours to resolve: merge in the editor, or pull again with `overwrite` in the request body.
+- **The index has a schema**: [`schema/registry.v1.schema.json`](./schema/registry.v1.schema.json) mirrors the
+  runtime validator, so an editor flags a typo before CI does.
 - **Publishing your own**: add an entry to `collections` in `index/registry.json` (`id`, `repo: github:owner/repo`,
   `ref`, `path`, `rosters[]`) and open a PR. `.github/workflows/registry.yml` checks the index against the real files.
 
@@ -339,10 +375,11 @@ 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.v1.schema.json (editor completion; kept aligned by tests)
+schema/           roster / capabilities / organization / registry v1 schemas (editor completion; kept aligned by tests)
 bin/cli.mjs       validate/list/version for CI
 scripts/          host-smoke.mjs, client-smoke.mjs, check-locale.mjs (dev only, not shipped)
 examples/         two example libraries
+orgs/             a worked example library with its own organization.yaml (21 rosters)
 test/             unit tests
 ```
 
@@ -350,7 +387,7 @@ test/             unit tests
 
 Verified on this machine:
 
-- `npm test` — 223/223 passing (format, parse, validate, registry, paths, bridge, verify buckets, digests and provenance, roster diff, capability requirements and the capability gate, 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` — 239/239 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 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

@@ -183,6 +183,40 @@ notes: 建队前先确认成员会话可用。
 
 兄弟文件有自己的 JSON Schema：[`schema/capabilities.v1.schema.json`](./schema/capabilities.v1.schema.json)，由 `test/capabilities.test.js` 钉住与 `lib/capabilities.js` 一致。
 
+## 档案库组织（`organization.yaml`）
+
+档案回答的是**成员是谁**，回答不了**哪几份档案属于同一套、哪份是生产、哪份已退役**。一座库放二十份来自不同来源的档案时，目录列表就不再是索引。库**根目录**上一个可选文件只声明这件事：
+
+```yaml
+kind: dsh-agent-roster-organization/v1
+organization: agent-roster-collective   # 必须等于目录名
+title: 团队档案合集
+maintainers: [STofone]
+rosters:
+  - {id: api-design, title: API 设计评审组, status: active, origin: 本项目自撰}
+  - {id: legacy-team, status: archived}
+```
+
+位置是有讲究的：它和档案目录**并列**，不在任何一份档案里面。它是这座库的目录页，所以也是库根唯一被允许的文件——在根上散落一个 `foo.yaml` 依然会报 `unexpected-file`。
+
+声明会和磁盘对账，三种结果刻意用不同严重度：
+
+| 情况 | 代码 | 严重度 | 理由 |
+|---|---|---|---|
+| 声明了，目录不在 | `organization-roster-missing` | **error** | 组织页在撒谎，比没有组织页更糟 |
+| 目录在，没登记 | `organization-roster-undeclared` | warn | 有人绕过索引加了档案，但它仍会被加载 |
+| 声明 `archived`，目录还在 | `organization-roster-archived` | info | 归档是声明，不是删除 |
+
+`organization` 必须等于目录名，和 `roster` 同一条规则：位置即身份，一座库两个 id 会让所有诊断都变得没法定位。未知键一律拒收——没人核得了的字段，只是换一种方式发绿。
+
+这份文件什么都不创建：不写 `team.json`、不建成员，也永远不会进入 `agent_teams_add_member` 参数。它的 JSON Schema 在 [`schema/organization.v1.schema.json`](./schema/organization.v1.schema.json)，由 `test/organization.test.js` 钉住与 `lib/organization.js` 一致。
+
+**仓内带了一个可跑的示例**：[`orgs/agent-roster-collective/`](./orgs/agent-roster-collective/) 里有 21 份档案（63 名成员），覆盖接口评审、事故响应、数据质量、数据库迁移、本地化、安全审计、性能、前端、文档、发布、客服分诊、招聘、市场研究、财务对账、合同审阅、内容运营、回归测试、模型评测、SRE 值守、文献综述与产品发现。每份都是"队长 + 两名专家"的三人组，全部为本项目自撰（未复制任何上游文本）。校验方式：
+
+```bash
+node bin/cli.mjs validate --dir orgs/agent-roster-collective
+```
+
 ## 工具
 
 | 工具 | 作用 |
@@ -259,6 +293,8 @@ notes: 建队前先确认成员会话可用。
 - **拉取到本机**：写入是幂等的，四种结果都会报给你——
   `created`（新写入）、`updated`（显式覆盖）、`unchanged`（内容一致，不写盘）、`conflict`（本地不一样，**默认不覆盖**）。
   冲突要你自己决定：要么在编辑器里合并，要么再点一次「拉取到本机」并在请求里带 `overwrite`。
+- **索引本身也有 schema**：[`schema/registry.v1.schema.json`](./schema/registry.v1.schema.json) 与运行时校验器对齐，
+  拼错字段在编辑器里就会提示，不必等 CI。
 - **登记自己的档案**：在 `index/registry.json` 的 `collections` 里加一条（`id`、`repo: github:owner/repo`、
   `ref`、`path`、`rosters[]`），提交 PR 即可；`.github/workflows/registry.yml` 会校验索引与仓库真实文件是否对得上。
 
@@ -322,10 +358,11 @@ lib/              format / parse / validate / registry / bridge / verify / rende
                   config-view / json / http / write / service / teams-state / tools
 client.js         客户端半边：左侧栏图标 + 主面板（档案/团队/体检）+ 设置页小节
 locale/           面板与列表词典（en/zh）
-schema/           roster.v1.schema.json（编辑器补全用，与校验器由测试对齐）
+schema/           roster / capabilities / organization / registry v1 schema（编辑器补全用，与校验器由测试对齐）
 bin/cli.mjs       validate / list / version，给 CI 用
 scripts/          host-smoke.mjs、client-smoke.mjs、check-locale.mjs（开发用，不随包发布）
 examples/         两座示例档案库
+orgs/             带 organization.yaml 的示例库（21 套档案）
 test/             单测
 ```
 
@@ -333,7 +370,7 @@ test/             单测
 
 本机已验证：
 
-- `npm test` —— 223/223 通过（格式、解析、校验、扫描、路径、桥接、核对四桶、摘要与溯源、档案差异、能力要求与能力闸门、无损 JSON、写入计划与执行、六条路由、快照与提示、两本词典一致、工具契约、客户端加载器契约、包清单、配置视图、样式 token 约束、声明层字段与队长段、schema 与常量对齐）。
+- `npm test` —— 239/239 通过（格式、解析、校验、扫描、路径、桥接、核对四桶、摘要与溯源、档案差异、能力要求与能力闸门、档案库组织、索引 schema、无损 JSON、写入计划与执行、六条路由、快照与提示、两本词典一致、工具契约、客户端加载器契约、包清单、配置视图、样式 token 约束、声明层字段与队长段、schema 与常量对齐）。
 - `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

@@ -147,6 +147,8 @@ async function main(argv) {
             rootDir: report.rootDir,
             missing: report.scan.missing,
             stats: report.scan.stats,
+            organization: report.scan.organization,
+            organizationCheck: report.scan.organizationCheck,
             rosters: report.scan.rosters.map((roster) => ({ id: roster.id, file: roster.file })),
             diagnostics: report.scan.diagnostics,
           })),
@@ -162,6 +164,14 @@ async function main(argv) {
         process.stdout.write(`${renderRosterList(report.scan)}\n`);
       } else {
         const { stats } = report.scan;
+        const organization = report.scan.organization ?? null;
+        if (organization !== null) {
+          const check = report.scan.organizationCheck;
+          process.stdout.write(
+            `  组织 ${organization.id}  ${organization.title}（登记 ${check.declared} · 在库 ${check.present} · ` +
+              `缺 ${check.missing.length} · 未登记 ${check.undeclared.length}）\n`,
+          );
+        }
         process.stdout.write(
           `  档案 ${stats.total}（通过 ${stats.ok}，失败 ${stats.failed}），成员 ${stats.members}，` +
             `诊断 ${stats.errors} error / ${stats.warnings} warn / ${stats.infos} info\n`,

package/index/registry.json

@@ -2,7 +2,7 @@
   "$schema": "../schema/registry.v1.schema.json",
   "kind": "dsh-agent-roster-registry/v1",
   "version": 1,
-  "generatedAt": "2026-10-30T00:00:00.000Z",
+  "generatedAt": "2026-11-02T17:00:43.713Z",
   "generator": "STofone/dsh-agent-roster (hand-maintained; verified by .github/workflows/registry.yml)",
   "source": "https://github.com/STofone/dsh-agent-roster",
   "collections": [
@@ -28,6 +28,50 @@
       ],
       "homepage": "https://github.com/STofone/dsh-agent-roster#examples"
     },
+    {
+      "id": "agent-roster-collective",
+      "title": "自撰团队档案合集（21 套 · 63 名成员）",
+      "description": "覆盖评审、事故响应、数据、文档、发布、研究等常见协作分工的 21 套档案，全部由本项目自撰（未复制任何上游文本），可直接复制改成自己的。",
+      "repo": "github:STofone/dsh-agent-roster",
+      "ref": "main",
+      "path": "orgs/agent-roster-collective",
+      "rosters": [
+        "api-design",
+        "content-ops",
+        "contract-review",
+        "data-quality",
+        "db-migration",
+        "docs-writer",
+        "finance-recon",
+        "frontend-ui",
+        "i18n-l10n",
+        "incident-response",
+        "literature-review",
+        "market-research",
+        "ml-eval",
+        "performance",
+        "product-discovery",
+        "qa-regression",
+        "recruiting",
+        "release-manager",
+        "security-audit",
+        "sre-oncall",
+        "support-triage"
+      ],
+      "tags": [
+        "collection",
+        "examples",
+        "operations",
+        "data",
+        "docs",
+        "research"
+      ],
+      "license": "MIT",
+      "maintainers": [
+        "STofone"
+      ],
+      "homepage": "https://github.com/STofone/dsh-agent-roster/tree/main/orgs/agent-roster-collective"
+    },
     {
       "id": "agent-teams",
       "title": "Agent Teams（wshobson/agents 迁移）",

package/lib/format.js

@@ -10,14 +10,13 @@
 /** 档案文档格式标识（出现在每份 roster.yaml 的 kind 字段）。 */
 export const ROSTER_KIND = "dsh-agent-roster/v1";
 
-/** 索引文档格式标识（由 scan CLI / GitHub Action 产出）。 */
-export const INDEX_KIND = "dsh-agent-roster-index/v1";
-
 /**
  * 公共档案库目录（registry）的格式标识。
  *
- * 与 {@link INDEX_KIND} 的区别：index 是“一个档案库扫描后的清单”（roster 指针），
- * registry 是“许多档案库的登记簿”（collection 指针）——后者才是订阅/共享的入口。
+ * 曾经另有一个 `dsh-agent-roster-index/v1`（“一个档案库扫描后的清单”），但没有任何命令
+ * 产出过它：registry 的每条 collection 本来就带 `rosters` 列表，并由 `registry sync`
+ * 按仓库实际内容重算——再定义第二种清单格式等于造第二个真源。故该常量已删除，
+ * 见 CHANGELOG 的 Removed 一节。
  */
 export const REGISTRY_KIND = "dsh-agent-roster-registry/v1";
 

package/lib/organization.js

@@ -0,0 +1,331 @@
+/**
+ * 组织档案（organization）：一座档案库的"目录页"。
+ *
+ * 为什么需要它：档案库只能回答"这一份档案写了什么"，回答不了"这些档案是什么关系、
+ * 哪份是生产、哪份是归档、谁维护"。当一座库里放二十份来自不同来源的档案时，
+ * 缺了这层就只能靠目录名猜。
+ *
+ * 边界（与 capabilities.yaml 同一条纪律）：
+ * - 组织只做**声明与核对**：声明库里有哪几份档案、各自什么状态；
+ *   它不创建团队、不改档案、不进 `agent_teams_add_member`。
+ * - 它**能被机械核对**：声明了但目录不在 = error，目录在却没声明 = warn，
+ *   已归档却仍在用 = info。核对不了的字段一律不收（未知键即错误）。
+ * - 位置即身份：`organization` 必须等于所在目录名，和 `roster` 的规则一致。
+ *
+ * @module dsh-agent-roster/organization
+ */
+
+/** 组织文件的 `kind`。与 roster / registry / capabilities 并列，互不冒充。 */
+export const ORGANIZATION_KIND = "dsh-agent-roster-organization/v1";
+
+/** 组织文件允许的文件名，按优先级排列。 */
+export const ORGANIZATION_FILE_NAMES = ["organization.yaml", "organization.yml", "organization.json"];
+
+/** 档案在组织里的状态。刻意只有两档：归档不等于删除，删除就是没有这个目录。 */
+export const ORGANIZATION_STATUSES = ["active", "archived"];
+
+/** 长度上限：与档案的 LIMITS 同一套口径，超了就报错而不是截断。 */
+export const LIMITS = {
+  rosters: 64,
+  titleChars: 120,
+  descriptionChars: 500,
+  licenseChars: 120,
+  homepageChars: 200,
+  maintainers: 16,
+  maintainerChars: 120,
+  noteChars: 300,
+};
+
+/** 组织 id 与档案 id 同形：小写、连字符、首字符必须是字母或数字。 */
+export const ID_PATTERN = /^[a-z0-9][a-z0-9-]{1,63}$/;
+
+const ROOT_FIELDS = new Set([
+  "kind",
+  "organization",
+  "title",
+  "description",
+  "license",
+  "homepage",
+  "maintainers",
+  "rosters",
+]);
+
+const ROSTER_FIELDS = new Set(["id", "title", "status", "origin", "note"]);
+
+/** 顶层字段清单（供 schema 对齐测试反向钉住，避免两处各写一份）。 */
+export const ORGANIZATION_FIELDS = Object.freeze([...ROOT_FIELDS]);
+
+/** 每条登记项的字段清单。 */
+export const ORGANIZATION_ROSTER_FIELDS = Object.freeze([...ROSTER_FIELDS]);
+
+/**
+ * 一条诊断。形状与 `lib/validate.js` 保持一致，好让 render / panel / CLI 用同一套渲染。
+ *
+ * @param {"error"|"warn"|"info"} severity
+ * @param {string} code
+ * @param {string} file
+ * @param {string} reason
+ * @returns {{severity: string, code: string, path: string, file: string, reason: string}}
+ */
+function diagnose(severity, code, file, reason) {
+  return { severity, code, path: "", file, reason };
+}
+
+/**
+ * 校验一份组织档案。
+ *
+ * 与 roster 的校验同一条纪律：**能核对的才收**。`homepage` 只校验是不是 http(s)，
+ * 不联网；`maintainers` 只校验形态，不校验这个人存在不存在。
+ *
+ * @param {unknown} value 解析后的 JSON/YAML 值
+ * @param {{file?: string, expectedId?: string|null}} [options]
+ * @returns {{ok: boolean, organization: object|null, diagnostics: object[]}}
+ */
+export function validateOrganization(value, options = {}) {
+  const file = options.file ?? ORGANIZATION_FILE_NAMES[0];
+  const expectedId = options.expectedId ?? null;
+  /** @type {object[]} */
+  const diagnostics = [];
+
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    diagnostics.push(diagnose("error", "organization-not-object", file, "组织文件必须是一个对象（键值对）。"));
+    return { ok: false, organization: null, diagnostics };
+  }
+
+  for (const key of Object.keys(value)) {
+    if (!ROOT_FIELDS.has(key)) {
+      diagnostics.push(
+        diagnose(
+          "error",
+          "unknown-field",
+          file,
+          `未知字段 "${key}"。组织文件只收 ${[...ROOT_FIELDS].join(" / ")}：` +
+            "核对不了的字段不收——写了也不会被任何人验证，只会被误当成事实。",
+        ),
+      );
+    }
+  }
+
+  if (value.kind !== ORGANIZATION_KIND) {
+    diagnostics.push(
+      diagnose("error", "organization-kind", file, `kind 必须是 "${ORGANIZATION_KIND}"，实际是 ${JSON.stringify(value.kind)}。`),
+    );
+  }
+
+  const id = value.organization;
+  if (typeof id !== "string" || !ID_PATTERN.test(id)) {
+    diagnostics.push(
+      diagnose("error", "organization-id", file, "organization 必须是 2–64 位小写字母/数字/连字符，且以字母或数字开头。"),
+    );
+  } else if (expectedId !== null && id !== expectedId) {
+    diagnostics.push(
+      diagnose(
+        "error",
+        "organization-id-mismatch",
+        file,
+        `organization 是 "${id}"，但所在目录叫 "${expectedId}"。位置即身份：组织 id 必须等于目录名。`,
+      ),
+    );
+  }
+
+  const title = optionalString(value, "title", LIMITS.titleChars, diagnostics, file, "organization-title");
+  optionalString(value, "description", LIMITS.descriptionChars, diagnostics, file, "organization-description");
+  optionalString(value, "license", LIMITS.licenseChars, diagnostics, file, "organization-license");
+
+  if (value.homepage !== undefined) {
+    const homepage = optionalString(value, "homepage", LIMITS.homepageChars, diagnostics, file, "organization-homepage");
+    if (typeof homepage === "string" && !/^https?:\/\/\S+$/i.test(homepage)) {
+      diagnostics.push(
+        diagnose("error", "organization-homepage", file, "homepage 只收 http(s) 地址：别的写法既打不开也核对不了。"),
+      );
+    }
+  }
+
+  if (value.maintainers !== undefined) {
+    if (!Array.isArray(value.maintainers)) {
+      diagnostics.push(diagnose("error", "organization-maintainers", file, "maintainers 必须是字符串数组。"));
+    } else if (value.maintainers.length > LIMITS.maintainers) {
+      diagnostics.push(
+        diagnose("error", "organization-maintainers", file, `maintainers 最多 ${LIMITS.maintainers} 项。`),
+      );
+    } else {
+      for (const who of value.maintainers) {
+        if (typeof who !== "string" || who.length === 0 || who.length > LIMITS.maintainerChars) {
+          diagnostics.push(
+            diagnose("error", "organization-maintainer", file, `维护者名字必须是 1–${LIMITS.maintainerChars} 个字符的字符串。`),
+          );
+          break;
+        }
+      }
+    }
+  }
+
+  const rosters = [];
+  const rawRosters = value.rosters;
+  if (!Array.isArray(rawRosters) || rawRosters.length === 0) {
+    diagnostics.push(diagnose("error", "organization-rosters", file, "rosters 必须是非空数组：组织的意义就是登记这些档案。"));
+  } else if (rawRosters.length > LIMITS.rosters) {
+    diagnostics.push(diagnose("error", "organization-rosters", file, `rosters 最多 ${LIMITS.rosters} 项。`));
+  } else {
+    const seen = new Set();
+    rawRosters.forEach((item, index) => {
+      const where = `rosters[${index}]`;
+      if (item === null || typeof item !== "object" || Array.isArray(item)) {
+        diagnostics.push(diagnose("error", "organization-roster-not-object", file, `${where} 必须是对象。`));
+        return;
+      }
+      for (const key of Object.keys(item)) {
+        if (!ROSTER_FIELDS.has(key)) {
+          diagnostics.push(
+            diagnose("error", "unknown-field", file, `${where} 的未知字段 "${key}"（只收 ${[...ROSTER_FIELDS].join(" / ")}）。`),
+          );
+        }
+      }
+      if (typeof item.id !== "string" || !ID_PATTERN.test(item.id)) {
+        diagnostics.push(diagnose("error", "organization-roster-id", file, `${where}.id 必须是合法档案 id。`));
+        return;
+      }
+      if (seen.has(item.id)) {
+        diagnostics.push(
+          diagnose("error", "organization-duplicate-roster", file, `档案 "${item.id}" 在组织里登记了两次。`),
+        );
+        return;
+      }
+      seen.add(item.id);
+      const status = item.status ?? "active";
+      if (!ORGANIZATION_STATUSES.includes(status)) {
+        diagnostics.push(
+          diagnose("error", "organization-roster-status", file, `${where}.status 只能是 ${ORGANIZATION_STATUSES.join(" / ")}。`),
+        );
+      }
+      const entryTitle = optionalString(item, "title", LIMITS.titleChars, diagnostics, file, "organization-roster-title", where);
+      const origin = optionalString(item, "origin", LIMITS.titleChars, diagnostics, file, "organization-roster-origin", where);
+      const note = optionalString(item, "note", LIMITS.noteChars, diagnostics, file, "organization-roster-note", where);
+      rosters.push({
+        id: item.id,
+        title: entryTitle ?? "",
+        status,
+        origin: origin ?? "",
+        note: note ?? "",
+      });
+    });
+  }
+
+  if (diagnostics.some((item) => item.severity === "error")) {
+    return { ok: false, organization: null, diagnostics };
+  }
+
+  return {
+    ok: true,
+    organization: {
+      kind: ORGANIZATION_KIND,
+      id,
+      title: title ?? "",
+      description: value.description ?? "",
+      license: value.license ?? "",
+      homepage: value.homepage ?? "",
+      maintainers: Array.isArray(value.maintainers) ? [...value.maintainers] : [],
+      rosters,
+    },
+    diagnostics,
+  };
+}
+
+/**
+ * 读一个可选字符串字段并钉住上限。
+ *
+ * @param {object} source
+ * @param {string} key
+ * @param {number} max
+ * @param {object[]} diagnostics
+ * @param {string} file
+ * @param {string} code
+ * @param {string} [where]
+ * @returns {string|undefined}
+ */
+function optionalString(source, key, max, diagnostics, file, code, where = "") {
+  const value = source[key];
+  if (value === undefined) return undefined;
+  const label = where === "" ? key : `${where}.${key}`;
+  if (typeof value !== "string" || value.length > max) {
+    diagnostics.push(diagnose("error", code, file, `${label} 必须是长度不超过 ${max} 的字符串。`));
+    return undefined;
+  }
+  return value;
+}
+
+/**
+ * 组织声明与磁盘实际情况的交叉核对。
+ *
+ * 三件事分开说，因为它们的严重度不同：
+ * - **缺**（声明了却找不到目录）：error。组织页在撒谎，比没有组织页更糟。
+ * - **多**（目录在却没登记）：warn。不是错误，但意味着有人绕过组织加了档案。
+ * - **归档仍在**：info。归档是声明，不是删除；提醒一句即可。
+ *
+ * @param {object|null} organization
+ * @param {string[]} rosterIds 磁盘上真正通过校验的档案 id
+ * @returns {{declared: number, present: number, missing: string[], undeclared: string[], archived: string[], status: string}}
+ */
+export function checkOrganization(organization, rosterIds) {
+  const onDisk = new Set(rosterIds);
+  const declared = new Set(organization === null ? [] : organization.rosters.map((item) => item.id));
+  const missing = [...declared].filter((id) => !onDisk.has(id)).sort();
+  const undeclared = [...onDisk].filter((id) => !declared.has(id)).sort();
+  const archived = organization === null
+    ? []
+    : organization.rosters.filter((item) => item.status === "archived" && onDisk.has(item.id)).map((item) => item.id).sort();
+  return {
+    declared: declared.size,
+    present: onDisk.size,
+    missing,
+    undeclared,
+    archived,
+    status: organization === null ? "absent" : missing.length > 0 ? "incomplete" : "ok",
+  };
+}
+
+/**
+ * 把交叉核对结果折成诊断。
+ *
+ * @param {object|null} organization
+ * @param {object} check {@link checkOrganization} 的返回值
+ * @param {string} file 组织文件相对路径
+ * @returns {object[]}
+ */
+export function organizationDiagnostics(organization, check, file) {
+  const diagnostics = [];
+  if (organization === null) return diagnostics;
+  if (check.missing.length > 0) {
+    diagnostics.push(
+      diagnose(
+        "error",
+        "organization-roster-missing",
+        file,
+        `组织声明了 ${check.missing.length} 份档案但库里找不到：${check.missing.join(", ")}。` +
+          "要么把目录加回来，要么把它们从 organization 里删掉——组织页不能比磁盘更乐观。",
+      ),
+    );
+  }
+  if (check.undeclared.length > 0) {
+    diagnostics.push(
+      diagnose(
+        "warn",
+        "organization-roster-undeclared",
+        file,
+        `库里有 ${check.undeclared.length} 份档案没在组织里登记：${check.undeclared.join(", ")}。` +
+          "它们仍会被加载，但组织页看不到它们——补一行登记，或确认它们不该在这里。",
+      ),
+    );
+  }
+  if (check.archived.length > 0) {
+    diagnostics.push(
+      diagnose(
+        "info",
+        "organization-roster-archived",
+        file,
+        `已归档但仍在库里的档案：${check.archived.join(", ")}。归档只是声明，不影响加载。`,
+      ),
+    );
+  }
+  return diagnostics;
+}