svharness 0.8.0

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "svharness",
+  "version": "0.8.0",
+  "description": "CLI scaffolder for SDD-Driven Agent-Agnostic Coding Framework (harness)",
+  "bin": {
+    "svharness": "./bin/cli.js",
+    "svharnessbuild": "./bin/cli.js"
+  },
+  "files": [
+    "dist/",
+    "bin/",
+    "templates/",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc",
+    "clean": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\"",
+    "rebuild": "npm run clean && npm run build",
+    "prepare": "npm run build",
+    "prepublishOnly": "npm run build"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "sdd",
+    "harness",
+    "ai-agent",
+    "scaffolder",
+    "spec-driven"
+  ],
+  "author": "uidq3640",
+  "license": "MIT",
+  "dependencies": {
+    "commander": "^12.1.0",
+    "ejs": "^3.1.10",
+    "fs-extra": "^11.2.0",
+    "js-yaml": "^4.1.0",
+    "picocolors": "^1.1.1",
+    "prompts": "^2.4.2",
+    "repomix": "^1.14.0",
+    "svharnessbuild": "^0.7.0",
+    "tar": "^7.5.15"
+  },
+  "devDependencies": {
+    "@types/ejs": "^3.1.5",
+    "@types/fs-extra": "^11.0.4",
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^20.14.0",
+    "@types/prompts": "^2.4.9",
+    "@types/tar": "^6.1.13",
+    "typescript": "^5.4.5"
+  }
+}

package/templates/_shared/apply-skills/harness-apply-skills-main.md

