svharness 0.8.0 → 0.13.2

package/dist/utils/validate-args.js

@@ -7,8 +7,12 @@ exports.detectBaselineMode = detectBaselineMode;
 exports.validateArgs = validateArgs;
 exports.listSupportedArches = listSupportedArches;
 exports.listSupportedAgents = listSupportedAgents;
+exports.isHarnessRoot = isHarnessRoot;
+exports.resolveConvertPaths = resolveConvertPaths;
+exports.validateConvertArgs = validateConvertArgs;
 const fs_extra_1 = __importDefault(require("fs-extra"));
 const node_path_1 = __importDefault(require("node:path"));
+const harness_name_1 = require("./harness-name");
 const SUPPORTED_ARCHES = [
     'android-compose',
     'android-xml',
@@ -21,9 +25,9 @@ const SUPPORTED_AGENTS = [
     'qoder',
     'cursor',
     'claude-code',
+    'opencode',
     'generic',
 ];
-const NAME_RE = /^[a-z][a-z0-9-]{1,39}$/;
 const DEFAULT_BASELINE_MAX_FILE_KB = 1024;
 /**
  * Decide whether the `--baseline` value looks like a git remote or a local path.
@@ -55,12 +59,19 @@ function detectBaselineMode(input) {
 }
 function validateArgs(input) {
     const errors = [];
-    // name
+    // name (normalized to leading `.`, e.g. my-app → .my-app)
+    let normalizedName;
     if (!input.name) {
-        errors.push('--name is required');
+        errors.push('--harness-name is required');
     }
-    else if (!NAME_RE.test(input.name)) {
-        errors.push(`--name "${input.name}" is invalid. Allowed: lowercase letters, digits, hyphen; start with letter; length 2-40.`);
+    else {
+        const nameCheck = (0, harness_name_1.validateHarnessNameInput)(input.name);
+        if (!nameCheck.ok) {
+            errors.push(nameCheck.message);
+        }
+        else {
+            normalizedName = nameCheck.normalized;
+        }
     }
     // arch
     if (!input.arch) {
@@ -115,7 +126,7 @@ function validateArgs(input) {
         throw new Error('Argument validation failed:\n  - ' + errors.join('\n  - '));
     }
     return {
-        name: input.name,
+        name: normalizedName ?? (0, harness_name_1.normalizeHarnessName)(input.name),
         arch: input.arch,
         agent: input.agent,
         baseline: baselineValue,
@@ -130,3 +141,133 @@ function listSupportedArches() {
 function listSupportedAgents() {
     return SUPPORTED_AGENTS;
 }
+const DEFAULT_CONCURRENCY = 3;
+const DEFAULT_MAX_FILE_MB = 50;
+const DEFAULT_TIMEOUT_SEC = 120;
+const DEFAULT_ENDPOINT = 'http://markitdown.desaysz.site';
+const ENV_ENDPOINT = 'SVHARNESS_MARKITDOWN_ENDPOINT';
+const DEFAULT_CONVERT_TYPE = 'requirements';
+/** True when `dir` exists and contains `harness.yaml`. */
+function isHarnessRoot(dir) {
+    return fs_extra_1.default.existsSync(node_path_1.default.join(dir, 'harness.yaml'));
+}
+function harnessMdDir(harnessRoot, type) {
+    return node_path_1.default.join(harnessRoot, type, 'md');
+}
+/**
+ * Resolve markdown output directory vs harness layout.
+ *
+ * - Standalone: `--output` is the final md directory (no `harness.yaml` under it).
+ * - Harness: `--output` points at harness root (has `harness.yaml`), or `--harness` is set
+ *   → writes to `<harness>/<type>/md/` unless both `--harness` and `--output` are given
+ *   (then `--output` is the final directory).
+ */
+function resolveConvertPaths(input) {
+    const outputProvided = input.output !== undefined;
+    const outputAbs = node_path_1.default.resolve(input.output ?? '.');
+    const harnessExplicit = !!input.harness;
+    if (harnessExplicit) {
+        const harnessRoot = node_path_1.default.resolve(input.harness);
+        if (outputProvided) {
+            return {
+                outputDir: outputAbs,
+                harnessRoot,
+                harnessMode: true,
+            };
+        }
+        return {
+            outputDir: harnessMdDir(harnessRoot, input.type),
+            harnessRoot,
+            harnessMode: true,
+        };
+    }
+    if (isHarnessRoot(outputAbs)) {
+        return {
+            outputDir: harnessMdDir(outputAbs, input.type),
+            harnessRoot: outputAbs,
+            harnessMode: true,
+        };
+    }
+    return {
+        outputDir: outputAbs,
+        harnessMode: false,
+    };
+}
+/**
+ * Validate and normalise options for `svharness convert`.
+ *
+ * All parameters have sensible defaults:
+ *  - --input defaults to `.` (current directory)
+ *  - --endpoint defaults to http://markitdown.desaysz.site
+ *  - --output defaults to `.` (current directory); see `resolveConvertPaths` for layout
+ *
+ * When --harness is explicitly given, it must exist and contain harness.yaml.
+ */
+function validateConvertArgs(input) {
+    const errors = [];
+    // input: default to ['.']
+    const patterns = (input.input ?? ['.']).map((s) => s.trim()).filter(Boolean);
+    const harnessExplicit = !!input.harness;
+    if (harnessExplicit) {
+        const harnessAbs = node_path_1.default.resolve(input.harness);
+        if (!fs_extra_1.default.existsSync(harnessAbs)) {
+            errors.push(`--harness path does not exist: ${harnessAbs}`);
+        }
+        else if (!fs_extra_1.default.statSync(harnessAbs).isDirectory()) {
+            errors.push(`--harness must be a directory: ${harnessAbs}`);
+        }
+        else if (!input.allowMissingHarnessYaml && !isHarnessRoot(harnessAbs)) {
+            errors.push(`--harness "${harnessAbs}" does not look like a harness root (missing harness.yaml)`);
+        }
+    }
+    // endpoint: flag > env > default
+    let endpoint = (input.endpoint && input.endpoint.trim()) ||
+        (process.env[ENV_ENDPOINT] && process.env[ENV_ENDPOINT].trim()) ||
+        DEFAULT_ENDPOINT;
+    try {
+        const u = new URL(endpoint);
+        if (!/^https?:$/.test(u.protocol)) {
+            errors.push(`--endpoint must use http(s) scheme, got: ${u.protocol}`);
+        }
+        // strip trailing slash for consistent downstream concatenation
+        endpoint = endpoint.replace(/\/+$/, '');
+    }
+    catch {
+        errors.push(`--endpoint is not a valid URL: ${endpoint}`);
+    }
+    const concurrency = positiveInt(input.concurrency, DEFAULT_CONCURRENCY, '--concurrency', errors);
+    const maxFileMB = positiveInt(input.maxFileMB, DEFAULT_MAX_FILE_MB, '--max-file-mb', errors);
+    const timeoutSec = positiveInt(input.timeoutSec, DEFAULT_TIMEOUT_SEC, '--timeout-sec', errors);
+    // type: validate ConvertTargetType
+    const convertType = input.type && ['requirements', 'references'].includes(input.type)
+        ? input.type
+        : DEFAULT_CONVERT_TYPE;
+    if (errors.length > 0) {
+        throw new Error('Argument validation failed:\n  - ' + errors.join('\n  - '));
+    }
+    const paths = resolveConvertPaths({
+        harness: input.harness,
+        output: input.output,
+        type: convertType,
+    });
+    return {
+        input: patterns,
+        outputDir: paths.outputDir,
+        harnessRoot: paths.harnessRoot,
+        harnessMode: paths.harnessMode,
+        endpoint,
+        concurrency,
+        maxFileMB,
+        timeoutSec,
+        type: convertType,
+    };
+}
+function positiveInt(raw, fallback, flag, errors) {
+    if (raw === undefined)
+        return fallback;
+    if (!Number.isFinite(raw) || raw <= 0) {
+        errors.push(`${flag} must be a positive number, got: ${raw}`);
+        return fallback;
+    }
+    return Math.floor(raw);
+}

package/dist/wiki/wikiTasksWriter.js

@@ -2,7 +2,7 @@
 /**
  * Writes a `TASKS.md` inside `<wikiBase>/` based on an outline computed by
  * `runRepowikiOutlineOnly`. The file is consumed by the downstream
- * harness-build-skill-knowledge-builder skill which fills page content iteratively.
+ * harness-build-skill-wiki-writer skill which fills page content iteratively.
  */
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
@@ -72,10 +72,10 @@ function renderTasksMarkdown(input) {
     lines.push("> 每页应产出 Markdown 文件到对应 `Output` 路径，内容严格基于基线源码。");
     lines.push("");
     lines.push("> **源码引用规范（强制，与 --generate-wiki 产出口径保持一致）**：");
-    lines.push("> 所有源码链接必须指向 `assets/baseline/code/` 下的路径，允许两种写法（可混用）：");
-    lines.push("> 1. 行内链接：`[Foo.java:10-30](../../../assets/baseline/code/<repo-relative>/Foo.java#L10-L30)`");
+    lines.push("> 所有源码链接必须指向 `baseline/code/` 下的路径，允许两种写法（可混用）：");
+    lines.push("> 1. 行内链接：`[Foo.java:10-30](../../baseline/code/<repo-relative>/Foo.java#L10-L30)`");
     lines.push("> 2. Sources 行：`Sources: <repo-relative>/Foo.java:10-30, <repo-relative>/Bar.kt:5-8`");
-    lines.push("> `<repo-relative>` 指**相对 `assets/baseline/code/` 的路径**，既非仓库原始绝对路径，");
+    lines.push("> `<repo-relative>` 指**相对 `baseline/code/` 的路径**，既非仓库原始绝对路径，");
     lines.push("> 也非 wiki md 文件的相对路径。行号使用 `start-end`（闭区间）。");
     lines.push("");
     lines.push("## Sections");
@@ -109,8 +109,7 @@ function renderTasksMarkdown(input) {
         lines.push(`  - 文件存在且非空`);
         lines.push(`  - 首段含页面标题（H1 与 title 一致）`);
         lines.push(`  - 至少引用 1 个 Relevant files 中的源码片段或路径`);
-        lines.push(`  - Sources 行或行内链接的路径必须定位到 \`assets/baseline/code/\` 下的真实文件`);
-        lines.push("");
+        lines.push(`  - Sources 行或行内链接的路径必须定位到 \`baseline/code/\` 下的真实文件`);
     }
     return lines.join("\n");
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "svharness",
-  "version": "0.8.0",
+  "version": "0.13.2",
   "description": "CLI scaffolder for SDD-Driven Agent-Agnostic Coding Framework (harness)",
   "bin": {
     "svharness": "./bin/cli.js",
@@ -10,6 +10,7 @@
     "dist/",
     "bin/",
     "templates/",
+    "templates/svharness.config.example.yaml",
     "README.md"
   ],
   "engines": {

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

@@ -1,91 +1,32 @@
 ---
 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 应用入口（薄索引模式）。提示用户当前项目已注入 runtime skills/rules，
+  优先直接调用已注入的 `harness-apply-skills-*` 子 skill；如无匹配，再按普通开发流程执行。
 ---
 
-# harness-apply-skills-main（harness 应用二级调度）
+# harness-apply-skills-main（harness 应用入口）
 
-你是一个 **harness 知识层调度器**。当用户请求基于当前项目绑定的 harness
-完成功能开发时，你不直接写业务代码，而是先把 harness 的约束、能力、基线、规格
-装载到上下文，再按语义把任务路由到 harness 内部的子 skill。
+你是一个 **harness 应用入口提示器**。当前项目已经注入运行期 rules 与 skills：
 
-> 本 skill 由 `svharnessbuild apply` 注入。harness 本体可能位于目标项目之外
-> 的任意路径（方案 B：不同根），因此**所有 harness 文件引用必须通过本 skill
-> 正文末尾的 `## 绑定元数据` YAML 块中的 `harness_root` 解析**，禁止假设相对
-> 位置，也不要去读取外部 `binding.yaml`——它只是冗余副本，不是权威来源。
+- harness 根目录：`__HARNESS_ROOT_REL__`
+- 运行期技能目录：`__HARNESS_ROOT_REL__/agent-env/skills/`
+- 运行期规则目录：`__HARNESS_ROOT_REL__/agent-env/rules/`
 
-## 输入
+## 使用原则
 
-- **本 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. 优先枚举当前项目已注入的 `harness-apply-skills-*` 子 skill，并调用最匹配者完成任务。
+2. 每次任务必须遵守已注入的 rules（always_on 优先）。
+3. 若没有匹配 skill，按普通实现流程完成，但仍需参考 `__HARNESS_ROOT_REL__/specs/`、`__HARNESS_ROOT_REL__/baseline/`。
+4. 不修改 `__HARNESS_ROOT_REL__` 下的任何文件；harness 作为只读知识源。
 
-## 算法
+## 典型触发
 
-1. **加载绑定**：从本 skill 正文末尾的 `## 绑定元数据` 小节（fenced ```yaml 代码块）
-   解析 `harness_root` 等字段。若解析失败或 `harness_root` 指向的目录不存在，
-   停止并提示用户重新运行 `svharnessbuild apply --force`。
+- 应用 harness-apply-skills-main 完成 xxx 功能开发
+- 使用 harness 开发 xxx
+- 基于 harness 做 xxx
 
-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}}
+- 本 skill 不负责二级调度与 binding 解析。
+- 如发现路径不一致，请重新执行 `svharness apply --force`。

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

@@ -5,14 +5,14 @@ harness 是 SDD-Driven Agent-Agnostic Coding Framework。spec 层与 task 层产
 ## 绝对禁止
 
 - 在 `specs/**`、`tasks/**`、`agent-env/rules/**`、`agent-env/memory/categories/**` 的内容里出现以下任一：
-  - 具体 agent 名（如 `qoder`、`codechat`、`cursor`、`claude-code`、`claude`、`chatgpt`、`gpt-4` 等）。
+  - 具体 agent 名（如 `qoder`、`codechat`、`cursor`、`claude-code`、`opencode`、`claude`、`chatgpt`、`gpt-4` 等）。
   - 某一 agent 的私有指令语法（如特定 slash command、特定 frontmatter 字段）。
-  - 某一 agent 的私有目录路径（`.qoder/`、`.codechat/`、`.cursor/`、`.claude/` 等）。
+  - 某一 agent 的私有目录路径（`.qoder/`、`.codechat/`、`.cursor/`、`.claude/`、`.opencode/` 等）。
 
 ## 允许出现 agent 标识的位置（白名单）
 
 - `svharnessbuild` CLI 源码与模板（负责适配注入，天然需要区分）。
-- `AGENTS.md` 中的"已知 agent 适配状态"段落（描述性说明，非约束性规则）。
+- `AGENTS_BUILD.md` 中的"已知 agent 适配状态"段落（描述性说明，非约束性规则）。
 - `.harness-build-state.yaml` 的 `agent` 字段（单一记录当前适配的 agent）。
 
 ## 正反例
@@ -31,5 +31,5 @@ harness 是 SDD-Driven Agent-Agnostic Coding Framework。spec 层与 task 层产
 
 ## 违规处理
 
-- P4_specs、P6_skills_tasks 阶段退出前必须 grep 上述黑名单关键词，命中即阶段 FAILED。
-- 历史违规条目在 P-Final_seal 前必须清理或抽象化重写。
+- S50_generate_specs、S70_runtime_assets 阶段退出前必须 grep 上述黑名单关键词，命中即阶段 FAILED。
+- 历史违规条目在 S90_finalize 前必须清理或抽象化重写。

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

@@ -6,14 +6,14 @@
 
 以下产出**必须**使用中文撰写：
 
-- `assets/requirements/*.requirements.yaml` 中 `description`、`acceptance` 字段
+- `requirements/yaml/*.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` 正文段落
+- `baseline/wiki/**/*.md` 正文段落
 - `agent-env/memory/**/*.md` 正文
-- `AGENTS.md`、`README.md`、`CHANGELOG.md` 正文
+- `AGENTS_BUILD.md`、`README.md`、`CHANGELOG.md` 正文
 - `.harness-build-state.yaml` 中 `next_action` 字段
 - Agent 向用户输出的所有状态卡片、提示、确认、错误信息
 
@@ -38,12 +38,12 @@
 > `description: "Show or hide the scheduled charging settings entry based on P_TMRAVA signal"`
 
 正例：
-> `next_action: '请将原始需求文档放入 assets/raw/ 目录后，告诉 Agent 继续构建'`
+> `next_action: '请将原始需求文档放入 requirements/raw/ 目录后，告诉 Agent 继续构建'`
 
 反例（严禁）：
 > `next_action: 'Say "begin harness build" in your AI agent session to invoke harness-build-skill-orchestrator.'`
 
 ## 违规处理
 
-- P-Final_seal 前必须全量扫描上述文件，发现非中文描述即标记阶段 FAILED。
+- S90_finalize 前必须全量扫描上述文件，发现非中文描述即标记阶段 FAILED。
 - 历史违规条目必须在中文化后才能推进到下一阶段。

package/templates/_shared/build-rules/harness-build-rule-convert-check.md

@@ -0,0 +1,46 @@
+# harness-build-rule-convert-check — 原始文档转换前置检查规则
+
+本规则约束 `S30_convert_docs` 阶段中 Agent 对 `requirements/raw/` 和 `references/raw/` 中原始文档的转换行为。
+
+## 检查范围
+
+Agent 在进入 S30_convert_docs 阶段后必须逐一检查以下两个目录：
+
+- `__HARNESS_ROOT__requirements/raw/` —— 正式需求的原始文档
+- `__HARNESS_ROOT__references/raw/` —— 参考资料原始文档
+
+## 转换前置检查
+
+对上述两个目录执行以下检查：
+
+1. **列出原始文件**：扫描目录，识别所有非 `.md`、非 `.gitkeep` 的文件（如 `.pdf`、`.docx`、`.pptx`、`.xlsx`、`.html`、`.txt`、`.csv` 等）。
+2. **检查对应 md 是否存在**：对每个原始文件，检查对应 `md/` 目录中是否存在同基名的 `.md` 文件（如 `requirements/raw/需求文档.pdf` → `requirements/md/需求文档.md`）。
+3. **判断是否需要转换**：仅当 `md/` 中缺少对应文件时，才需要执行转换；已存在的跳过。
+
+## 转换方式（按优先级）
+
+1. **优先调用 CLI**：若运行环境支持，直接调用 `svharness convert --input <raw文件或目录> --output __HARNESS_ROOT__ --type requirements` 或 `--type references` 完成转换。
+2. **提示用户手动运行**：若 Agent 无法直接调用 CLI，以表单形式提示用户运行上述命令，并提供完整命令示例。
+
+## 产物校验
+
+转换完成后，Agent 必须校验：
+
+- `requirements/md/` 包含 `requirements/raw/` 中每份非 md 源文档对应的 `.md` 文件
+- `references/md/` 包含 `references/raw/` 中每份非 md 源文档对应的 `.md` 文件
+
+## 禁止事项
+
+- **不得删除原始文件**：`raw/` 中的源文档保留作为原始证据，不得移动或删除。
+- **不得在 raw 下生成 converted_md**：转换产物只能写入 `__HARNESS_ROOT__requirements/md/` 或 `__HARNESS_ROOT__references/md/`；禁止在 `raw/` 内创建 `converted_md/` 或其它中间目录。
+- **不得无中生有**：禁止在 `md/` 中生成无 `raw/` 源文件对应的 `.md` 文件。
+- **不得跳过校验**：即使调用 CLI 成功，也必须确认产物文件存在。
+- **不得修改文件内容**：转换为 Markdown 后，内容应忠实反映源文档，Agent 不得在转换过程中添加、删除或修改信息。
+
+## 失败处理
+
+若某个文件转换失败（如文件损坏、格式不支持），Agent 应：
+
+- 记录失败文件路径和原因
+- 以表单形式告知用户，并提供手动处理建议
+- 其他文件继续完成转换，不因单文件失败阻塞整个阶段

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

@@ -28,4 +28,4 @@ agent-env/memory/
 
 - 阶段退出时自动扫描 inbox。
 - 用户显式请求"记住...""别忘了..."时写入 inbox。
-- `harness-build-skill-knowledge-builder` 提取 rules 时同步产生的经验写入 inbox。
+- `harness-build-skill-references-intake` 或 `harness-build-skill-agent-env-merge` 处理 references/规则候选时同步产生的经验写入 inbox。

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

@@ -4,14 +4,36 @@
 
 ## 阶段顺序（不得重排）
 
-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`，归档。
+1. **S10_wiki** — 生成 `baseline/wiki/` 与 `baseline/code/SAMPLES.md`。**仅当项目有 baseline 时存在此阶段**；无 baseline 时跳过。退出：wiki 页面或任务清单可回溯到具体源码。Wiki 是项目经验底座，先于需求文档生成，为后续所有阶段提供架构知识参考。
+2. **S20_collect_inputs** — 添加相关文件（四项输入收集）。
+   - 2.1 需求文档：提醒用户放入 `requirements/raw/`（也可由用户在 svharness 指令中指定来源路径）。
+   - 2.2 参考资料：提醒用户放入 `references/raw/`（也可由用户在 svharness 指令中指定来源路径）。
+  - 2.3 额外运行期资源：询问是否通过 `--extra-skills <path...>` 提供（支持文件/目录/glob，可混放 skills/rules，先暂存到 `agent-env/_incoming/skills/`）。
+  - 2.4 类型确认约束：若有规则或未知类型资源，必须在 S65 依据 `agent-env/_incoming/manifest.yaml` 完成分流确认后再写入最终目录。
+   准入：四类目标目录存在；退出：`requirements/raw/` 至少 1 份真实文档，且其余三项已完成"已提供/无新增"确认。
+3. **S30_convert_docs** — 将 `requirements/raw/` 和 `references/raw/` 中的非 Markdown 原始文档统一转为 Markdown，产物落到对应 `md/` 目录。准入：S20_collect_inputs DONE；退出：每份源文档在对应 `md/` 目录中有同基名的 `.md` 文件。
+4. **S40_extract_requirements** — 由 `harness-build-skill-spec-builder` 将 raw 条目化到 `requirements/yaml/`。退出：每条需求有稳定 id 与归属域。
+5. **S50_generate_specs** — 生成 `specs/{signals,ui,behavior,interfaces}/*.yaml`。退出：全部通过 `specs/*/schema.json` 校验。
+6. **S60_process_references**（阶段叙事：**references 处理**）— 对 S20 中的 references 执行处理与结构化：
+   - 必须执行 `svharness convert`，不得跳过转换直接抽取；
+   - 必须产出结构化索引（规制约束 / skills 候选 / signals / manuals，缺项需显式标注）；
+   - references 落地策略需经用户表单确认。
+   退出：references 已完成转换、结构化索引与落地确认。
+7. **S61_confirm_baseline_extraction**（阶段叙事：**baseline 自动提取确认**）— 在进入 agent-env 写入前，确认是否启用从 baseline 自动提取 skills/rules。
+   - 必须以表单明确选择：启用 / 关闭；
+   - 未确认不得默认启用自动提取；
+   - 确认结果必须可被后续阶段读取（用于 S65 策略分支），建议写入 `phases.S61_confirm_baseline_extraction.baseline_auto_extract`。
+   退出：自动提取开关状态已确认并记录。
+8. **S65_customize_agent_env**（阶段叙事：**agent-env 定制**）— 对 S20 中的 extra-skills / extra-rules 执行合并写入（来源可来自单入口 `--extra-skills` 的 `_incoming/manifest.yaml`；若 S61 启用，可纳入 baseline 自动提取候选）。
+   - 任何冲突（同名文件、目录已存在、命名不符合规范、语义重复）必须先给出修改建议；
+   - 待用户表单确认后再写入；
+   - 未确认不得覆盖。
+   退出：extra-skills / extra-rules 完成"无冲突写入"或"冲突已确认后写入/跳过"。
+9. **S70_runtime_assets** — 产出运行期 `agent-env/skills/` 与 `tasks/templates/`。
+   语义约束：skills 是执行 task 的能力积木，task 是可复用的流程模板。
+   退出：每 skill 有 SKILL.md，tasks 覆盖三类典型场景。
+10. **S80_seed_memory** — 播种 `agent-env/memory/categories/` 初始分类。退出：inbox 流转规则已落地。
+11. **S90_finalize** — 翻转 `specs.bootstrap_mode = false`，归档。
 
 ## 硬约束
 
@@ -19,7 +41,11 @@
 - 遇到 `BLOCKED` 阶段必须显式报出阻塞原因，不得静默跳过。
 - 阶段状态流转仅允许 `PENDING → IN_PROGRESS → DONE/FAILED/BLOCKED`。
 - 任一阶段退出条件未满足，`current_phase` 不得推进。
-- **P1_wiki 仅在项目有 baseline 时出现**；无 baseline 时该阶段不存在，不在 state 中写入，流程从 P2_raw 开始。
-- **P2_raw 退出前必须确认 `assets/raw/` 中存在用户放入的真实文档**，Agent 不得自行生成占位文件。
+- **S10_wiki 仅在项目有 baseline 时出现**；无 baseline 时该阶段不存在，不在 state 中写入，流程从 S20_collect_inputs 开始。
+- **S20_collect_inputs 退出前必须确认 `requirements/raw/` 中存在用户放入的真实文档**，Agent 不得自行生成占位文件。
+- **S20_collect_inputs 必须对 references/skills/rules 三项完成显式征询**（已提供 / 暂无新增 / 稍后补充）。
+- **S60_process_references 阶段中，references 必须先转换为 Markdown 并完成结构化索引确认**。
+- **S61_confirm_baseline_extraction 阶段中，必须显式确认是否启用 baseline 自动提取 skills/rules，禁止默认启用**。
+- **S65_customize_agent_env 阶段中，任何写入冲突必须先给建议，再经用户确认后写入**。
 - **任何涉及流程变更或内容修改的操作必须经用户表单确认**（见 `harness-build-rule-user-interaction`）。
 - **所有面向用户的输出必须使用中文**（见 `harness-build-rule-chinese-only`）。

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

@@ -1,6 +1,6 @@
 # harness-build-rule-skills-tasks-output — skills 与 tasks 产出规范
 
-本规则约束 P6_skills_tasks 阶段产出物的结构与命名。`harness-build-skill-knowledge-builder` 与人工协作时必须遵守。
+本规则约束 S70_runtime_assets 阶段产出物的结构与命名。`harness-build-skill-knowledge-builder` 与人工协作时必须遵守（S60/S61/S65 职责不在本规则覆盖范围）。
 
 ## skills 产出
 
@@ -12,7 +12,7 @@ agent-env/skills/
 
 - 每个 skill **必须**独占一个子目录，主文件**固定命名** `SKILL.md`（大写，不得用 `skill.md` 或 `<name>.md`）。
 - `SKILL.md` 顶部 yaml frontmatter 必备字段：`name`、`description`。description 中需含中英触发关键词。
-- skill 名使用 `kebab-case`，前缀体现领域（如 `dsv-signal-codegen`、`harness-build-skill-orchestrator`）。
+- skill 名使用 `kebab-case`。运行期 skill 建议使用 `harness-apply-<topic>` 前缀，避免与构建期 `harness-build-*` 混淆。
 
 ## tasks 产出
 
@@ -33,3 +33,4 @@ tasks/templates/
 - skill 与 task 文档中不得硬编码任何具体 agent 的私有指令格式（见 harness-build-rule-agent-agnostic.md）。
 - skill 描述中不得出现"本 agent""本工具"一类自指代，必须写明能力本身。
 - 产出物必须可被任意符合 SKILL.md 规范的 agent 消费。
+- 不得将构建期 skill（`harness-build-*`）误写入运行期 `agent-env/skills/`。

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

@@ -18,12 +18,12 @@ specs/
 
 - 写入任一 `specs/<domain>/*.yaml` 前，必须先读 `specs/<domain>/schema.json`。
 - 字段增减/重命名时，`schema.json` 与对应 yaml 必须**同一提交**更新，不得分两步。
-- yaml 中不得出现任何具体 agent 名（qoder/codechat/cursor/claude-code 等）— 违反 agent-agnostic 铁律。
+- yaml 中不得出现任何具体 agent 名（qoder/codechat/cursor/claude-code/opencode 等）— 违反 agent-agnostic 铁律。
 
 ## 校验节点
 
-- P3_specs 退出前：所有 yaml 逐一过 schema 校验，失败则阶段状态置 FAILED。
-- 后续阶段读取 specs 时不做 schema 校验（已由 P3 把关），但仍不得修改已冻结字段。
+- S50_generate_specs 退出前：所有 yaml 逐一过 schema 校验，失败则阶段状态置 FAILED。
+- 后续阶段读取 specs 时不做 schema 校验（已由 S50 把关），但仍不得修改已冻结字段。
 
 ## 正反例