svharness 0.8.0 → 0.13.2

package/templates/_shared/build-rules/harness-build-rule-user-interaction.md

@@ -2,24 +2,29 @@
 
 本规则约束 harness 构建过程中 Agent 与用户的交互方式。Agent 是**辅助角色**，不得替代用户做决策，不得未经确认擅自推进流程或修改内容。
 
-## 红线一：P2_raw 必须等待用户放入需求文档
-
-- **P2_raw** 阶段退出条件：`assets/raw/` 目录中**必须存在用户主动放入的至少 1 份需求文档**。
-- Agent **严禁**在 `assets/raw/` 为空或仅含 `.gitkeep` 时自动生成占位文档、虚拟需求或模板填充内容。
-- Agent **严禁**跳过 P2_raw 直接进入 P3_requirements。若用户未提供原始文档，Agent 必须：
-  1. 以表单方式提示用户："请将原始需求文档（如 xlsx、pdf、md、txt）放入 `assets/raw/` 目录"
+## 红线一：S20_collect_inputs 必须完成四项输入确认
+
+- **S20_collect_inputs** 阶段退出条件：
+  1. `requirements/raw/` 中**必须存在用户主动放入的至少 1 份需求文档**；
+  2. `references/raw/` 已完成"已提供/暂无新增"确认；
+  3. `agent-env/skills/` 已完成"有无额外 skills"确认；
+  4. `agent-env/rules/` 已完成"有无额外 rules"确认。
+- Agent **严禁**在 `requirements/raw/` 为空或仅含 `.gitkeep` 时自动生成占位文档、虚拟需求或模板填充内容。
+- Agent **严禁**跳过 S20_collect_inputs 直接进入 S40_extract_requirements。若用户未提供原始文档，Agent 必须：
+  1. 以表单方式提示用户："请将原始需求文档（如 xlsx、pdf、md、txt）放入 `requirements/raw/` 目录"
   2. 等待用户确认已完成文件放入后，再校验目录内容并推进阶段状态
+- 对 references / skills / rules 三项，Agent 必须通过表单做显式询问，且允许用户在 svharness 指令中指定来源路径。
 
 ## 红线二：必须以表单方式与用户交互
 
 当 Agent 需要与用户交流信息或等待用户确认时，**必须**使用表单确认机制（如 `ask_user_question` 工具或等价的交互式表单），**禁止**仅以纯文本方式输出提示后自行继续。
 
 适用场景（不限于）：
-- 阶段准入确认："是否继续进入 P3_requirements 阶段？"
-- 文档缺失提示："assets/raw/ 中未发现需求文档，请放入后确认"
-- 阶段产出审查："P4_specs 已生成 4 个模块的 YAML，是否通过校验？"
+- 阶段准入确认："是否继续进入 S40_extract_requirements 阶段？"
+- 文档缺失提示："requirements/raw/ 中未发现需求文档，请放入后确认"
+- 阶段产出审查："S50_generate_specs 已生成 4 个模块的 YAML，是否通过校验？"
 - 关键决策点："是否要调整 schema？/ 是否跳过该需求？"
-- 流程变更征询："是否要将该规则纳入 P5_rules？"
+- 流程变更征询："是否要将该规则纳入 S61_confirm_baseline_extraction / S65_customize_agent_env？"
 
 **禁止的做法**：
 - 在终端输出一段文字后直接继续执行下一阶段
@@ -33,9 +38,24 @@ Agent **不得**在以下行为上自行决定，**必须**先征求用户同意
 - 修改 `.harness-build-state.yaml` 中 `current_phase` 的跳转方向（如跳过某阶段）
 - 修改 `harness.yaml` 中的 `specs.layers` 配置（增删层、改 schema 路径）
 - 修改任何 `specs/*/schema.json`（字段增删、类型变更）
-- 修改 `AGENTS.md` 中的构建流程步骤
+- 修改 `AGENTS_BUILD.md` 中的构建流程步骤
 - 新增、删除或重命名 `agent-env/rules/` 下的规则文件
 - 调整阶段退出条件（如降低校验标准以通过某个阶段）
+- 在 S65（agent-env 定制）中遇到同名冲突时直接覆盖写入
+
+## 红线四：S60 / S61 / S65 的确认链路不得跳过
+
+当阶段涉及 references 与扩展资源导入时，必须按阶段职责执行确认链路：
+
+- S60（references 处理）：必须先执行 `svharness convert` 并形成结构化索引，再经表单确认落地策略。
+- S61（baseline 自动提取确认）：必须以表单明确"是否启用自动从 baseline 提取 skills/rules"；未确认不得默认开启。
+- S65（agent-env 定制）：若出现冲突（同名、命名不合规、语义重复），必须执行：
+
+1. 先给出可执行建议（如重命名建议、拆分建议、保留旧版建议）。
+2. 再用表单让用户确认（覆盖 / 重命名写入 / 跳过）。
+3. 仅在确认后写入。
+
+禁止：检测冲突后直接覆盖、静默跳过且不告知用户。
 
 **允许的自主行为**（无需额外确认）：
 - 按 `harness-build-rule-orchestrator-flow` 规则正常推进阶段状态
@@ -46,18 +66,18 @@ Agent **不得**在以下行为上自行决定，**必须**先征求用户同意
 ## 正反例
 
 正例（等待用户放入文档）：
-> Agent 检测到 `assets/raw/` 为空，输出表单提示用户放入文档，暂停等待。
+> Agent 检测到 `requirements/raw/` 为空，输出表单提示用户放入文档，暂停等待。
 
 反例（擅自生成）：
-> Agent 发现 `assets/raw/` 为空，自行生成 `placeholder-requirements.md` 填入后标记 P2_raw 为 DONE。
+> Agent 发现 `requirements/raw/` 为空，自行生成 `placeholder-requirements.md` 填入后标记 S20_collect_inputs 为 DONE。
 
 正例（表单确认）：
