svharness 0.11.0 → 0.13.2

package/dist/utils/validate-args.js

@@ -7,9 +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',
@@ -25,7 +28,6 @@ const SUPPORTED_AGENTS = [
     '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.
@@ -57,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) {
@@ -117,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,
@@ -138,54 +147,79 @@ 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
- *  - --harness defaults to the --output path (or current directory)
- *  - --output defaults to `.` (current directory)
+ *  - --output defaults to `.` (current directory); see `resolveConvertPaths` for layout
  *
  * When --harness is explicitly given, it must exist and contain harness.yaml.
- * When inferred from --output, we skip the harness.yaml requirement so users
- * can run `svharness convert` without ceremony.
  */
 function validateConvertArgs(input) {
     const errors = [];
-    // resolve output base (defaults to cwd)
-    const outputRaw = input.output ?? '.';
-    const outputAbs = node_path_1.default.resolve(outputRaw);
     // input: default to ['.']
     const patterns = (input.input ?? ['.']).map((s) => s.trim()).filter(Boolean);
-    // harness: explicit > output path
-    let harnessAbs;
     const harnessExplicit = !!input.harness;
     if (harnessExplicit) {
-        harnessAbs = node_path_1.default.resolve(input.harness);
+        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 (!fs_extra_1.default.existsSync(node_path_1.default.join(harnessAbs, 'harness.yaml'))) {
+        else if (!input.allowMissingHarnessYaml && !isHarnessRoot(harnessAbs)) {
             errors.push(`--harness "${harnessAbs}" does not look like a harness root (missing harness.yaml)`);
         }
     }
-    else {
-        // fallback to output path
-        harnessAbs = outputAbs;
-        // skip harness.yaml validation when inferred — just warn if missing
-        if (fs_extra_1.default.existsSync(harnessAbs) && fs_extra_1.default.statSync(harnessAbs).isDirectory()) {
-            if (!fs_extra_1.default.existsSync(node_path_1.default.join(harnessAbs, 'harness.yaml'))) {
-                // warn-only (harmless: outDir just gets created)
-            }
-        }
-        else {
-            // if output path doesn't exist yet, that's fine — we'll create it
-        }
-    }
     // endpoint: flag > env > default
     let endpoint = (input.endpoint && input.endpoint.trim()) ||
         (process.env[ENV_ENDPOINT] && process.env[ENV_ENDPOINT].trim()) ||
@@ -211,9 +245,16 @@ function validateConvertArgs(input) {
     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,
-        harness: harnessAbs,
+        outputDir: paths.outputDir,
+        harnessRoot: paths.harnessRoot,
+        harnessMode: paths.harnessMode,
         endpoint,
         concurrency,
         maxFileMB,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "svharness",
-  "version": "0.11.0",
+  "version": "0.13.2",
   "description": "CLI scaffolder for SDD-Driven Agent-Agnostic Coding Framework (harness)",
   "bin": {
     "svharness": "./bin/cli.js",

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

@@ -1,122 +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>/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 由 `svharness 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` —— 绑定时间与工具版本
-  - `apply_skill_registry` —— 由 S60 登记的**内容引用**清单（`name` / `reference_md` /
-    `description`，可选 `entry` / `source_id`）；`svharness apply` 将其内联到本 skill，
-    运行期**仅通过本清单 + `references/md/` 原文**路由与执行，不向目标项目注入
-    `harness-apply-skills-*` 子目录
-- （旁置，不读）`./references/binding.yaml` —— 冗余副本，仅供 `svharness`
-  自身工具链（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` 指向的目录不存在，
-   停止并提示用户重新运行 `svharness 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. **扫描子能力清单**（按优先级合并路由表）：
-   - **优先**使用绑定元数据中的 `apply_skill_registry`（见下文「References 能力」）；
-   - 再枚举 `<harness_root>/agent-env/skills/*/SKILL.md`（模板 skill、baseline 合并
-     skill；**不含** `harness-apply-skills-*` 前缀——references 已由 registry 承载），
-     提取 `name` + `description`；
-   - 合并去重后得到本次会话可用的 **子 skill 路由表**。不要整目录朗读内容，按需要再深读。
-
-4. **语义路由**：
-   - 若任务匹配 `apply_skill_registry` 中某项，按「References 能力 → 执行」处理，
-     **直接读** `<harness_root>/<reference_md>`，勿再查找同名子 skill 目录；
-   - 否则在路由表中选择最匹配的 1 ~ N 个 agent-env 子 skill；
-   - 若无匹配，回到普通实现路径，但仍必须遵守步骤 2 的规则。
-
-5. **查阅基线与规格**（按需）：
-   - `<harness_root>/baseline/wiki/` —— 项目知识摘要，优先用于建立上下文
-   - `<harness_root>/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 是知识源，演进由 `svharness` 和 harness 内部的 maintainer skill 负责。
-- **不得把 harness 的 always_on rules 当成"建议"**；它们是硬约束。
-- **不得引用 `baseline/code/` 之外的源码**作为"参考实现"。
-- **不得把本 skill 当作业务 skill**：它只做上下文装载 + 路由，业务实现由子 skill 或
-  agent 本体完成。
-- 所有面向用户的说明使用**中文**；字段名、类名、路径保留英文。
-- 多个子 skill 有冲突结论时，显式告知用户并请其裁决，不得自行二选一。
-
-## 典型触发例
-
-- "应用 harness-apply-skills-main 完成无线充电开关功能开发"
-- "基于 harness 新增设置项 Fragment"
-- "按 harness 规范实现新信号 CMDID 0xA3"
-- "apply harness 给我做一个埋点上报"
-
-以上触发均需先走算法 1~5，再进入业务实现。
-
-## References 能力（`apply_skill_registry`）
-
-`apply_skill_registry` 是 S60 为**内容引用**登记的清单，由 `svharness apply` 内联到
-本 skill 绑定元数据。运行期以清单 + `<harness_root>/references/md/` 为准，**不依赖**
-目标项目或 harness 内是否存在 `harness-apply-skills-*` 子 skill 目录。
-
-### 路由
-
-1. 将用户任务与 `apply_skill_registry[].description`、`name` 做语义匹配。
-2. 选出 0 ~ 1 条（必要时可多条）登记项；无匹配时回退到 agent-env 子 skill 扫描。
-
-### 执行（匹配到登记项后）
-
-1. 从绑定元数据取 `harness_root`、`target_project`。
-2. 阅读 `<harness_root>/<reference_md>` 中与本次任务相关的章节；有 `source_id` 时可
-   对照 `<harness_root>/references/yaml/index.yaml`。**禁止**跳过原文臆造流程。
-3. 遵守 `<harness_root>/agent-env/rules/` 中 `always_on` 规则。
-4. 若登记项含 `entry`（如 `/agent analyst`），按 references 原文执行该入口。
-5. 在 `target_project` 下交付；与 `<harness_root>/specs/` 冲突时先请用户裁决。
-6. 不得修改 harness 目录内任何文件；不得把本路径当作构建期 skill（`harness-build-*`）。
-
-## 绑定元数据（权威来源，由 svharness apply 生成，请勿手工编辑）
-
-{{BINDING_YAML_BLOCK}}
+- 本 skill 不负责二级调度与 binding 解析。
+- 如发现路径不一致，请重新执行 `svharness apply --force`。

package/templates/svharness.config.example.yaml

@@ -31,9 +31,10 @@ apply:
   clone: false
   yes: true
 
+# convert：output 无 harness.yaml 时写入该目录；有 harness.yaml 时写入 <output>/<type>/md/
 convert:
   input:
     - ./docs/*.pdf
-  output: .
+  output: ./my-app-harness
   type: requirements
   yes: true