@@ -0,0 +1,91 @@
+---
+name: harness-apply-skills-main
+description: >
+  把 harness 知识层（rules / skills / specs / baseline / memory）应用到目标项目，
+  完成具体功能开发。**从本 skill 正文内嵌的 `## 绑定元数据` 小节解析** `harness_root`，
+  然后加载 `<harness_root>/agent-env/rules/` 作为强约束、扫描
+  `<harness_root>/agent-env/skills/*/SKILL.md` 作为子能力，并参考
+  `<harness_root>/assets/baseline/`、`<harness_root>/specs/` 产出代码。
+  当用户说"应用 harness-apply-skills-main 完成 xxx 功能开发"、
+  "使用 harness 开发 xxx"、"基于 harness 做 xxx"、"apply harness"、
+  "按 harness 规范实现 xxx" 时触发。
+---
+
+# harness-apply-skills-main（harness 应用二级调度）
+
+你是一个 **harness 知识层调度器**。当用户请求基于当前项目绑定的 harness
+完成功能开发时，你不直接写业务代码，而是先把 harness 的约束、能力、基线、规格
+装载到上下文，再按语义把任务路由到 harness 内部的子 skill。
+
+> 本 skill 由 `svharnessbuild apply` 注入。harness 本体可能位于目标项目之外
+> 的任意路径（方案 B：不同根），因此**所有 harness 文件引用必须通过本 skill
+> 正文末尾的 `## 绑定元数据` YAML 块中的 `harness_root` 解析**，禁止假设相对
+> 位置，也不要去读取外部 `binding.yaml`——它只是冗余副本，不是权威来源。
+
+## 输入
+
+- **本 skill 文件内嵌的 `## 绑定元数据` YAML 块** —— 权威来源，运行时从这里读取：
+  - `harness_root` —— harness 目录（形如 `<name>-harness/`）的**绝对路径**
+  - `harness_root_rel` —— 相对目标项目根目录的路径（用于在 md 中渲染跨项目链接）
+  - `harness_name` —— harness 名称
+  - `harness_version` —— harness 构建状态版本（来自 `<harness_root>/VERSION`）
+  - `target_project` —— 绑定的目标项目根路径
+  - `agent` —— 当前 IDE / agent 标识
+  - `applied_at` / `applied_by` —— 绑定时间与工具版本
+- （旁置，不读）`./references/binding.yaml` —— 冗余副本，仅供 `svharnessbuild`
+  自身工具链（status / detach 等）解析；skill 运行时**不读它**。
+
+## 算法
+
+1. **加载绑定**：从本 skill 正文末尾的 `## 绑定元数据` 小节（fenced ```yaml 代码块）
+   解析 `harness_root` 等字段。若解析失败或 `harness_root` 指向的目录不存在，
+   停止并提示用户重新运行 `svharnessbuild apply --force`。
+
+2. **加载强约束**：枚举并读取 `<harness_root>/agent-env/rules/*.mdc` 与
+   `<harness_root>/agent-env/rules/*.md`（`always_on` 必须全部遵守；
+   `model_decision` 按本次任务语义挑选）。规则冲突时以 `always_on` 为准。
+
+3. **扫描子能力清单**：枚举 `<harness_root>/agent-env/skills/*/SKILL.md`，
+   提取 frontmatter 的 `name` + `description`，建立本次会话可用的
+   **子 skill 路由表**。不要整目录朗读内容，按需要再深读。
+
+4. **语义路由**：根据用户任务在路由表中选择最匹配的 1 ~ N 个子 skill。
+   若无匹配，回到普通实现路径，但仍必须遵守步骤 2 的规则。
+
+5. **查阅基线与规格**（按需）：
+   - `<harness_root>/assets/baseline/wiki/` —— 项目知识摘要，优先用于建立上下文
+   - `<harness_root>/assets/baseline/code/` —— 权威参考实现；禁止引用该目录外的路径作为"参考实现"
+   - `<harness_root>/specs/signals|ui|behavior|interfaces/` —— 若任务与信号/UI/行为/接口相关，必须先对齐 schema
+   - `<harness_root>/tasks/` —— 若存在匹配的任务模板，优先复用
+
+6. **执行与交付**：严格在 `target_project` 下写代码，引用 harness 文件时用
+   相对路径（`harness_root_rel` + 子路径）。不得把 harness 内部文件复制到
+   目标项目；harness 是只读的知识源。
+
+7. **记忆沉淀**：若本次产生了可复用经验，按 agent-env 的 memory 规范追加到
+   `<harness_root>/agent-env/memory/inbox/`（如果目录存在）；不确定时停住询问。
+
+## 守则（不得违反）
+
+- **不得绕过本 skill 内嵌的 `## 绑定元数据` 小节**去猜测 harness 路径；路径错误必须让用户重绑定。
+- **不得修改 harness 目录下的文件**（rules / skills / specs / baseline / VERSION）。
+  harness 是知识源，演进由 `svharnessbuild` 和 harness 内部的 maintainer skill 负责。
+- **不得把 harness 的 always_on rules 当成"建议"**；它们是硬约束。
+- **不得引用 `assets/baseline/code/` 之外的源码**作为"参考实现"。
+- **不得把本 skill 当作业务 skill**：它只做上下文装载 + 路由，业务实现由子 skill 或
+  agent 本体完成。
+- 所有面向用户的说明使用**中文**；字段名、类名、路径保留英文。
+- 多个子 skill 有冲突结论时，显式告知用户并请其裁决，不得自行二选一。
+
+## 典型触发例
+
+- "应用 harness-apply-skills-main 完成无线充电开关功能开发"
+- "基于 harness 新增设置项 Fragment"
+- "按 harness 规范实现新信号 CMDID 0xA3"
+- "apply harness 给我做一个埋点上报"
+
+以上触发均需先走算法 1~5，再进入业务实现。
+
+## 绑定元数据（权威来源，由 svharnessbuild apply 生成，请勿手工编辑）
+
+{{BINDING_YAML_BLOCK}}

package/templates/_shared/build-rules/harness-build-rule-agent-agnostic.md