-> Agent 完成 P4_specs 后，使用 `ask_user_question` 呈现校验结果，等待用户确认通过。
+> Agent 完成 S50_generate_specs 后，使用 `ask_user_question` 呈现校验结果，等待用户确认通过。
 
 反例（纯文本跳过）：
-> Agent 输出"P4_specs 已完成"后直接将阶段标记为 DONE 并推进到下一阶段。
+> Agent 输出"S50_generate_specs 已完成"后直接将阶段标记为 DONE 并推进到下一阶段。
 
 ## 违规处理
 
 - 任何违反上述红线的 Agent 行为，用户可随时回退该阶段状态为 FAILED。
-- P-Final_seal 阶段需审查是否有过未经确认的流程修改。
+- S90_finalize 阶段需审查是否有过未经确认的流程修改。

package/templates/_shared/build-skills/harness-build-skill-agent-env-merge.md

@@ -0,0 +1,75 @@
+---
+name: harness-build-skill-agent-env-merge
+description: >
+  处理构建期 agent-env 合并：S61 确认是否启用 baseline 自动提取 skills/rules，
+  S65 执行 extra-skills / extra-rules（以及已启用的 baseline 候选）冲突处理与写入。
+  当用户说"合并 extra-skills/rules"、"处理 agent-env 冲突"、"确认 baseline 自动提取"，
+  或由 orchestrator 在 S61/S65 阶段委派时触发。
+---
+
+# harness-build-skill-agent-env-merge（agent-env 合并器）
+
+你负责 **S61_confirm_baseline_extraction** 与 **S65_customize_agent_env**，不负责 references 转换与 S70 索引沉淀。
+
+## 输入
+
+- `__HARNESS_ROOT__agent-env/skills/` / `__HARNESS_ROOT__agent-env/rules/`
+- `__HARNESS_ROOT__agent-env/_incoming/manifest.yaml`（由 `--extra-skills` 单入口导入生成，可混放 skills/rules）
+- `__HARNESS_ROOT__baseline/code/`（仅在 S61=ENABLED 时用于候选提取）
+- `__HARNESS_ROOT__.harness-build-state.yaml`
+- S20 已确认输入：`extra-skills` / `extra-rules`（可由单入口 `--extra-skills` 混放提供）
+
+进入本 skill 后，必须先自动读取并盘点 `agent-env/skills`、`agent-env/rules`、`_incoming/manifest.yaml` 与相关来源目录中的既有输入（含 CLI 预先导入项），
+再进入"是否新增/是否写入"决策。用户若选择"不新增"，仅表示不追加新资源，不得跳过盘点与既有输入确认。
+
+## 负责阶段
+
+### S61 —— baseline 自动提取确认（skills/rules）
+
+目标：确认是否启用 baseline 自动提取，避免默认开启导致误提取。
+
+执行步骤（强制）：
+1. 展示可提取来源与影响范围。
+2. 用表单让用户二选一：启用 / 关闭。
+3. 写入阶段结果：`phases.S61_confirm_baseline_extraction.baseline_auto_extract = ENABLED|DISABLED`。
+
+### S65 —— agent-env 定制（合并写入）
+
+目标：在 S61 结果约束下，完成 extra-skills / extra-rules（及已启用 baseline 候选）的可控合并。
+
+冲突处理顺序（强制）：
+1. 先盘点并回显当前待处理输入（manifest 条目 + 已存在目标目录内容），再识别冲突（同名文件、已有目录、命名不合规、语义重复）。
+   - 先基于 `_incoming/manifest.yaml` 对每个条目识别类型：`skill|rule|unknown`。
+2. 给出建议（覆盖、重命名、合并、跳过）。
+   - `unknown` 类型必须先经表单确认再决定落地目录或跳过。
+3. 表单确认最终写入方案。
+4. 仅在确认后写入。
+
+命名约束（运行期资源）：
+- 额外 skill 目录建议：`harness-apply-skills-<topic>`
+- 额外 rule 文件建议：`harness-apply-rules-<topic>.md` / `.mdc`
+- 命名不合规时必须先给重命名建议，不得直接写入。
+
+## 状态更新
+
+- 更新 `S61_confirm_baseline_extraction` / `S65_customize_agent_env` 的 `status`；
+- 保留 `baseline_auto_extract` 字段；
+- 记录计数：`rules_count` / `skills_count`；
+- 刷新 `updated_at`。
+
+## 守则（不得违反）
+
+- 未经 S61 表单确认，不得启用 baseline 自动提取；
+- 未经用户确认，不得覆盖写入冲突文件；
+- 不得处理 S60 references intake 与 S70 skills/tasks 索引；
+- 所有面向用户说明使用中文，必须表单交互。
+
+## 必须遵守的构建规则（位于 Agent rules 目录）
+
+- `harness-build-rule-orchestrator-flow` — 本 skill 仅服务 S61/S65；
+- `harness-build-rule-user-interaction` — 决策点必须表单确认；
+- `harness-build-rule-agent-agnostic` — 产物严禁硬编码具体 agent；
+- `harness-build-rule-chinese-only` — 描述性内容必须中文；
+- `harness-build-rule-memory-write` — 可复用经验按 inbox → categories 规范写入。
+
+若规则文件缺失，停止并提示用户重新运行 `svharness build`。

package/templates/_shared/build-skills/harness-build-skill-knowledge-builder.md

@@ -1,120 +1,84 @@
 ---
 name: harness-build-skill-knowledge-builder
 description: >
