@pioneer_zmc/dsh-workbench 0.2.1

package/skills/specdev-business/references/change.md

@@ -0,0 +1,117 @@
+# 已有业务修改指引
+
+本指引管"已有业务或其产物的再次修改"——业务完整交付过当然算，还在半路的也算：图没画、
+证据没补、快照没存过，都不挡进入；本次改什么，就按需读取相关材料。缺的产物（图、详情、
+证据、快照等）只在影响本次修改的正确性或产品操作时才补齐，不要求先凑齐整套资产。首次实现
+见 [implementation.md](implementation.md)，首次证据补录与差异核对见
+[evidence-review.md](evidence-review.md)；本指引不重复它们的规则，只管"再次修改"多出来的事。
+
+一句话定义（公共版）：
+
+> 修改已有业务时，识别本次影响范围，更新受影响的实现和说明，验证新行为与相关旧行为，
+> 并保留可追溯的历史。
+
+**规则分层**（本指引只写第一类，其余引用或让位，不搬运）：
+
+| 类型 | 例子 | 放在哪里 |
+|---|---|---|
+| 通用可靠性要求 | 不覆盖已有工作、不遗漏相关改动、验证修改结果、如实报告差异 | 本指引主流程 |
+| Archify 产品约束 | 节点 ID 与详情对应、证据按固定提交读取、快照保存范围 | 引用现有产品约定（project-contract.md 等） |
+| 项目的工作习惯 | 每个小功能单独批准、修复轮数上限、页面由谁验收 | 目标项目自身规则；冲突时按目标项目执行 |
+
+## 1. 确认当前状态与本次目标
+
+- 阅读与本次修改**相关**的规格、代码、图、详情和证据；有疑问再追查历史，不默认通读
+  整个业务。
+- 分清四样东西：**文档现在怎么规定、代码实际上怎么做、本次要求改成什么、哪些还不清楚**。
+  旧文档可能过时，不能直接当成实现事实——代码与文档的一致性用
+  [evidence-review.md](evidence-review.md) §4 的核对思路确认，不凭文档自述。
+- 动手前检查已有未提交改动，避免覆盖或混入别人的工作；发现来源不明的改动怎么处置，
+  按目标项目规则。
+- 用户已明确授权的修改直接推进；只有信息不足、要求冲突或范围扩大时才补充确认。
+
+## 2. 判断影响范围与验收方式
+
+- 说明哪些规则（FR/AC）、代码、节点、详情和证据可能受影响，以及用什么证明修改完成
+  ——这就是本次修改的影响面与验收口径，动手前先摆出来。
+- 简单修改几句话说清即可，不强制新增计划、任务单或审批表（与
+  [implementation.md](implementation.md) §1 同一口径）；改动跨模块或影响面广时按目标
+  项目规则落文件。
+- 目标是一个**完整、可验证的变更**：一次业务修改同步几个相关文件很正常，不按文件
+  数量机械拆分，也不把无关文件捎带进来。
+
+## 3. 确认修改前的状态可以追溯
+
+- 复用已有 Git 提交或管理页快照即可；确有尚未保存、需要保留的状态时，再提示处理。
+- 不要求每次修改前新建快照或空提交。两样东西用途不同：**Git 留存代码状态，管理页
+  快照登记图的版本**（三个图文件＋阶段，见 [project-contract.md](project-contract.md) §4）。
+
+## 4. 按影响范围修改和同步
+
+不要求每次改齐"规格、代码、测试、图、详情、证据"六样，按修改情况取用：
+
+| 修改情况 | 通常需要处理 |
+|---|---|
+| 文字纠错，业务含义未变 | 修正文案；检查引用是否受影响 |
+| 代码重构，外部行为未变 | 验证原有行为不变；检查相关证据是否仍准确 |
+| 业务规则或流程变化 | 更新规格、实现和必要测试；同步受影响图与详情 |
+| 补齐已有实现的出处 | 查证并更新证据（evidence-review.md §2），不顺带重画业务图 |
+
+- **ID 稳定的边界**：语义未变的业务、图、节点、规则 ID 保持稳定
+  （[workflow.md](workflow.md) §3.2、[specification.md](specification.md) §5——规则编号
+  作废不回收，新增续编新号）；真正删除、替换或拆分的节点，同步处理关联引用（详情
+  分节、证据指向、连线），**不为保留编号而让旧 ID 偷换含义**。
+- **证据沿用 4b 规则**：按引用提交查证内容和行号，无法核实的明确标记。旧证据按固定
+  提交读取，**不因后续代码变化自动失效**——要检查的是这条证据还能不能支撑当前描述：
+  相关实现变了才按 evidence-review.md §3 顺序更新引用（先提交实现、再提交证据），
+  无关改动不必把证据刷成最新提交。
+
+## 5. 验证本次修改与相关旧行为
+
+- 不只验证新要求满足，也验证**受影响的原有行为**仍然成立；验证范围由依赖关系决定，
+  不简单等同于"改了哪几行"。
+- 图源未变且已有校验回执仍适用时复用，不重跑；图源变化时按
+  [workflow.md](workflow.md) §4 重新校验（五判据全过才算）。
+- 规格、图、详情、源码之间仍有差异就如实报告（差异报告用
+  [evidence-review.md](evidence-review.md) §5 的六列格式），不能靠删条件或改描述让
+  结果看起来一致。
+
+## 6. 交付变化与未完成项
+
+报告四件事：
+
+1. **改了什么及原因**——原因写在交付报告或提交说明里，不强制另建变更日志；
+2. **影响哪里**——受影响的规则、代码、图、详情、证据清单；
+3. **如何验证及结果**——未验证项如实标注；
+4. **还有什么未决或未验证**。
+
+提交与发布遵循目标项目的授权规则；需要在管理页登记新版本时，保存仍由用户亲手完成
+（[project-contract.md](project-contract.md) §4）。
+
+## 7. Archify 特有事实（引用，不重复发明流程）
+
+- 保存操作由用户在管理页完成，本指引只提醒不代存（project-contract.md §4）。
+- 历史快照保留当时的图、详情和证据；业务文档及部分名称信息不随快照回退——看历史
+  快照要核对当时的业务文档时，按快照指向的提交另行用 Git 核对。
+- 保存可能返回已有快照（三个图文件与阶段和已有快照相同时），不能承诺"每次修改都会
+  产生新快照"；以实际返回的快照为准。
+- 未经核实的内容不因进入修改流程就被标成已实现——四类标注口径不变
+  （project-contract.md §2.5、evidence-review.md §4）。
+
+## 8. 边界
+
+- 本指引管已有业务或其产物的再次修改；从零开始的新业务从 SKILL.md 设计段主流程进入，不走本文。
+- 拿不准归属的差异（该改代码还是该改规格）不自行选择，带候选交用户裁决
+  （与 evidence-review.md §6 同一条纪律）。
+- 本指引自身添加新规则前先问三件事：**它解决了什么实际问题、现有规则为何没解决、
+  最轻的补救是什么**——单个项目的偏好留在项目规则里，重复出现、能解释清楚的共性问题
+  才进本指引。
+
+## 9. 来源与状态
+
+- 依据：2026-09-18 改版方案（**AI 建议、作者采纳定稿**——规则三分法、一句话定义、
+  六步框架、四情形表与"旧证据不因代码变化自动失效"的存续口径均出自该方案，含同日
+  评审三处修正）。
+- 状态：三情形纸面推演已过，评审修正后自 SKILL 修改段入口重推；实际修改已于
+  2026-09-18 在真实业务（login-app 登录业务加组织维度）实跑验证，含评审三处修正
+  后的复验（12 档测试全绿、showcase 五判据重过）。