@@ -0,0 +1,35 @@
+# harness-build-rule-agent-agnostic — harness 框架 agent-agnostic 铁律
+
+harness 是 SDD-Driven Agent-Agnostic Coding Framework。spec 层与 task 层产物必须能被任意符合协议的 agent 消费，禁止硬编码具体 agent 标识。
+
+## 绝对禁止
+
+- 在 `specs/**`、`tasks/**`、`agent-env/rules/**`、`agent-env/memory/categories/**` 的内容里出现以下任一：
+  - 具体 agent 名（如 `qoder`、`codechat`、`cursor`、`claude-code`、`claude`、`chatgpt`、`gpt-4` 等）。
+  - 某一 agent 的私有指令语法（如特定 slash command、特定 frontmatter 字段）。
+  - 某一 agent 的私有目录路径（`.qoder/`、`.codechat/`、`.cursor/`、`.claude/` 等）。
+
+## 允许出现 agent 标识的位置（白名单）
+
+- `svharnessbuild` CLI 源码与模板（负责适配注入，天然需要区分）。
+- `AGENTS.md` 中的"已知 agent 适配状态"段落（描述性说明，非约束性规则）。
+- `.harness-build-state.yaml` 的 `agent` 字段（单一记录当前适配的 agent）。
+
+## 正反例
+
+正例（抽象）：
+> 在 skill 触发时，先读取 `harness.yaml` 再决定下一步动作。
+
+反例（agent 绑定）：
+> 在 Qoder 中使用 `/harness-build-skill-orchestrator` 触发本流程。
+
+正例（目录中性）：
+> 将构建辅助 skills 放在 agent 私有 skills 目录下。
+
+反例（目录硬编码）：
+> 将构建辅助 skills 放在 `.qoder/skills/` 下。
+
+## 违规处理
+
+- P4_specs、P6_skills_tasks 阶段退出前必须 grep 上述黑名单关键词，命中即阶段 FAILED。
+- 历史违规条目在 P-Final_seal 前必须清理或抽象化重写。

package/templates/_shared/build-rules/harness-build-rule-chinese-only.md

@@ -0,0 +1,49 @@
+# harness-build-rule-chinese-only — 产出内容中文强制规则
+
+本规则约束 harness 构建过程中所有面向用户的产出内容必须使用中文。harness 面向中文开发团队，任何 Agent 生成的文档、说明、描述必须以中文为唯一自然语言。
+
+## 适用范围
+
+以下产出**必须**使用中文撰写：
+
+- `assets/requirements/*.requirements.yaml` 中 `description`、`acceptance` 字段
+- `specs/**/*.yaml` 中所有描述性字段（如 `description`、`note`、`summary`、`purpose`）
+- `agent-env/rules/**/*.md` 或 `*.mdc` 中正文段落、正反例注释、检测说明
+- `agent-env/skills/*/SKILL.md` 正文及 description
+- `tasks/templates/**/*.md` 正文
+- `assets/baseline/wiki/**/*.md` 正文段落
+- `agent-env/memory/**/*.md` 正文
+- `AGENTS.md`、`README.md`、`CHANGELOG.md` 正文
+- `.harness-build-state.yaml` 中 `next_action` 字段
+- Agent 向用户输出的所有状态卡片、提示、确认、错误信息
+
+## 保留英文的范围（不译）
+
+以下内容**保持英文不翻译**：
+
+- 代码（函数名、变量名、类名、方法名、包名）
+- 文件路径、目录名
+- 字段名（YAML key、JSON key）
+- 枚举值、CMD ID、信号名
+- 技术术语的标准缩写（MVC、MVVM、UDF、Hilt、AIDL、API、SDK、NDK）
+- git commit hash
+- schema 中的 type/format/pattern 等元数据字段
+
+## 正反例
+
+正例：
+> `description: "根据 P_TMRAVA 信号显示或隐藏预约充电设置入口"`
+
+反例（严禁）：
+> `description: "Show or hide the scheduled charging settings entry based on P_TMRAVA signal"`
+
+正例：
+> `next_action: '请将原始需求文档放入 assets/raw/ 目录后，告诉 Agent 继续构建'`
+
+反例（严禁）：
+> `next_action: 'Say "begin harness build" in your AI agent session to invoke harness-build-skill-orchestrator.'`
+
+## 违规处理
+
+- P-Final_seal 前必须全量扫描上述文件，发现非中文描述即标记阶段 FAILED。
+- 历史违规条目必须在中文化后才能推进到下一阶段。