-  构建 harness 的知识层（不含 wiki 正文）：baseline/code 样本快照、规则正反例、
-  skills 与 tasks 索引。当用户说"参考代码快照"、"提取规则"、"构建 skills"、
-  "snapshot baseline code"、"build rules"，或由 harness-build-skill-orchestrator 在阶段
-  P5_rules / P6_skills_tasks 委派，以及 P1_wiki 下的"样本代码挑选"子任务
-  委派时触发。baseline wiki 正文撰写由独立 skill harness-build-skill-wiki-writer 负责，本 skill 不承担。
+  构建 harness 的知识沉淀层（不含 wiki 正文与 agent-env 合并）：baseline/code 代表样本
+  与 S70 的运行期 skills/tasks 索引。当用户说"参考代码快照"、"构建 runtime skills"、
+  "build runtime tasks"，或由 harness-build-skill-orchestrator 在 S10_wiki（样本子任务）/
+  S70_runtime_assets 委派时触发。
 ---
 
 # harness-build-skill-knowledge-builder（知识层构建器）
 
-你负责构建 harness 中**可复用的知识层**（不含 wiki 正文）——那些 specs 无法表达、但未来 task 执行时
-仍需依赖的内容：基线代码样本、编码规则、skills 与 tasks 索引。
+你负责构建 harness 中**可复用的知识沉淀层**（不含 wiki 正文，不含 references intake，不含 agent-env merge）：
+baseline 代表样本、运行期 skills 与 tasks 索引。
 
-> 职责边界：**baseline wiki 正文的逐页撰写不在本 skill 范围内**，由 harness-build-skill-wiki-writer 专职完成。
-> 本 skill 只对 `assets/baseline/code/` 做"代表样本挑选"（如需要）。
+> 职责边界：
+> - references 转换与结构化由 `harness-build-skill-references-intake` 负责；
+> - baseline 自动提取确认与 extra-skills/rules 合并写入由 `harness-build-skill-agent-env-merge` 负责；
+> - baseline wiki 正文由 `harness-build-skill-wiki-writer` 负责。
 
 ## 输入
 
-- `__HARNESS_ROOT__specs/**` —— 必须已构建（依赖 P3 为 DONE）
-- `__HARNESS_ROOT__assets/requirements/**` —— 用于将规则回溯到需求
-- `__HARNESS_ROOT__assets/baseline/code/` —— CLI 的 `--baseline` 已完成全量拷贝
-- `__HARNESS_ROOT__harness.yaml` —— 确认哪些知识通道当前激活
+- `__HARNESS_ROOT__specs/**` —— 已构建（依赖 S40/S50 DONE）
+- `__HARNESS_ROOT__requirements/**` —— 回溯需求语义
+- `__HARNESS_ROOT__baseline/code/` —— baseline 全量快照（由 CLI 拷贝）
+- `__HARNESS_ROOT__harness.yaml` —— 当前知识通道配置
 
-## 本 skill 负责的阶段
+进入本 skill 后，必须先自动读取并盘点上述输入是否已存在（尤其 `baseline/code/` 与 specs/requirements 的现有内容），
+再进入 S10/S70 的新增或生成决策。用户若选择"无新增"，仅表示不追加新材料，不得跳过盘点与既有内容确认。
 
-### P1 —— baseline/code（参考代码样本，可选子任务）
+## 本 skill 负责的阶段
 
-目标：在 `__HARNESS_ROOT__assets/baseline/code/` 已有全量快照的基础上，**可选地**挑出"代表性样本清单"供 P5/P6 参考。
+### S10（子任务）—— baseline/code 代表样本清单（可选）
 
-> 说明：CLI 的 `--baseline` 已将基线源码全量拷贝到 `__HARNESS_ROOT__assets/baseline/code/`；本步骤不拷贝任何文件，
-> 只是在有必要时产出一份 `__HARNESS_ROOT__assets/baseline/code/SAMPLES.md` 罗列约 20 个典型样本，便于规则抽取回溯。
-> 如果不需要可直接跳过。
+目标：在 `__HARNESS_ROOT__baseline/code/` 全量快照基础上，可选产出 `SAMPLES.md`，为 S70 的技能抽象提供稳定样本入口。
 
-选型策略（硬上限：约 20 个文件）：
-- 每种原型挑选 1 个代表文件，而非把整个原型全部列出。
-- 优先选：1 个 Controller / 1 个 Model / 1 个 Parser / 1 个 Sender / 1 个 ViewCallback /
-  1 个 Activity / 1 个 Fragment / 1 个 Adapter / 1 段 build.gradle / 1 个 AIDL。
-- 用相对 `__HARNESS_ROOT__assets/baseline/code/` 的路径引用，不再另外拷贝文件。
+执行策略（硬上限：约 20 文件）：
+- 每类原型只选 1 个代表文件，不做全集罗列；
+- 优先覆盖：Controller / Model / Parser / Sender / ViewCallback / Activity / Fragment / Adapter / build.gradle / AIDL；
+- 仅写相对 `__HARNESS_ROOT__baseline/code/` 的路径，不额外拷贝文件。
 
 禁止：
-- **不得**重新拷贝或删除 `__HARNESS_ROOT__assets/baseline/code/` 下的任何文件。
-- **不得**在本步骤内写 wiki 正文——交给 harness-build-skill-wiki-writer。
-
-### P5 —— 规则（正反例）
-
-目标：在 `__HARNESS_ROOT__agent-env/rules/` 下，为每个规则主题产出一份 markdown，将项目的硬性约束编码化。
-
-每个规则文件结构：
-
-```markdown
-# <规则标题>
-
-## 是什么
-
-一段话陈述该不变式。
-
-## 正例
-
-<从 __HARNESS_ROOT__assets/baseline/code/ 取出或最小改写的代码块>
-
-## 反例
-
-<展示反模式的最小代码块，附注释说明为什么错>
-
-## 如何检测
-
-评审者或 Agent 如何识别违规。
-```
-
-种子规则（按项目实际调整）：
-- MVC 分层（UI 仅依赖 Controller）
-- Controller 单例双重检查锁
-- Parser 隔离（UI 中禁止解析 byte[]）
-- Listener 作为成员变量（禁止 lambda 传入 `setDataChangeListener`）
-- 信号流向（车→机 / 机→车 不得绕过）
+- 不得改动 `baseline/code/` 下文件；
+- 不得在本步骤撰写 wiki 正文。
 
