@stofone/dsh-agent-roster 0.7.0 → 0.8.1

package/CHANGELOG.md

@@ -4,6 +4,53 @@
 
 ## [Unreleased]
 
+## [0.8.1] - 2026-11-03
+
+### Moved to the `dsh-agent-roster` organization
+
+- **The repository now lives at `dsh-agent-roster/dsh-agent-roster`** (GitHub keeps redirects from
+  the old owner, so existing clones and links keep working). Nothing about the format, the tools or
+  the published package name changes.
+- **The default registry source follows the move**: `lib/remote.js` asks
+  `https://raw.githubusercontent.com/dsh-agent-roster/dsh-agent-roster/main/index/registry.json`,
+  so a fresh install that has not configured `indexes` does not depend on a redirect.
+- **Package metadata and schema `$id`s point at the new home** (`package.json` homepage /
+  repository / issues, and the four `schema/*.v1.schema.json` files), so editors and npm resolve
+  the canonical location instead of a redirect.
+
+## [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 +310,8 @@
 - 工具返回值含 `undefined` 键，运行时按 `value is not lossless JSON` 整次拒绝；缺失值统一写 `null`，
   且所有返回值先过 `lib/json.js#lossless`。
 
-[Unreleased]: https://github.com/STofone/dsh-agent-roster/compare/v0.7.0...main
-[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
+[Unreleased]: https://github.com/dsh-agent-roster/dsh-agent-roster/compare/v0.8.1...main
+[0.8.1]: https://github.com/dsh-agent-roster/dsh-agent-roster/releases/tag/v0.8.1
+[0.8.0]: https://github.com/dsh-agent-roster/dsh-agent-roster/releases/tag/v0.8.0
+[0.7.0]: https://github.com/dsh-agent-roster/dsh-agent-roster/releases/tag/v0.7.0
+[0.2.0]: https://github.com/dsh-agent-roster/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 |
@@ -266,7 +300,7 @@ Rosters can be shared: keep one or more of them in a GitHub repository, register
 repository's `index/registry.json`, and anyone who subscribes can see them in the panel and pull them locally.
 
 - **Subscribing**: set `indexes` to an `https://…/registry.json` URL or `npm:pkg` (reads `registry.json` from the
-  package). Empty means the official source, `STofone/dsh-agent-roster`'s `index/registry.json`; an explicit `false`
+  package). Empty means the official source, `dsh-agent-roster/dsh-agent-roster`'s `index/registry.json`; an explicit `false`
   is the only way to disable remote sources entirely.
 - **How often it refreshes**: TTL **one hour** — that is the unauthenticated GitHub budget of 60 requests/hour.
   `?refresh=1` (or the tools' `refresh`) bypasses the cache, throttled to one try per 60 seconds so the quota is not
@@ -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
+```
+
 ## 工具
 
 | 工具 | 作用 |
@@ -253,12 +287,14 @@ notes: 建队前先确认成员会话可用。
 别人订阅后就能在面板里看到并一键拉到自己机器上。
 
 - **订阅方式**：设置里 `indexes` 填 `https://…/registry.json`，或 `npm:pkg`（从 npm 包的 `registry.json` 读）。
-  留空 = 只用官方源 `STofone/dsh-agent-roster` 的 `index/registry.json`；显式写 `false` 才彻底不连远端。
+  留空 = 只用官方源 `dsh-agent-roster/dsh-agent-roster` 的 `index/registry.json`；显式写 `false` 才彻底不连远端。
 - **多久更新一次**：TTL **一小时**——等于未认证 GitHub 的 60 次/小时配额。`?refresh=1`（或工具的 `refresh`）
   可绕过缓存，但 60 秒内最多一次，避免把配额烧光。拉取失败时沿用上次缓存并在页面上写明「缓存（拉取失败）」。
 - **拉取到本机**：写入是幂等的，四种结果都会报给你——
   `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,15 +2,15 @@
   "$schema": "../schema/registry.v1.schema.json",
   "kind": "dsh-agent-roster-registry/v1",
   "version": 1,
-  "generatedAt": "2026-10-30T00:00:00.000Z",
-  "generator": "STofone/dsh-agent-roster (hand-maintained; verified by .github/workflows/registry.yml)",
-  "source": "https://github.com/STofone/dsh-agent-roster",
+  "generatedAt": "2026-11-02T17:00:43.713Z",
+  "generator": "dsh-agent-roster/dsh-agent-roster (hand-maintained; verified by .github/workflows/registry.yml)",
+  "source": "https://github.com/dsh-agent-roster/dsh-agent-roster",
   "collections": [
     {
       "id": "agent-roster-examples",
       "title": "官方起步档案集",
       "description": "评审与调研两套起步档案，用来验证格式、桥接与核对链路；也可以直接复制成自己的档案。",
-      "repo": "github:STofone/dsh-agent-roster",
+      "repo": "github:dsh-agent-roster/dsh-agent-roster",
       "ref": "main",
       "path": "examples",
       "rosters": [
@@ -26,7 +26,51 @@
       "maintainers": [
         "STofone"
       ],
-      "homepage": "https://github.com/STofone/dsh-agent-roster#examples"
+      "homepage": "https://github.com/dsh-agent-roster/dsh-agent-roster#examples"
+    },
+    {
+      "id": "agent-roster-collective",
+      "title": "自撰团队档案合集（21 套 · 63 名成员）",
+      "description": "覆盖评审、事故响应、数据、文档、发布、研究等常见协作分工的 21 套档案，全部由本项目自撰（未复制任何上游文本），可直接复制改成自己的。",
+      "repo": "github:dsh-agent-roster/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/dsh-agent-roster/dsh-agent-roster/tree/main/orgs/agent-roster-collective"
     },
     {
       "id": "agent-teams",

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";