package/templates/_shared/build-rules/harness-build-rule-memory-write.md

@@ -0,0 +1,31 @@
+# harness-build-rule-memory-write — agent-env/memory 写入规范
+
+本规则约束 harness 内部 `agent-env/memory/` 的流转与写入。所有 agent 在 harness 构建过程中产生的可复用经验，必须按此规范写入。
+
+## 目录结构（固定）
+
+```
+agent-env/memory/
+  inbox/                 (临时登记区：待归档条目)
+  categories/            (正式分类区：按主题分目录)
+    <category-name>/
+      <entry-id>.md
+```
+
+## 写入流程
+
+1. **先落 inbox**：任何新经验先以 `inbox/<timestamp>-<slug>.md` 写入，不得直接写入 categories。
+2. **分类归档**：每次构建阶段退出前，由 orchestrator 或人工将 inbox 条目分类迁入 `categories/<cat>/`，删除 inbox 源文件。
+3. **条目结构**：每条 md 顶部必须含 `title`、`category`、`keywords`、`created_at` 元信息（yaml frontmatter）。
+4. **禁止覆盖**：同名条目已存在时，必须新增新 id 或人工决议合并；禁止静默覆盖历史。
+
+## Agent-agnostic 约束
+
+- 条目正文中提到具体 agent 名时，必须同时列出至少两个不同 agent 的对应动作，否则视为硬编码违规。
+- 记忆条目不得把某个 agent 的内部指令语法直接写入；必须抽象为通用行为描述。
+
+## 触发时机
+
+- 阶段退出时自动扫描 inbox。
+- 用户显式请求"记住...""别忘了..."时写入 inbox。
+- `harness-build-skill-knowledge-builder` 提取 rules 时同步产生的经验写入 inbox。

package/templates/_shared/build-rules/harness-build-rule-orchestrator-flow.md

@@ -0,0 +1,25 @@
+# harness-build-rule-orchestrator-flow — harness 构建阶段流程红线
+
+本规则约束 `harness-build-skill-orchestrator` 驱动的构建阶段准入/退出条件。任何 skill 或人工操作都不得跳过、合并或逆序执行这些阶段。
+
+## 阶段顺序（不得重排）
+
+1. **P1_wiki** — 生成 `assets/baseline/wiki/` 与 `assets/baseline/code/SAMPLES.md`。**仅当项目有 baseline 时存在此阶段**；无 baseline 时跳过。退出：wiki 页面或任务清单可回溯到具体源码。Wiki 是项目经验底座，先于需求文档生成，为后续所有阶段提供架构知识参考。
+2. **P2_raw** — 原始需求文档入库 `assets/raw/`。准入：目录存在；退出：用户已放入至少 1 份原始文档（空目录或仅含 `.gitkeep` 不满足退出条件）。用户可参考 P1_wiki 中的架构知识来撰写更精准的需求。
+3. **P3_requirements** — 由 `harness-build-skill-spec-builder` 将 raw 条目化到 `assets/requirements/`。退出：每条需求有稳定 id 与归属域。
+4. **P4_specs** — 生成 `specs/{signals,ui,behavior,interfaces}/*.yaml`。退出：全部通过 `specs/*/schema.json` 校验。
+5. **P5_rules** — 汇总架构/领域规则到 `agent-env/rules/`。退出：每条规则含正反例各一。
+6. **P6_skills_tasks** — 产出 `agent-env/skills/` 与 `tasks/templates/`。退出：每 skill 有 SKILL.md，tasks 覆盖三类典型场景。
+7. **P7_memory** — 播种 `agent-env/memory/categories/` 初始分类。退出：inbox 流转规则已落地。
+8. **P-Final_seal** — 翻转 `specs.bootstrap_mode = false`，归档。
+
+## 硬约束
+
+- `.harness-build-state.yaml` 只做最小字段补丁，禁止整文件重写。
+- 遇到 `BLOCKED` 阶段必须显式报出阻塞原因，不得静默跳过。
+- 阶段状态流转仅允许 `PENDING → IN_PROGRESS → DONE/FAILED/BLOCKED`。
+- 任一阶段退出条件未满足，`current_phase` 不得推进。
+- **P1_wiki 仅在项目有 baseline 时出现**；无 baseline 时该阶段不存在，不在 state 中写入，流程从 P2_raw 开始。
+- **P2_raw 退出前必须确认 `assets/raw/` 中存在用户放入的真实文档**，Agent 不得自行生成占位文件。
+- **任何涉及流程变更或内容修改的操作必须经用户表单确认**（见 `harness-build-rule-user-interaction`）。
+- **所有面向用户的输出必须使用中文**（见 `harness-build-rule-chinese-only`）。