-### P6 —— skills & tasks 索引
+### S70 —— runtime skills & tasks 索引
 
-目标：填充 `__HARNESS_ROOT__agent-env/skills/` 与 `__HARNESS_ROOT__tasks/templates/`，放入**构建期沉淀**下来的 **运行期 skill**
-（区别于 Agent IDE 中的 build-skill）。
+目标：填充 `__HARNESS_ROOT__agent-env/skills/` 与 `__HARNESS_ROOT__tasks/templates/`，沉淀可复用运行期能力单元。
 
-1. 将 P1–P5 中识别到的"反复出现的 Agent 操作"抽成 skill，放在
-   `__HARNESS_ROOT__agent-env/skills/<skill>/SKILL.md`，带 YAML frontmatter。
-2. 将离散的开发者工作流抽成 task 模板，放在 `__HARNESS_ROOT__tasks/templates/<task>/TASK.md`，含 inputs / steps / acceptance。
-3. Skill 与 task **应通过路径引用 specs 与规则**，不要内联其内容。
+约束：
+1. 将反复出现的 Agent 操作抽成 skill，落在
+   `__HARNESS_ROOT__agent-env/skills/<skill>/SKILL.md`（YAML frontmatter 必备）。
+2. 将可复用开发流程抽成 task，落在
+   `__HARNESS_ROOT__tasks/templates/<task>/TASK.md`（含 inputs / steps / acceptance）。
+3. skill 与 task 通过路径引用 specs / rules，不内联完整内容。
 
 ## 状态更新
 
 每完成一个子阶段：
-- 更新 `__HARNESS_ROOT__.harness-build-state.yaml`（P5 / P6 的 `status`；P1 的"样本清单"子任务若产出，一并记录）。
-- 记录计数：`baseline_code_samples` / `rules_count` / `skills_count` / `tasks_count`。
+- 更新 `__HARNESS_ROOT__.harness-build-state.yaml`（S70 的 `status`；S10 子任务若产出一并记录）；
+- 记录计数：`baseline_code_samples` / `skills_count` / `tasks_count`；
 - 刷新 `updated_at`。
 
 ## 守则（不得违反）
 
-- **不得撰写或编辑 baseline wiki 正文**（交给 harness-build-skill-wiki-writer）。
-- **不得凭空编造架构**：所有结论必须落地到源码或 specs。无法追溯的推断一律舍弃。
-- **规则必须同时有正例与反例**，否则规则文件视为不合格。
-- **不得从本 skill 内编辑 specs 或 schema**。若规则与 specs 冲突，立即停止并上报 orchestrator。
-- 所有对用户的说明使用中文；路径、字段名、类名保留英文。
-- **必须以表单方式**与用户交互确认，禁止仅以纯文本输出后自行继续。
-- **所有描述性字段必须使用中文**（见 `harness-build-rule-chinese-only`）。
+- 不得撰写或编辑 baseline wiki 正文；
+- 不得在本 skill 内处理 S60/S61/S65；
+- 不得编辑 specs/schema；若发现冲突立即上报 orchestrator；
+- 所有面向用户的说明使用中文；路径、字段名、类名保留英文；
+- 必须使用表单进行确认，禁止仅输出纯文本后自行继续。
 
 ## 必须遵守的构建规则（位于 Agent rules 目录）
 
-本 skill 执行前必须加载并严格遵循（文件位于当前 agent 的 rules 目录，具体路径/扩展名
-随 agent 可能为 `.md` 或 `.mdc`）：
+执行前必须加载并严格遵循（规则目录中可能为 `.md` 或 `.mdc`）：
 
-- `harness-build-rule-orchestrator-flow` — 本 skill 服务 P1(样本)/P5/P6，禁止跨阶段跳步或合并。
-- `harness-build-rule-skills-tasks-output` — P6 产物必须符合 skills/tasks 目录与命名规范。
-- `harness-build-rule-memory-write` — 构建过程中的可复用经验按 inbox → categories 规范写入。
-- `harness-build-rule-agent-agnostic` — 所有 baseline/rules/skills 产物严禁硬编码具体 agent 名。
-- `harness-build-rule-specs-schema` — 引用 specs 时按四域路径，不得绕过 schema。
-- `harness-build-rule-chinese-only` — 所有产出内容必须使用中文。
-- `harness-build-rule-user-interaction` — 用户交互铁律：表单确认、禁止擅自修改。
+- `harness-build-rule-orchestrator-flow` — 本 skill 仅服务 S10(样本)/S70；
+- `harness-build-rule-skills-tasks-output` — S70 产物结构与命名规范；
+- `harness-build-rule-memory-write` — 可复用经验按 inbox → categories 写入；
+- `harness-build-rule-agent-agnostic` — 产物严禁硬编码具体 agent；
+- `harness-build-rule-specs-schema` — 引用 specs 时按四域路径；
+- `harness-build-rule-chinese-only` — 描述性内容必须中文；
+- `harness-build-rule-user-interaction` — 表单确认、禁止擅自修改。
 
-若规则文件缺失，停止工作并提示用户重新运行 `svharnessbuild init`。
+若规则文件缺失，停止并提示用户重新运行 `svharness build`。
 

package/templates/_shared/build-skills/harness-build-skill-orchestrator.md

@@ -12,13 +12,14 @@ description: >
 
 ## 输入
 
+- （可选）**`harness-build-skills-main`** —— 若会话从总清单进入，已解析绑定元数据并完成规则装载，可直接以本 skill 为执行入口。
 - `__HARNESS_ROOT__.harness-build-state.yaml`（状态机，权威进度来源）
 - `__HARNESS_ROOT__harness.yaml`（清单：路径、版本、层配置）