package/skills/specdev-business/references/evidence-review.md

@@ -0,0 +1,125 @@
+# 证据补录与差异核对指引
+
+本指引管"实现完成之后"这一段：源码证据怎么查证落笔、证据与实现的提交顺序怎么走、
+规格／图／详情／源码怎么核对、差异报告怎么交付。evidence.json 的字段合法性总表见
+[project-contract.md](project-contract.md) §2.6（单一来源，本文不重复）；实现段的方案
+与任务见 [implementation.md](implementation.md)。
+
+## 1. 何时进入
+
+- 实现已完成、必要测试已跑、改动已按授权提交——之后才补证据，不为补证据打断实现。
+- 描述已有实现（源码早已在某个历史提交里）时，直接按 §2 查证引用，不新做实现。
+
+## 2. 证据条目怎么写（先查证，再落笔）
+
+七个字段一条不缺：`id`、`label`、`repo`、`commit`、`path`、`fromLine`、`toLine`。
+插件对缺 `id`／`label`、省略 `repo` 只降级显示不报错；本 Skill 约定写全——`repo`
+固定写 `"."`，明示同仓引用。每条落笔前逐项查证，不估：
+
+- **commit**：`git rev-parse <提交>` 取全 40 位小写十六进制；不写短哈希、`HEAD`、
+  "最新"这类会漂移的写法；提交必须能在图所在仓库解析。
+- **path**：仓库根相对路径、正斜杠（如 `backend/app/routers/…`）；不写盘符、
+  反斜杠、开头的 `/` 与 `..` 段。
+- **行号**：按**该提交上**的文件核对——`git show <commit>:<path>` 数行；工作区文件
+  可能已变，拿工作区行号估是错的。文件按 `\n` 切行、末尾空行不算一行；行号越界
+  整条报错，插件不自动收紧范围。
+- **id／label**：id 用短横线英文（如 `eligibility-core`），同一图内不重复；label 写
+  人话＋行范围（如"资格判定核心（12–16 行）"），让作者不点开源码就知道这条指什么。
+
+单条示例（虚构业务，仅示意形状；真实使用时提交号须替换为查证过的真值）：
+
+```json
+{
+  "id": "eligibility-core",
+  "label": "资格判定核心（12–16 行）",
+  "repo": ".",
+  "commit": "<git rev-parse 查证过的 40 位十六进制提交号>",
+  "path": "src/activity-eligibility.js",
+  "fromLine": 12,
+  "toLine": 16
+}
+```
+
+引用范围取"能独立说明一件事"的最小连续段，不为凑数引用整个文件；条目数量以覆盖
+本图相关规则与节点为准，不设指标。
+
+## 3. 提交顺序（A→B）
+
+1. **先提交实现，得提交 A**：获批实现按授权提交；证据要指向的就是 A。
+2. **再提交证据，得提交 B**：把指向 A（或既有历史提交）的条目写进 evidence.json，
+   同步 details.md 受影响节点的四类标注（如【设计】改【实现】）并在正文注明出处
+   （写法如"（证据 eligibility-core）"，见 project-contract.md §2.5 约束 7），一并提交。
+3. **验收后提醒保存**：保存检查要求三个图文件与最新提交一致（project-contract.md
+   §4）——证据不先提交，作者存不了。差异报告（§5）交作者、验收与差异裁决完成后，
+   才提醒作者在管理页亲手保存**实现版**。**快照锚定的提交不预设是 B**：三个图文件
+   与阶段和已有快照相同时，保存返回的是那份旧快照；否则锚定保存时确认的 HEAD——
+   B 之后又有别的提交时也不是 B。保存结果以实际返回的快照为准；要核对"当时的
+   业务文档"，按返回快照指向的提交去核对（project-contract.md §4）。
+
+- **源码已在历史提交**：直接引用那个提交，不为凑证据造无意义提交。
+- **禁止自指**：不试图把"包含 evidence.json 自身的那个提交"填进 `commit`——提交前
+  拿不到号，提交后文件已变，逻辑上不可能；条目只能指向写入它之前已存在的提交。
+- 证据条目是对代码事实的记录，差异裁决不改变条目本身；裁决后代码再变，才按 §6
+  更新条目再提交。
+- 实现未改变图所描述的行为时，不重画图、不重跑制图校验（SKILL.md 实现段入口）；
+  实现改变了图所描述的行为时，图与规格的同步属修改流程（[change.md](change.md)），先如实报差异。
+
+## 4. 四方核对（只读）
+
+对象：业务规格（FR／AC 编号）× 图（节点与分支）× details.md（四类标注）× 源码
+（证据切片）。**核对阶段不改任何文件**——差异先报告，经作者裁决后再改。三类检查
+（思路借自 Spec Kit analyze 的覆盖与冲突检查，见 source-map.md）：
+
+- **覆盖**：与本图相关的每条规则、每个关键节点，必居四态之一——有证据支持
+  （已有实现）、【设计】（拟定设计）、未实现（**查证后确认**代码里没有）、
+  【未核实】（代码可能存在，但本轮没查证到足够证据，写清缺什么）。没查证到的
+  只能标【未核实】，不断言"未实现"。反向，每条证据都要能指回某条规则或节点——
+  指不回的（证据孤儿）列为问题。
+- **冲突**：证据与规格条文矛盾（规格写"不得"、代码却允许）、两条证据互相矛盾、
+  图上的走向与代码实际走向不一致——逐条列出，不裁决、不改文案抹平。
+- **缺口**：规格没写、代码却做了的夹带行为；图上有、代码没做的节点。实现期发现
+  业务缺口本应停下报告（implementation.md §4），这里是事后兜底再扫一遍。
+
+不对差异做严重度分级——差异一律交作者裁决，不用 CRITICAL／HIGH 那套机器分级
+排优先级。
+
+## 5. 差异报告（六列，随实现段交付报告给出）
+
+| # | 规则／节点 | 设计要求 | 实现事实与出处 | 测试结果 | 未核实项 | 待作者裁决 |
+|---|---|---|---|---|---|---|
+
+- 每行对应一条规则（FR-xxx／AC-xxx）或一个图节点。核对过且一致的行也列出——让
+  作者看到覆盖范围；量大时先与作者确认核对范围，但"没进表"不得被读成"没有差异"。
+- **三分开**：实现事实列只写代码是什么（出处＝证据 id，或 `path@提交前 8 位:行号`）；
+  测试结果列只写跑了什么、结果如何，没跑写"未测"；业务判断（算不算符合）只出现在
+  待裁决列与表尾总判断，不混进事实列。
+- **未核实项**：没能核实的如实写（无证据、行号未查、环境未跑），不装成已核对。
+- 表尾给总判断：核实一致 X 条、不一致 Y 条、未核实 W 条、待裁决 Z 条——未核实
+  单列，不并进"核实一致"；没有差异如实写"无差异"，不硬凑行；有差异不靠改文案
+  抹平（SKILL.md 守恒关系第 2、3 条）。
+
+示例（虚构业务，仅演示格式；提交号为插件虚构样本仓里的值）：
+
+| # | 规则／节点 | 设计要求 | 实现事实与出处 | 测试结果 | 未核实项 | 待作者裁决 |
+|---|---|---|---|---|---|---|
+| 1 | FR-006 | 未验证账户提交报名必须被拒 | 账户状态先于重复报名判定，未验证直接拒（证据 eligibility-core，src/activity-eligibility.js@3fda7dc3:12–16） | 单测 2 例通过（未验证拒、已验证放行） | 无 | 无 |
+| 2 | send_confirmation | 确认消息分座位与候补两种文案 | 【设计】节点未实现（设计如此），无代码 | 未测 | 无 | 无 |
+
+默认不落独立报告文件；图多或作者要求留档时，落位与命名先与作者确认。
+
+## 6. 裁决后怎么办
+
+- 作者对差异逐条裁决后，按批准范围改：改代码、补证据，或修订规格／图（规格走
+  specification.md，图按 [workflow.md](workflow.md) §3–§4 修改并重跑校验，完整修改
+  流程见 [change.md](change.md)）；改完重新核对受影响的行，仍按 §3 顺序提交，
+  保存实现版仍由作者亲手点。
+- 拿不准归属的差异（该改代码还是该改规格）不自行选择，作为待裁决问题带着候选给出。
+
+## 7. 边界
+
+- 不新增节点级证据 UI：第一版用图下方现有证据面板读固定提交代码；页面交互扩展
+  另行裁决。
+- 不编造真实业务证据：本文示例均为插件自带虚构样本或占位符；真实证据必须逐条按
+  §2 查证。
+- 本指引经插件源码静态核对（`src/core/evidence.ts` 等），并已在真实登录业务实跑
+  验证（2026-09-18）；规格修订联动与图同步见 [change.md](change.md)。