package/templates/_shared/build-rules/harness-build-rule-skills-tasks-output.md

@@ -0,0 +1,35 @@
+# harness-build-rule-skills-tasks-output — skills 与 tasks 产出规范
+
+本规则约束 P6_skills_tasks 阶段产出物的结构与命名。`harness-build-skill-knowledge-builder` 与人工协作时必须遵守。
+
+## skills 产出
+
+```
+agent-env/skills/
+  <skill-name>/
+    SKILL.md
+```
+
+- 每个 skill **必须**独占一个子目录，主文件**固定命名** `SKILL.md`（大写，不得用 `skill.md` 或 `<name>.md`）。
+- `SKILL.md` 顶部 yaml frontmatter 必备字段：`name`、`description`。description 中需含中英触发关键词。
+- skill 名使用 `kebab-case`，前缀体现领域（如 `dsv-signal-codegen`、`harness-build-skill-orchestrator`）。
+
+## tasks 产出
+
+```
+tasks/templates/
+  <task-category>/
+    <task-name>.md
+```
+
+必须覆盖三类典型场景（缺一不可）：
+
+1. **新增信号/接口/数据**类（由需求驱动的增量）。
+2. **重构/适配**类（由架构/多变体驱动的存量改造）。
+3. **测试/校验**类（由质量保障驱动）。
+
+## 禁止事项
+
+- skill 与 task 文档中不得硬编码任何具体 agent 的私有指令格式（见 harness-build-rule-agent-agnostic.md）。
+- skill 描述中不得出现"本 agent""本工具"一类自指代，必须写明能力本身。
+- 产出物必须可被任意符合 SKILL.md 规范的 agent 消费。

package/templates/_shared/build-rules/harness-build-rule-specs-schema.md

@@ -0,0 +1,32 @@
+# harness-build-rule-specs-schema — specs 层 schema 校验铁律
+
+本规则约束 harness `specs/` 层的结构与校验流程。任何 spec 产出、变更、审查都必须通过对应 `schema.json`。
+
+## 四域固定不变
+
+```
+specs/
+  signals/     (+ schema.json)
+  ui/          (+ schema.json)
+  behavior/    (+ schema.json)
+  interfaces/  (+ schema.json)
+```
+
+域名、目录名、schema 文件名均为约定名称，禁止改名或增删。任何新需求必须归入这四域之一，无法归入即提醒用户重新审视需求颗粒度。
+
+## 写入前置
+
+- 写入任一 `specs/<domain>/*.yaml` 前，必须先读 `specs/<domain>/schema.json`。
+- 字段增减/重命名时，`schema.json` 与对应 yaml 必须**同一提交**更新，不得分两步。
+- yaml 中不得出现任何具体 agent 名（qoder/codechat/cursor/claude-code 等）— 违反 agent-agnostic 铁律。
+
+## 校验节点
+
+- P3_specs 退出前：所有 yaml 逐一过 schema 校验，失败则阶段状态置 FAILED。
+- 后续阶段读取 specs 时不做 schema 校验（已由 P3 把关），但仍不得修改已冻结字段。
+
+## 正反例
+
+正例：为 signals 新增一条物理信号前，先扩展 `signals/schema.json.properties`，再写 `signals/hvac.yaml`。
+
+反例（严禁）：直接在 yaml 里新增一个未在 schema 中声明的自由字段 `agent_hint`。

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