-- `__HARNESS_ROOT__AGENTS.md`（Agent 协作协议参考）
+- `__HARNESS_ROOT__AGENTS_BUILD.md`（Agent 协作协议参考）
 
 ## 算法
 
-1. 读取 `__HARNESS_ROOT__.harness-build-state.yaml`。若文件不存在，打印错误并提示用户先运行 `svharnessbuild init`。
+1. 读取 `__HARNESS_ROOT__.harness-build-state.yaml`。若文件不存在，打印错误并提示用户先运行 `svharness build`。
 2. 识别 `current_phase` 及其 `status`。
 3. 对当前阶段，以"状态卡片"形式输出：
    - 阶段 id + 一句话说明
@@ -26,21 +27,36 @@ description: >
    - 是否需要人工（`manual_required: true`）或需要 Agent 工作（`requires_agent: true`）
    - 推荐下一步调用哪个 skill
 4. **必须以表单确认方式**询问用户是否继续，未经用户确认不得自行推进：
-   - **P1_wiki** — 读取 state 中该 phase 的语义字段决定行为：
-     - phase **不存在** → 跳过（本项目无 baseline，直接推进到 P2_raw）。
+  - **S10_wiki** — 读取 state 中该 phase 的语义字段决定行为：
+    - phase **不存在** → 跳过（本项目无 baseline，直接推进到 S20_collect_inputs）。
      - `status: DONE`, `mode: full` → wiki 已完整，orchestrator 不再委派；如需修订委派给 `harness-build-skill-wiki-writer`。
-     - `status: PENDING`, `mode: outline-only` → 读 `tasks_file`（默认 `__HARNESS_ROOT__assets/baseline/wiki/TASKS.md`），
+     - `status: PENDING`, `mode: outline-only` → 读 `tasks_file`（默认 `__HARNESS_ROOT__baseline/wiki/TASKS.md`），
        委派给 `harness-build-skill-wiki-writer` 逐页撰写正文；全部 `[x]` 后由 orchestrator 标记 `DONE`。
        - `source: cli-tasks` —— 用户选择默认 tasks-only 模式。
        - `source: cli-full-degraded` —— CLI 完整生成失败后降级，页面可能已有部分草稿，优先续写。
-     - 可选子任务：若需要"代表样本清单"（`__HARNESS_ROOT__assets/baseline/code/SAMPLES.md`），委派给 `harness-build-skill-knowledge-builder`。
-   - **P2_raw** — 以表单提示用户把原始需求文档放入 `__HARNESS_ROOT__assets/raw/`。**校验目录非空且不含仅 `.gitkeep`** 后，以表单确认并标记 DONE。**严禁在目录为空时自动生成占位文档**。用户可参考 P1_wiki 中的架构知识来撰写更精准的需求。
-   - **P3_requirements** — 委派给 `harness-build-skill-spec-builder`（需求条目化提取到 `__HARNESS_ROOT__assets/requirements/`）。
-   - **P4_specs** — 委派给 `harness-build-skill-spec-builder`（生成受 schema 校验的 YAML）。
-   - **P5_rules** — 以表单请用户补充 `__HARNESS_ROOT__agent-env/rules/` 的正反例；Agent 可起草骨架（委派给 `harness-build-skill-knowledge-builder`）。
-   - **P6_skills_tasks** — 委派给 `harness-build-skill-knowledge-builder`（`__HARNESS_ROOT__agent-env/skills/` + `__HARNESS_ROOT__tasks/templates/`）。
-   - **P7_memory** — 以表单请用户播种 `__HARNESS_ROOT__agent-env/memory/categories/` 初始分类；Agent 可建议草稿。
-   - **P-Final_seal** — 提醒用户运行 `svharnessbuild seal`（后续版本提供），并将 `specs.bootstrap_mode` 翻转为 false。
+     - 可选子任务：若需要"代表样本清单"（`__HARNESS_ROOT__baseline/code/SAMPLES.md`），委派给 `harness-build-skill-knowledge-builder`。
+  - **S20_collect_inputs** — 必须先做"已输入资源盘点"，再做"是否新增"确认（两者都用表单）：
+    1. 先盘点并展示当前已有输入（**不可跳过**）：读取 `__HARNESS_ROOT__requirements/raw/`、`__HARNESS_ROOT__references/raw/` 与 `__HARNESS_ROOT__agent-env/_incoming/skills/`，确认是否已包含通过 svharness 指令预先注入的文件；
+    2. 需求文档新增：若仍需补充，提示放入 `__HARNESS_ROOT__requirements/raw/`（或让用户在 svharness 指令中给出来源路径）；
+    3. 参考资料新增：若仍需补充，提示放入 `__HARNESS_ROOT__references/raw/`（或让用户在 svharness 指令中给出来源路径）；
+    4. 额外运行期资源新增：询问是否通过 `svharness build --extra-skills <path...>` 提供（可混放 skills/rules，统一暂存到 `__HARNESS_ROOT__agent-env/_incoming/skills/`）；
+    5. 类型确认：若输入包含规则文件或无法识别类型的资源，提示将由 S65 根据 `__HARNESS_ROOT__agent-env/_incoming/manifest.yaml` 做分流确认（skill→`agent-env/skills/`，rule→`agent-env/rules/`）。
+    **关键约束**：用户选择"不新增"仅表示不再添加新文件，**不等于**跳过本阶段；仍须完成第 1 步盘点并基于 `raw/` 现有文件做确认后方可退出。
+    **退出条件**：已完成第 1 步盘点；`requirements/raw/` 存在真实文档；其余项完成"已提供/无新增"确认。严禁自动生成占位文档。
+  - **S30_convert_docs** — 将 `raw/` 中的非 Markdown 原始文档统一转换为 Markdown：
+     1. 检查 `__HARNESS_ROOT__requirements/raw/` 中是否有非 `.md`、非 `.gitkeep` 的文件。
+     2. 检查 `__HARNESS_ROOT__references/raw/` 中是否有非 `.md`、非 `.gitkeep` 的文件。
+     3. 若有，以表单提示用户运行 `svharness convert --input <path> --output __HARNESS_ROOT__ --type requirements`（或 references）将文档转为 md；也可由 Agent 直接调用 CLI（若运行环境支持）。
+     4. 校验两个 `md/` 目录是否已包含 `raw/` 中每份源文档对应的 `.md` 文件。
+    5. 全部完成后标记 DONE 并推进到 S40_extract_requirements。
+  - **S40_extract_requirements** — 委派给 `harness-build-skill-spec-builder`（需求条目化提取到 `__HARNESS_ROOT__requirements/yaml/`）。
+  - **S50_generate_specs** — 委派给 `harness-build-skill-spec-builder`（生成受 schema 校验的 YAML）。
+  - **S60_process_references**（references 处理）— 仅处理 references：执行 `svharness convert`，产出结构化索引（规制约束 / skills 候选 / signals / manuals），并通过表单确认落地策略；委派给 `harness-build-skill-references-intake`。
+  - **S61_confirm_baseline_extraction**（baseline 自动提取确认）— 以表单确认是否允许后续阶段自动从 `__HARNESS_ROOT__baseline/code/` 提取 skills/rules；未确认不得自动提取；确认结果建议写入 `phases.S61_confirm_baseline_extraction.baseline_auto_extract`；委派给 `harness-build-skill-agent-env-merge`。
+  - **S65_customize_agent_env**（agent-env 定制）— 处理 extra-skills / extra-rules 合并写入（来源可来自单入口 `--extra-skills` 的 `_incoming/manifest.yaml` 清单）。遇到冲突时必须执行"先给修改建议 → 用户表单确认 → 再写入"；委派给 `harness-build-skill-agent-env-merge`。
+  - **S70_runtime_assets** — 委派给 `harness-build-skill-knowledge-builder`（`__HARNESS_ROOT__agent-env/skills/` + `__HARNESS_ROOT__tasks/templates/`）。语义上 skill 是执行 task 的能力单元，task 是流程模板。
+   - **S80_seed_memory** — 以表单请用户播种 `__HARNESS_ROOT__agent-env/memory/categories/` 初始分类；Agent 可建议草稿。
+   - **S90_finalize** — 提醒用户运行 `svharnessbuild seal`（后续版本提供），并将 `specs.bootstrap_mode` 翻转为 false。
 5. 每次完成后，**最小增量补丁**更新 `__HARNESS_ROOT__.harness-build-state.yaml`：
    - 已完成阶段标记 `status: DONE`，填写 `completed_at`
    - 将 `current_phase` 推进到下一个 PENDING 阶段