package/skills/specdev-business/references/implementation.md

@@ -0,0 +1,67 @@
+# 实现段指引
+
+本指引管"业务规格获批之后、动手实现"这一段：什么时候需要方案与任务文件、怎么写、怎么执行、怎么交付。
+模板管"长什么样"（`assets/plan-template.md`、`assets/tasks-template.md`），本指引管"怎么写、怎么执行"。
+
+## 1. 何时进入、何时落文件
+
+- **进入条件**：业务规格已获作者批准，且作者明确批准了本次实现范围。标着【待裁决】的事项
+  不得当作已批准规则进入实现。
+- **三问是硬要求，文件不是**：任何实现开工前必须先答清——**怎么实现？影响哪里？每步验收什么？**
+  ——并经作者同意。答不清说明规格或方案还不成熟，先补齐再动手。
+- **按复杂度落文件**：简单功能（一两处小改、无新规则）不强制写 plan.md／tasks.md，
+  在既有计划或交付报告里把三问答清即可，不为仪式增加文件。改动跨模块、影响面广、
+  或作者要求留档时才落文件；落位与命名开工时与作者确认，不自行新建目录约定。
+- **不默认凑齐配套文件**：调研记录、数据模型、接口契约、快速上手指南都不作为默认必交文件。
+  普通设计解释写进方案相应章节；确有需要独立成文的（如接口契约变更），先说明原因、
+  纳入获批范围再写。关键业务决定不落这些文件——回业务规格。
+
+## 2. 方案（plan）怎么写
+
+- **职责边界**：业务规格定规则（FR-xxx 是什么）；方案只解释"怎么实现、为什么这么选、影响哪里"。
+  方案引用规则编号，不重新定义同名业务规则——发现规格没写清的，回规格补或标【待裁决】，
+  不在方案里另立规矩。
+- 方案必须答清开工三问（与 §1 同一组），对应模板：**§2.1 怎么实现**（做法与数据流，
+  不贴大段代码）、**§2.3 影响哪里**（会动的文件、模块、接口，以及既有图／详情／证据
+  是否需要同步——先如实列出，同步流程见 [change.md](change.md)）、**§5 每步验收什么**（验证计划总览，
+  含作者亲验项）。「为什么这么选」（§2.2 候选方案与放弃理由，关键决定按
+  「决定／理由／放弃的替代」留痕）继续保留为方案解释，不属于三问、不得省略。
+- 技术上下文只填与本次相关的项；未定的技术前提标【待澄清】，集中问作者，不猜。
+- 验证计划在方案里给总览（含作者亲验项）；逐任务的验收放任务清单。
+
+## 3. 任务清单（tasks）怎么写
+
+- 从**已批准**的方案拆解；每个任务必须"能做、能验"：写清做什么（含文件路径）、
+  完成后拿什么证明（「验」）、依据哪条规则（「据」）。
+- **约束逐字进任务**：涉及数量上限、格式、权限、时间窗等关键约束时，把规格里的约束原文
+  逐字抄进任务描述，不留实现期自由裁量；除引用编号外，关键数字也照抄，不只写"按规格"。
+- 编号从 T001 连续分配、一经使用不改号；默认串行执行，有依赖在条目注明——不引入并行标记
+  与分工策略。
+- **测试规则**：业务逻辑与缺陷修复必须带必要的相关测试；纯样式、文案、配置类改动可用
+  格式检查、预览或相关单档验证。不因"先写代码后写测试"推倒重来，也不为通过而放宽检查。
+
+## 4. 执行纪律
+
+- 一次只做一个获批功能；只动范围内和相关文件，不顺带扩大。
+- 实现中发现业务缺口（规格没说、两种做法都合理）先停下来报告，不替作者拍板。
+- 同一问题累计两轮修复仍未解决即停，报告事实、已试方法与未解决点，与作者商量。
+- 实现与规格、图、详情不一致时如实摆出差异交作者裁决，不改文案抹平。
+- 提交只在获批分支、只含本功能相关内容；页面效果交作者本人查看验收。
+
+## 5. 交付前自查
+
+- [ ] 三问已答清并获作者同意（独立文件或等价表达）。
+- [ ] 每个任务有「验」且逐条执行、结果如实（含失败与未验项）。
+- [ ] 业务逻辑与缺陷修复带了必要测试；测试结果如实报告。
+- [ ] 未重新定义规格规则；新发现的规则去了规格或已标【待裁决】。
+- [ ] 影响面中需要同步的图／详情／证据已处理或已列为待办。
+- [ ] 差异与未决项如实列出，无则写"无"。
+
+自查通过后按此报告：任务完成情况（含失败与未验项）、测试命令与结果、差异与未决项（差异明细用 [evidence-review.md](evidence-review.md) §5 的六列表展开）、提交状态；页面类改动附入口与检查点。
+
+## 6. 边界
+
+- 本指引只管方案与任务的编写执行；实现完成后的证据补录与规格／图／详情／源码核对见
+  [evidence-review.md](evidence-review.md)，保存实现版快照由作者在管理页亲手完成
+  （[project-contract.md](project-contract.md) §4），已有业务的修改同步见 [change.md](change.md)。
+- 不照搬 Spec Kit implement 命令的自动执行流程、扩展 hooks 与并行执行机制。