@@ -0,0 +1,63 @@
+# harness-build-rule-user-interaction — 用户交互铁律
+
+本规则约束 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/` 目录"
+  2. 等待用户确认已完成文件放入后，再校验目录内容并推进阶段状态
+
+## 红线二：必须以表单方式与用户交互
+
+当 Agent 需要与用户交流信息或等待用户确认时，**必须**使用表单确认机制（如 `ask_user_question` 工具或等价的交互式表单），**禁止**仅以纯文本方式输出提示后自行继续。
+
+适用场景（不限于）：
+- 阶段准入确认："是否继续进入 P3_requirements 阶段？"
+- 文档缺失提示："assets/raw/ 中未发现需求文档，请放入后确认"
+- 阶段产出审查："P4_specs 已生成 4 个模块的 YAML，是否通过校验？"
+- 关键决策点："是否要调整 schema？/ 是否跳过该需求？"
+- 流程变更征询："是否要将该规则纳入 P5_rules？"
+
+**禁止的做法**：
+- 在终端输出一段文字后直接继续执行下一阶段
+- 假设用户"默认同意"而跳过确认
+- 用纯文本输出"请确认(y/n)"然后自行判定为 y
+
+## 红线三：禁止未经用户同意修改 harness 构建流程或内容
+
+Agent **不得**在以下行为上自行决定，**必须**先征求用户同意：
+
+- 修改 `.harness-build-state.yaml` 中 `current_phase` 的跳转方向（如跳过某阶段）
+- 修改 `harness.yaml` 中的 `specs.layers` 配置（增删层、改 schema 路径）
+- 修改任何 `specs/*/schema.json`（字段增删、类型变更）
+- 修改 `AGENTS.md` 中的构建流程步骤
+- 新增、删除或重命名 `agent-env/rules/` 下的规则文件
+- 调整阶段退出条件（如降低校验标准以通过某个阶段）
+
+**允许的自主行为**（无需额外确认）：
+- 按 `harness-build-rule-orchestrator-flow` 规则正常推进阶段状态
+- 在 specs 目录下生成符合 schema 的 YAML 文件
+- 按 `harness-build-rule-memory-write` 规范写入 memory
+- 最小补丁式更新 `.harness-build-state.yaml` 的 `status`/`completed_at`/`updated_at`
+
+## 正反例
+
+正例（等待用户放入文档）：
+> Agent 检测到 `assets/raw/` 为空，输出表单提示用户放入文档，暂停等待。
+
+反例（擅自生成）：
+> Agent 发现 `assets/raw/` 为空，自行生成 `placeholder-requirements.md` 填入后标记 P2_raw 为 DONE。
+
+正例（表单确认）：
+> Agent 完成 P4_specs 后，使用 `ask_user_question` 呈现校验结果，等待用户确认通过。
+
+反例（纯文本跳过）：
+> Agent 输出"P4_specs 已完成"后直接将阶段标记为 DONE 并推进到下一阶段。
+
+## 违规处理
+
+- 任何违反上述红线的 Agent 行为，用户可随时回退该阶段状态为 FAILED。
+- P-Final_seal 阶段需审查是否有过未经确认的流程修改。

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

@@ -0,0 +1,120 @@
+---
+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-build-skill-knowledge-builder（知识层构建器）
+
+你负责构建 harness 中**可复用的知识层**（不含 wiki 正文）——那些 specs 无法表达、但未来 task 执行时
+仍需依赖的内容：基线代码样本、编码规则、skills 与 tasks 索引。
+
+> 职责边界：**baseline wiki 正文的逐页撰写不在本 skill 范围内**，由 harness-build-skill-wiki-writer 专职完成。
+> 本 skill 只对 `assets/baseline/code/` 做"代表样本挑选"（如需要）。
+
+## 输入
+
+- `__HARNESS_ROOT__specs/**` —— 必须已构建（依赖 P3 为 DONE）
+- `__HARNESS_ROOT__assets/requirements/**` —— 用于将规则回溯到需求
+- `__HARNESS_ROOT__assets/baseline/code/` —— CLI 的 `--baseline` 已完成全量拷贝
+- `__HARNESS_ROOT__harness.yaml` —— 确认哪些知识通道当前激活
+
+## 本 skill 负责的阶段
+
+### P1 —— baseline/code（参考代码样本，可选子任务）
+
+目标：在 `__HARNESS_ROOT__assets/baseline/code/` 已有全量快照的基础上，**可选地**挑出"代表性样本清单"供 P5/P6 参考。
+
+> 说明：CLI 的 `--baseline` 已将基线源码全量拷贝到 `__HARNESS_ROOT__assets/baseline/code/`；本步骤不拷贝任何文件，
+> 只是在有必要时产出一份 `__HARNESS_ROOT__assets/baseline/code/SAMPLES.md` 罗列约 20 个典型样本，便于规则抽取回溯。
+> 如果不需要可直接跳过。
+
+选型策略（硬上限：约 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/` 的路径引用，不再另外拷贝文件。
+
+禁止：
+- **不得**重新拷贝或删除 `__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`）
+- 信号流向（车→机 / 机→车 不得绕过）
+
+### P6 —— skills & tasks 索引
+
+目标：填充 `__HARNESS_ROOT__agent-env/skills/` 与 `__HARNESS_ROOT__tasks/templates/`，放入**构建期沉淀**下来的 **运行期 skill**
+（区别于 Agent IDE 中的 build-skill）。
+
+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 与规则**，不要内联其内容。
+
+## 状态更新
+
+每完成一个子阶段：
+- 更新 `__HARNESS_ROOT__.harness-build-state.yaml`（P5 / P6 的 `status`；P1 的"样本清单"子任务若产出，一并记录）。
+- 记录计数：`baseline_code_samples` / `rules_count` / `skills_count` / `tasks_count`。
+- 刷新 `updated_at`。
+
+## 守则（不得违反）
+
+- **不得撰写或编辑 baseline wiki 正文**（交给 harness-build-skill-wiki-writer）。
+- **不得凭空编造架构**：所有结论必须落地到源码或 specs。无法追溯的推断一律舍弃。
+- **规则必须同时有正例与反例**，否则规则文件视为不合格。
+- **不得从本 skill 内编辑 specs 或 schema**。若规则与 specs 冲突，立即停止并上报 orchestrator。
+- 所有对用户的说明使用中文；路径、字段名、类名保留英文。
+- **必须以表单方式**与用户交互确认，禁止仅以纯文本输出后自行继续。
+- **所有描述性字段必须使用中文**（见 `harness-build-rule-chinese-only`）。
+
+## 必须遵守的构建规则（位于 Agent rules 目录）
+
+本 skill 执行前必须加载并严格遵循（文件位于当前 agent 的 rules 目录，具体路径/扩展名
+随 agent 可能为 `.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` — 用户交互铁律：表单确认、禁止擅自修改。
+
+若规则文件缺失，停止工作并提示用户重新运行 `svharnessbuild init`。
+

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

@@ -0,0 +1,87 @@
+---
+name: harness-build-skill-orchestrator
+description: >
+  Harness 构建总调度。读取 __HARNESS_ROOT__.harness-build-state.yaml，报告当前阶段，路由到合适的下游 skill，
+  并在每步完成后更新阶段状态。当用户说"开始构建 harness"、"继续构建 harness"、"harness 进度"、
+  "下一步干什么"、"begin harness build"、"continue harness build" 等时触发。
+---
+
+# harness-build-skill-orchestrator（构建总调度）
+
+你是本 SDD harness 的构建总指挥。你的职责只有四件事：**读取状态 → 报告现状 → 路由到对应 skill → 更新状态**。
+
+## 输入
+
+- `__HARNESS_ROOT__.harness-build-state.yaml`（状态机，权威进度来源）
+- `__HARNESS_ROOT__harness.yaml`（清单：路径、版本、层配置）
+- `__HARNESS_ROOT__AGENTS.md`（Agent 协作协议参考）
+
+## 算法
+
+1. 读取 `__HARNESS_ROOT__.harness-build-state.yaml`。若文件不存在，打印错误并提示用户先运行 `svharnessbuild init`。
+2. 识别 `current_phase` 及其 `status`。
+3. 对当前阶段，以"状态卡片"形式输出：
+   - 阶段 id + 一句话说明
+   - 预期产物（哪些目录下的哪些文件）
+   - 是否需要人工（`manual_required: true`）或需要 Agent 工作（`requires_agent: true`）
+   - 推荐下一步调用哪个 skill
+4. **必须以表单确认方式**询问用户是否继续，未经用户确认不得自行推进：
+   - **P1_wiki** — 读取 state 中该 phase 的语义字段决定行为：
+     - phase **不存在** → 跳过（本项目无 baseline，直接推进到 P2_raw）。
+     - `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`），
+       委派给 `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。
+5. 每次完成后，**最小增量补丁**更新 `__HARNESS_ROOT__.harness-build-state.yaml`：
+   - 已完成阶段标记 `status: DONE`，填写 `completed_at`
+   - 将 `current_phase` 推进到下一个 PENDING 阶段
+   - 用一句具体可执行的建议更新 `next_action`
+   - 顶层 `updated_at` 刷新为当前 ISO8601 时间
+
+## 输出格式
+
+每次响应必须以状态卡片开头：
+
+```
+阶段:     P3_specs (IN_PROGRESS)
+需要:     agent
+已完成:   signals (4 个模块), ui (4 个模块)
+待处理:   behavior, interfaces, 校验
+下一步:   harness-build-skill-spec-builder（behavior 模块）
+```
+
+随后**必须以表单方式**（如 `ask_user_question`）询问："是否继续？" —— 不得仅以纯文本输出后自行继续。
+
+## 守则（不得违反）
+
+- **绝不跳过阶段**。遇到 `BLOCKED` 阶段，必须显式报出阻塞原因。
+- **绝不未经确认删除文件**。
+- **绝不整文件重写** `__HARNESS_ROOT__.harness-build-state.yaml`，只做最小字段补丁。
+- **绝不未经用户表单确认就修改构建流程或内容**（见 `harness-build-rule-user-interaction`）。
+- 若状态文件 YAML 解析失败，立即停止并请求人工修复。
+- 所有面向用户的输出使用中文；字段名、路径、CMD ID 等保留英文不译。
+
+## 必须遵守的构建规则（位于 Agent rules 目录）
+
+执行任何阶段前，先加载并严格遵循以下规则（文件位于当前 agent 的 rules 目录，
+如 `.qoder/rules/`、`.codechat/rules/`、`.cursor/rules/harness-build/`、
+`.claude/rules/`、`.harness/rules/`，具体扩展名随 agent 可能为 `.md` 或 `.mdc`）：
+
+- `harness-build-rule-orchestrator-flow` — 构建阶段准入/退出红线，任何调度决策都必须匹配。
+- `harness-build-rule-specs-schema` — P4 阶段生成的 YAML 必须通过对应 schema.json。
+- `harness-build-rule-memory-write` — 若本阶段有可复用经验，按 inbox → categories 流转写入。
+- `harness-build-rule-skills-tasks-output` — 委派 P6 时，产物结构/命名必须符合该规则。
+- `harness-build-rule-agent-agnostic` — 产出文本中严禁出现任何具体 agent 名或其私有指令语法。
+- `harness-build-rule-chinese-only` — 所有面向用户的产出内容必须使用中文。
+- `harness-build-rule-user-interaction` — 用户交互铁律：等待 raw、表单确认、禁止擅自修改。
+
+若上述规则文件缺失，先提醒用户重新运行 `svharnessbuild init` 恢复规则注入，再继续工作。