@@ -52,7 +68,7 @@ description: >
 每次响应必须以状态卡片开头：
 
 ```
-阶段:     P3_specs (IN_PROGRESS)
+阶段:     S50_generate_specs (IN_PROGRESS)
 需要:     agent
 已完成:   signals (4 个模块), ui (4 个模块)
 待处理:   behavior, interfaces, 校验
@@ -74,14 +90,15 @@ description: >
 
 执行任何阶段前，先加载并严格遵循以下规则（文件位于当前 agent 的 rules 目录，
 如 `.qoder/rules/`、`.codechat/rules/`、`.cursor/rules/harness-build/`、
-`.claude/rules/`、`.harness/rules/`，具体扩展名随 agent 可能为 `.md` 或 `.mdc`）：
+`.claude/rules/`、`.opencode/rules/`、`.harness/rules/`，具体扩展名随 agent 可能为 `.md` 或 `.mdc`）：
 
 - `harness-build-rule-orchestrator-flow` — 构建阶段准入/退出红线，任何调度决策都必须匹配。
-- `harness-build-rule-specs-schema` — P4 阶段生成的 YAML 必须通过对应 schema.json。
+- `harness-build-rule-convert-check` — S30_convert_docs 阶段须检查 `requirements/raw/` 与 `references/raw/`，确保非 md 原始文档已转为 Markdown 方可推进。
+- `harness-build-rule-specs-schema` — S50 阶段生成的 YAML 必须通过对应 schema.json。
 - `harness-build-rule-memory-write` — 若本阶段有可复用经验，按 inbox → categories 流转写入。
-- `harness-build-rule-skills-tasks-output` — 委派 P6 时，产物结构/命名必须符合该规则。
+- `harness-build-rule-skills-tasks-output` — 委派 S70 时，产物结构/命名必须符合该规则。
 - `harness-build-rule-agent-agnostic` — 产出文本中严禁出现任何具体 agent 名或其私有指令语法。
 - `harness-build-rule-chinese-only` — 所有面向用户的产出内容必须使用中文。
 - `harness-build-rule-user-interaction` — 用户交互铁律：等待 raw、表单确认、禁止擅自修改。
 
-若上述规则文件缺失，先提醒用户重新运行 `svharnessbuild init` 恢复规则注入，再继续工作。
+若上述规则文件缺失，先提醒用户重新运行 `svharness build` 恢复规则注入，再继续工作。

package/templates/_shared/build-skills/harness-build-skill-references-intake.md

@@ -0,0 +1,91 @@
+---
+name: harness-build-skill-references-intake
+description: >
+  处理构建期 references intake：将 references/raw 转换为 markdown，并产出结构化索引
+  （规制约束 / skills 候选 / signals / manuals）。对「内容引用」登记
+  apply-skills-registry，供 apply 阶段经 harness-apply-skills-main 的 apply_skill_registry 路由。
+  当用户说"处理 references"、
+  "convert references"、"提取参考文档结构化索引"，或由 orchestrator 在
+  S60_process_references 委派时触发。
+---
+
+# harness-build-skill-references-intake（references 摄取器）
+
+你只负责 **S60_process_references**：把 references 从原始资料转成可消费的结构化知识，并为需要在 apply 阶段复用的**内容引用**登记到 `apply-skills-registry.yaml`（由 `harness-apply-skills-main` 统一路由，不另建子 skill 目录）。
+
+## 输入
+
+- `__HARNESS_ROOT__references/raw/` —— 原始参考资料
+- `__HARNESS_ROOT__references/md/` —— 转换目标目录
+- `__HARNESS_ROOT__references/yaml/index.yaml` —— 结构化索引（本阶段产出）
+- `__HARNESS_ROOT__references/apply-skills-registry.yaml` —— apply skill 注册表（本阶段维护）
+- `__HARNESS_ROOT__.harness-build-state.yaml` —— 当前阶段状态
+- `__HARNESS_ROOT__harness.yaml` —— references 来源配置
+
+模板与格式示例：
+- `__HARNESS_ROOT__references/apply-skills-registry.example.yaml`
+- references 运行期路由与执行说明见 `svharnessbuild` 模板
+  `templates/_shared/apply-skills/harness-apply-skills-main.md` 中「References 能力」一节
+
+进入本 skill 后，必须先自动读取并盘点 `references/raw/` 与 `references/md/` 的既有内容（含 build 阶段 CLI 已注入的文件），
+再进入转换与索引决策。用户若选择「无新增 references」，仅表示不追加新 raw 文件，不得跳过盘点。
+
+## 内容引用 vs 非内容引用
+
+| 类型 | 含义 | S60 落盘 |
+|------|------|----------|
+| **内容引用** | apply 时需要反复查阅该 references/md 原文来指导实现（方法论、平台能力、插件流程等） | 仅登记 `apply-skills-registry.yaml`（由 apply-main 内联 `apply_skill_registry` 路由） |
+| **规制约束** | 仅作为规则候选，写入 rules 由 S65 处理 | 只进 `index.yaml` → `rules_candidates`，**不**建 apply skill |
+| **手册/背景** | 只读背景，偶发查阅 | 只进 `index.yaml` → `manuals`，**不**建 apply skill |
+| **signals** | 领域信号定义 | 只进 `index.yaml` → `signals` |
+
+判断为**内容引用**时至少满足其一：用户明确要在开发中按该文档执行；文档描述可复用流程/能力/插件入口；`skills_candidates` 中标记为可路由能力。
+
+## 负责阶段
+
+### S60 —— references 处理（convert + 结构化索引 + apply skills）
+
+执行步骤（强制顺序）：
+
+1. 盘点并回显 `references/raw/`、`references/md/` 文件清单。
+2. 与用户确认各类 references 的用途（内容引用 / 规制 / 手册 / signals）。
+3. 对 `references/raw/` 中非 md 源文件执行 `svharness convert`（`--type references`，输出到 `references/md/`）。
+4. 产出或更新 `references/yaml/index.yaml`（`rules_candidates` / `skills_candidates` / `signals` / `manuals`）。
+5. **内容引用 → 登记 apply-skills-registry.yaml**（经表单确认后执行）：
+   - 路径：`__HARNESS_ROOT__references/apply-skills-registry.yaml`
+   - 每条追加：`skill_name`（`harness-apply-skills-<topic>`，kebab-case）、`reference_md`、
+     `description`（含触发关键词）、可选 `source_id` / `entry`、`enabled: true`
+   - `skill_dir` 可与 `skill_name` 相同（兼容字段）；**勿**在 `agent-env/skills/` 下新建
+     `harness-apply-skills-*` 目录——运行期由 `harness-apply-skills-main` 读 registry +
+     `references/md/` 执行
+   - 供 `svharness apply` 写入 `harness-apply-skills-main` 绑定元数据的 `apply_skill_registry`
+6. 汇总 S60 结果并以表单确认（含：索引路径、registry 新增条目、未登记的 references 及原因）。
+
+## 状态更新
+
+- 更新 `.harness-build-state.yaml` 的 `S60_process_references.status`；
+- 记录计数：`references_count` / `references_converted_count` / `reference_apply_skills_count`（registry 中 enabled 条目数）；
+- 刷新 `updated_at`。
+
+## 守则（不得违反）
+
+- 不得处理 S61/S65/S70 的职责；
+- **禁止**调用或假设存在 `svharness references-apply-skills` 子命令（不存在）；
+- **禁止**在 `agent-env/skills/` 下新建 `harness-apply-skills-*` 目录（已合并到 apply-main）；
+- 未经表单确认，不得新增 registry 条目或覆盖已有登记；
+- 不得把仅作规制/手册的 references 误建为 apply skill；
+- 不得编辑 specs/schema；
+- 所有面向用户的说明使用中文；
+- 必须用表单确认，禁止纯文本后自行继续。
+
+## 必须遵守的构建规则（位于 Agent rules 目录）
+
+- `harness-build-rule-orchestrator-flow` — 本 skill 仅服务 S60；
+- `harness-build-rule-convert-check` — 转换完整性检查；
+- `harness-build-rule-skills-tasks-output` — skill 目录与 SKILL.md 命名规范；
+- `harness-build-rule-specs-schema` — 引用 specs 时按四域路径；
+- `harness-build-rule-agent-agnostic` — 产物严禁硬编码具体 agent；
+- `harness-build-rule-chinese-only` — 描述性内容必须中文；
+- `harness-build-rule-user-interaction` — 用户交互必须表单确认。
+
+若规则文件缺失，停止并提示用户重新运行 `svharness build`。

package/templates/_shared/build-skills/harness-build-skill-spec-builder.md

@@ -12,8 +12,11 @@ description: >
 
 ## 输入
 
-- `__HARNESS_ROOT__assets/raw/*.{md,xlsx,pdf,txt}` —— 原始需求文档
-- `__HARNESS_ROOT__assets/requirements/*.requirements.yaml` —— 已条目化的结构化需求项（如已存在）
+- `__HARNESS_ROOT__requirements/raw/*.{md,xlsx,pdf,txt}` —— 原始需求文档
+- `__HARNESS_ROOT__requirements/md/*.{md}` —— convert 预处理后的 Markdown
+- `__HARNESS_ROOT__requirements/yaml/*.requirements.yaml` —— 已条目化的结构化需求项（如已存在）
+- `__HARNESS_ROOT__references/raw/*.{md,xlsx,pdf,txt}` —— 参考资料原始文档
+- `__HARNESS_ROOT__references/md/*.{md}` —— references 转换后的 Markdown
 - `__HARNESS_ROOT__specs/<layer>/schema.json` —— 每一层的校验目标
 - `__HARNESS_ROOT__harness.yaml` —— 确认哪些层当前激活
 
@@ -21,11 +24,15 @@ description: >
 
 ### 阶段 A：raw → requirements（条目化）
 
-对 `__HARNESS_ROOT__assets/raw/` 下每个文件，产出一个 `__HARNESS_ROOT__assets/requirements/<module>.requirements.yaml`，结构如下：
+执行步骤（强制顺序）：
+1. 先对 `requirements/raw/` 执行 `svharness convert` 到 `requirements/md/`，示例：
+   - `svharness convert --input "__HARNESS_ROOT__requirements/raw" --output "__HARNESS_ROOT__" --type requirements`
+2. 校验 `requirements/raw/` 中每个非 `.md`、非 `.gitkeep` 文件，都在 `requirements/md/` 有同基名 `.md` 产物；若缺失，停止条目化并以表单提示用户补齐转换。
+3. 基于 `requirements/md/` 的转换结果进行条目抽取，为 `requirements/raw/` 下每个源文件产出一个 `__HARNESS_ROOT__requirements/yaml/<module>.requirements.yaml`，结构如下：
 
 ```yaml
 module: <module>
-source_doc: "assets/raw/<file>"
+source_doc: "requirements/raw/<file>"
 extracted_at: <ISO8601 日期>
 items:
   - id: REQ-<MODULE>-001
@@ -41,12 +48,14 @@ items:
 - 条目 id **稳定**：一旦产出不得改写，新条目追加。
 - 每条 `description` 必须是**一句清晰的陈述**。
 - `traces_to` 初始可为空，阶段 B 生成 specs 后回填。
+- `source_doc` 必须引用 `requirements/raw/` 下真实文件。
+- **禁止跳过转换直接抽取**：不得直接从 `requirements/raw/` 读取 `.xlsx/.pdf/.docx` 等原始文件生成条目，必须通过 `requirements/md/` 中间层。
 
 ### 阶段 B：requirements → specs（规格生成）
 
 对每个模块、每个激活层（signals / ui / behavior / interfaces）：
 
-1. 读取 `__HARNESS_ROOT__assets/requirements/<module>.requirements.yaml`。
+1. 读取 `__HARNESS_ROOT__requirements/yaml/<module>.requirements.yaml`。
 2. 读取 `__HARNESS_ROOT__specs/<layer>/schema.json`。
 3. 生成 `__HARNESS_ROOT__specs/<layer>/<module>.<layer>.yaml`，要求：
    - 满足 schema（所有 `required` 字段完备、`enum` 取值合法）
@@ -57,12 +66,12 @@ items:
 ## 状态更新
 
 每完成一个模块后：
-- 更新 `__HARNESS_ROOT__.harness-build-state.yaml`（阶段 P3 或 P4，带每层子状态）。
+- 更新 `__HARNESS_ROOT__.harness-build-state.yaml`（阶段 S40 或 S50，带每层子状态）。
 - 刷新状态文件与 spec 文件的 `updated_at`。
 
 ## 守则（不得违反）
 
-- **不得无中生有**：所有需求必须来自 `__HARNESS_ROOT__assets/raw/`。`assets/raw/` 为空或仅含 `.gitkeep` 时，**必须以表单方式提示用户放入需求文档**，禁止自行生成占位内容。
+- **不得无中生有**：所有需求必须来自 `__HARNESS_ROOT__requirements/raw/`。`requirements/raw/` 为空或仅含 `.gitkeep` 时，**必须以表单方式提示用户放入需求文档**，禁止自行生成占位内容。
 - **不得修改 `schema.json`**：schema 若有问题，停下来告诉用户，不要自行改写。
 - 单个 spec YAML 文件应保持 **< 300 行**；超过时按子模块拆分。
 - 一个 YAML 文件只承载一个层，**不要混层**。
@@ -75,11 +84,12 @@ items:
 本 skill 执行前必须加载并严格遵循（文件位于当前 agent 的 rules 目录，具体路径/扩展名
 随 agent 可能为 `.md` 或 `.mdc`）：
 
+- `harness-build-rule-convert-check` — 本 skill 消费 `requirements/md/` 与 `references/md/`，上游 S30_convert_docs 缺漏时拒绝条目化。
 - `harness-build-rule-specs-schema` — specs 四域固定、schema.json 必过、字段增减需同步。
-- `harness-build-rule-orchestrator-flow` — 本 skill 仅服务 P3/P4，禁止跨阶段跳步。
+- `harness-build-rule-orchestrator-flow` — 本 skill 仅服务 S40/S50，禁止跨阶段跳步。
 - `harness-build-rule-agent-agnostic` — 生成的 requirements/specs YAML 严禁出现具体 agent 名或私有语法。
 - `harness-build-rule-memory-write` — 条目化/规格化过程中产生的可复用经验按规范写入 memory。
 - `harness-build-rule-chinese-only` — 所有产出内容必须使用中文（字段名、枚举值等保留英文）。
 - `harness-build-rule-user-interaction` — 用户交互铁律：等待 raw 文档、表单确认、禁止擅自修改。
 
-若规则文件缺失，停止工作并提示用户重新运行 `svharnessbuild init`。
+若规则文件缺失，停止工作并提示用户重新运行 `svharness build`。