package/skills/specdev-business/references/project-contract.md

@@ -0,0 +1,211 @@
+# 管理页六类文件与节点详情约定
+
+本约定管三件事：一张图交付时落在业务仓库的哪些文件里、每个文件长什么样才合法、节点详情（details.md）怎么写。图的画法与校验见 [workflow.md](workflow.md)（workflow.json 本身不在本文重复）；业务规格怎么写见 [specification.md](specification.md)。依据插件源码与 README D2 节静态整理（2026-09-17），首次真实使用在计划步骤 2。
+
+## 1. 目录总览与路径基准
+
+插件只认一种组织方式（约定根 `docs/specdev/`，业务仓库根相对）：
+
+```text
+<业务仓库>/
+  docs/specdev/
+    project.json                        # 项目（整仓一份）
+    <业务id>/business.json              # 业务（每业务一份）
+    <业务id>/<图id>/chart.json          # 图说明（每图一份）
+    <业务id>/<图id>/workflow.json       # 图源（Archify workflow JSON）
+    <业务id>/<图id>/details.md          # 节点详情
+    <业务id>/<图id>/evidence.json       # 源码证据引用
+  docs/…、src/…                         # 业务文档与源码留在原位，只引用不搬动
+```
+
+- **路径基准**：business.json 里 `docs` 数组、evidence.json 里 `path`，一律写**业务仓库根相对路径**（正斜杠分隔），不是相对 `docs/specdev/`，也不写盘符绝对路径。
+- **id 即目录名**：业务 id、图 id 就是各自的目录名；插件按目录遍历，说明文件里的 `id` 与目录名不一致会直接标记说明文件问题。
+- **业务 id 与图 id 的硬限制**：必须匹配 `^[A-Za-z0-9][A-Za-z0-9._-]*$`（字母或数字开头，其余只能是字母、数字、点、下划线、连字符）——这是管理页路由与 API 的统一校验（`src/dsh/index.ts` 的 `ID_PATTERN`）。说明文件字段检查只看 id＝目录名，**id 不合规的业务/图照样进不去页面、调不了 API**：目录名用中文，即使说明文件全对也访问不了。
+- **命名建议（硬限制之内从严）**：沿用 workflow 节点 id 的风格——字母开头，可含数字、下划线、连字符，不用点，不写中文、空格、斜杠。快照标签名形如 `specdev/<图编号>/<版本标识>`，图 id 会进标签名，保持朴素少踩坑。
+- **图编号全项目唯一**：跨业务也不允许重复。重复时两边都标记编号冲突、该图阅读停用——历史快照按图编号归组，重了分不清归属。
+
+## 2. 六类文件逐个约定
+
+下例合成一个最小项目（一段业务、一张图），字段值是编的，形状对齐插件自带合法样本（`sample/generate.mjs`）与源码校验规则。"最小合法"指缺了会报错、再少写一个字段就不成立；**已有文件只改要改的字段，其余内容原样保留，不整份重建**（插件只校验下表字段，不拒绝额外字段，静态核对结论）。
+
+### 2.1 project.json（项目）
+
+```json
+{
+  "schema": "specdev/project/1",
+  "name": "示例项目名"
+}
+```
+
+| 字段 | 必填 | 含义 |
+|---|---|---|
+| `schema` | 是 | 固定 `"specdev/project/1"`，一字不差 |
+| `name` | 是 | 项目显示名（首页标题），非空 |
+| `description` | 否 | 项目一句话说明 |
+
+规则：整仓只有这一份；`schema` 不对或 `name` 缺失时首页直接报错。项目里已有其他字段（如 `description`、后续业务信息）保留不动。
+
+### 2.2 business.json（业务）
+
+```json
+{
+  "schema": "specdev/business/1",
+  "id": "activity-registration",
+  "name": "活动报名",
+  "intro": "一句话业务介绍。",
+  "docs": ["docs/活动报名说明.md"]
+}
+```
+
+| 字段 | 必填 | 含义 |
+|---|---|---|
+| `schema` | 是 | 固定 `"specdev/business/1"` |
+| `id` | 是 | 业务 id，**必须与目录名一致** |
+| `name` | 是 | 业务显示名，非空 |
+| `intro` | 否 | 业务介绍（业务页展示） |
+| `docs` | 否 | 业务文档路径数组：仓库根相对路径，引用原位文档，不复制 |
+
+规则：
+
+- **文档留在原位**：`docs` 只登记路径；业务文档放仓库哪里都行，管理页按路径去读。
+- **页面只读声明过的路径**：不在 `docs` 里的路径，管理页拒绝读取；声明了但工作区文件不存在，会明确报"文档不存在"。所以每条路径写完自查文件在不在。
+- 已有业务再添图时，这份文件通常不用动。
+
+### 2.3 chart.json（图说明）
+
+```json
+{
+  "schema": "specdev/chart/1",
+  "id": "submit-review",
+  "name": "提交复核流程",
+  "summary": "一句话图摘要。"
+}
+```
+
+| 字段 | 必填 | 含义 |
+|---|---|---|
+| `schema` | 是 | 固定 `"specdev/chart/1"` |
+| `id` | 是 | 图编号，**必须与目录名一致，且全项目唯一** |
+| `name` | 是 | 图显示名（业务页图列表、阅读页标题） |
+| `summary` | 否 | 图摘要（图列表展示） |
+
+规则：新建图前先确认这个编号没被别的业务用掉（含历史遗留目录）。
+
+### 2.4 workflow.json（图源，同图目录）
+
+- **原生 Archify workflow JSON**：字段、制作流程、showcase 校验五判据全部见 [workflow.md](workflow.md)，本文不重复。
+- **不自创插件没约定的业务字段**：插件把这份文件原样交给 Archify 渲染，业务语义走 details.md 与 evidence.json；Archify schema 也不允许额外字段，塞了只会校验失败。
+- 缺失时阅读页明确报"缺图文件"，不给空白页；文件超过 2MB 读取上限会报"读不开"——图源保持精炼，不往里塞大段填充。
+
+### 2.5 details.md（节点详情，同图目录）
+
+分节约定（插件的解析规则）：
+
+- 每节解释对应节点的**职责、条件、先后顺序、失败后果**，并给**业务文档出处**（章节或编号）；文档没定的走向见写作约束第 8 条。
+- 一级标题 `#`（首个分节之前）＝ 图的总说明；**首个分节之前只有这一行标题会显示**，其余前言（引用块、说明段）一律被忽略——阶段声明这类要紧话写进标题行（样例即"……（设计版）"）或各节前缀，不放前言。
+- 每节以 `## <节点id>` 开头；节内**不是完整 Markdown**，页面只按简单规则显示：空行分段、`-`／`*`／`数字.` 简单列表、`**加粗**` 与 `` `行内代码` ``。链接、表格、引用块、三级及更深标题不会按 Markdown 渲染——复杂语法要么按普通文字原样显示、要么被忽略，重要信息别依赖这些格式。
+- **分节标题只写纯节点 id**：插件把 `## ` 后第一个空白前的词当节点 id，其余当附注。写成中文（如 `## 提交报名`）不报错，但该节与图上节点（英文 id）对不上——点节点会显示"没有这个节点的说明"，等于白写。
+- 同一节点 id 写多节：不算错，但详情弹层只会显示第一份并提示；不要写多节。
+- 图上没有、详情里写了的 id：容忍照常显示（删节点后旧详情不必同步删）；图上有、详情没写的：插件列为"没写说明"，不算错误——**这只是读取降级，不是交付标准**：本 Skill 交付要求分节覆盖图上全部节点（见检查清单第 4 项）。
+- 正文代码围栏（``` 或 ~~~）不会截断分节（围栏里的 `#`／`##` 不当标题），但围栏符号本身也只按普通文字显示，展示能力以上面"简单规则显示"一条为准。
+
+最小合法示例（对应一张两节点图；注意首个 `##` 之前只有标题行会显示）：
+
+```markdown
+# 提交复核流程 · 节点详情（设计版，尚无源码证据）
+
+## submit_registration
+【设计】学生在门户填写报名表并提交；表单只收集必要字段。
+
+## check_eligibility
+【设计】校验账户状态与重复报名，判定是否受理；不通过转拒绝，不落记录。
+```
+
+**写作约束**（摘自 archify-reader《详情内容规范》2026-09-05 作者裁决，适配到本文件；读者设定不变）：
+
+1. **读者是看过图、没看过代码的业务裁决者**。不许擅自换成技术读者。
+2. **正文零代码标识符**：变量、函数、表名、配置名、状态码、HTTP 方法不进白话正文；源码核对走 evidence.json（源码引用单列），不放正文里。
+3. **按真实执行顺序讲**：先做什么、后做什么，一步一句事实——顺序本身就是检验点，逻辑不对读者要能看出来。谁、对什么数据、做了什么动作、得到什么结果；必要术语第一次出现给一句白话注释；客观白描，不修饰、不科普、不"专业腔"总结。
+4. **失败分支也是事实**：这一步出错会怎样、影响谁；禁止只写成功路径。没跑过的失败情景不得写成已验证事实。
+5. **首尾承接**：开头说从哪个节点接过什么、前面完成了什么；结尾说本次在哪结束、留下什么结果、谁在什么条件下进入哪个节点。入口/终点如实说明，不为填格式虚构上下游。
+6. **依赖就地解释**：不只说"现有规则""前面处理过"——先写当前判断必需的一句话规则或数据来源，再引用对应节点；多个分支时明确列出条件。
+7. **四类分开说**：拟定设计、已有实现、未实现、未核实，分开标注不混写（示例用【设计】前缀；标记写法可自定，分开说不可省）。
+8. **文档未定义的分支列为问题，不以图补定规则**：业务文档没定的走向，在详情或交付报告里列为待裁决问题，不在图和详情里替业务做决定（与 workflow.md §3 出处规则同一条纪律）。
+
+### 2.6 evidence.json（源码证据引用，同图目录）
+
+设计阶段的合法形态就是**空清单，不伪造**：
+
+```json
+{
+  "schema": "specdev/evidence/1",
+  "refs": []
+}
+```
+
+描述已有实现时才补引用条目（字段与规则经 `src/core/evidence.ts` 静态核对）：
+
+```json
+{
+  "schema": "specdev/evidence/1",
+  "refs": [
+    {
+      "id": "eligibility-core",
+      "label": "资格判定核心（12–16 行）",
+      "repo": ".",
+      "commit": "<查证过的 40 位十六进制完整提交号>",
+      "path": "src/activity-eligibility.js",
+      "fromLine": 12,
+      "toLine": 16
+    }
+  ]
+}
+```
+
+| 字段 | 必填 | 规则 |
+|---|---|---|
+| `id`／`label` | 建议 | 引用标识与显示名；缺省显示"refs[N]／引用 N+1" |
+| `repo` | 可选 | 第一批只支持同仓：省略或写 `"."`；写别的整条报错 |
+| `commit` | 是 | 40 位十六进制完整提交号（短哈希不行） |
+| `path` | 是 | 仓库根相对路径、正斜杠；不允许反斜杠、盘符、绝对路径、`..` 段 |
+| `fromLine`／`toLine` | 是 | 整数、从 1 起；`fromLine ≤ toLine`，且不得超过**该提交上**文件总行数 |
+
+规则：
+
+- **证据永远按固定提交读**：文件后来变了不算引用错误；但引用写错（提交不存在、文件不在该提交上、行号越界）整条明确报错，页面不放近似内容。
+- 每条引用独立成败，一条坏不拖累别的；写引用前逐条查证行号，不估。
+- 设计阶段 refs 留空；没证据不硬凑。
+- 何时补证据、怎么查证与提交、补完怎么核对，见 [evidence-review.md](evidence-review.md)。
+
+## 3. 交付前检查清单（第一版手动）
+
+按本 Skill 流程交付前逐项过一遍。第一版只用清单，不新建自动化脚本（计划 1b-2 停止边界）；插件自身的报错（说明文件问题、编号冲突、路径不存在）会体现在管理页，清单是把问题在交付前拦住。
+
+| # | 检查项 | 怎么查 |
+|---|---|---|
+| 1 | 六类文件格式 | JSON 都能解析；三个说明文件 `schema` 一字不差、必填字段非空、`id` 与目录名一致；workflow.json 过 workflow.md §4 校验（showcase 五判据全过） |
+| 2 | 图编号全项目唯一 | 扫全部 `docs/specdev/<业务id>/` 下的图目录名，新图编号不与任何现有图重复 |
+| 3 | 文档路径有效 | business.json `docs` 每条：仓库根相对、正斜杠、文件在工作区确实存在 |
+| 4 | 详情节与节点 ID 对应 | details.md 每个 `## ` 节的 id 都在 workflow.json `nodes[].id` 里；无中文标题、无多节同 id；**分节覆盖图上全部节点**——插件容忍漏写（显示"没写说明"）只是读取降级，交付不得留漏：能补齐的当场补齐，业务文档没写依据的列为待裁决问题，不默认放过 |
+| 5 | 规则及分支出处 | 每个节点的职责、条件、先后、失败后果都能指回业务文档；文档没定义的分支已列为待裁决问题，没在图里替业务定规则 |
+
+## 4. 保存边界（如实说）
+
+- **Skill 只提醒，不代存**：保存版本是作者在管理页亲手点的动作（唯一写操作＝给提交挂附注标签）。Skill 流程做到"提醒作者查看并手动保存"为止，AI 不代点、不直接打快照标签。
+- **随版本读取的只有三个数据文件**：workflow.json、details.md、evidence.json。保存前的检查也只核对这三个文件与最新提交一致（换行差异不算改动）。
+- **保存结果分两种，锚定的提交不一定是当前 HEAD**：插件保存时先按三个文件的内容＋阶段查重——与已有快照完全相同就**直接返回那份旧快照**（`alreadySaved`，不给当前提交挂新标签）。例如只改业务文档并提交后再保存同阶段的图，三个图文件没变，返回的可能仍是旧提交上的那份。内容或阶段有变化，才在当前 HEAD 上新建快照。**核对"这份快照对应的业务文档"时，按实际返回的快照锚定的提交去核对**，不默认它是最新提交。
+- **不随版本回退的**：图名称与摘要取自**当前** chart.json（管理页在历史版本下有说明行提示）；业务名称、介绍、文档列表取自当前 business.json；业务文档内容按工作区当前文件读。
+- 因此看历史快照时，若要核对**当时的**业务文档，须按该快照指向的提交另行用 git 核对，不能拿当前文档当历史文档。
+
+## 5. 来源与状态
+
+| 来源 | 取用点 |
+|---|---|
+| `specdev-workbench/README.md`（D2 节、页面与 API、快照五项校验） | 目录结构、图名不随版本回退、docs 只读声明路径 |
+| `specdev-workbench/sample/generate.mjs` + `sample/data/` | 六类文件合法样本形状、details 分节写法、证据引用条目 |
+| `skills/archify-reader/SKILL.md`《详情内容规范》 | §2.5 写作约束八条（摘取适配，见下） |
+| `src/core/types.ts`、`chart-files.ts`、`evidence.ts`、`inventory.ts`、`src/dsh/index.ts`（doc 路由）、`web/assets/details.js` | 字段校验、三文件清单、证据硬规则、编号冲突、分节解析（均只读核对，未改插件） |
+
+有意不采用（reader 规范里属于旧 HTML 阅读器产物的概念，不移植）：普通／源码对照双模式、悬停注释、`evidenceExemption`、reader.json 与构建脚本；本文件只取其写作纪律。generate.mjs 的坏样本（坏标签、坏证据、超限）用于理解插件报错行为，不作为书写目标。
+
+状态：最小合法示例与规则均经源码静态核对（2026-09-17）；本文件未经真实业务仓实跑（计划步骤 2 首跑），"最小合法"的判定依据是插件字段校验逻辑，非管理页实走验证。