@cyning/harness 0.3.1 → 0.3.2

package/CHANGELOG.md

@@ -4,6 +4,22 @@
 
 ## [Unreleased]
 
+## [0.3.2] - 2026-06-15
+
+### Added
+
+- **Starter 40-self-check 帽**：[`harness/prompts/40-self-check.md`](harness/prompts/40-self-check.md) · Starter 闭包 **10/22/30/40**
+- **`task.harness.v1.json` schema**：[`schema/task.harness.v1.schema.json`](schema/task.harness.v1.schema.json)
+- **CLI `task check`**：`harness task check --file PATH [--no-circular] [--registry DIR]` · depends_on 环检测
+- **gate-check manifest 版本**：输出 `manifest.version` / preset · 与产品包版本不一致时提示 upgrade
+- **金样 sidecar**：[`examples/demo_checkout/task_demo_p0_golden_v1.harness.json`](examples/demo_checkout/task_demo_p0_golden_v1.harness.json)
+- **测试**：`test/task.check.test.js` · `npm test` 扩展
+
+### Changed
+
+- `harness/prompts/README.md`：标注 Starter 四帽闭包
+- 维护者本地验证：`npm run harness -- task check --file …`
+
 ## [0.3.1] - 2026-06-15
 
 ### Fixed

package/README.md

@@ -31,7 +31,7 @@
 ## Quick Start（npx · v0.3+）
 
 ```bash
-# 新业务仓根
+# 新业务仓根（须在目标业务仓执行，勿在本产品仓根目录跑 npx）
 npx @cyning/harness@latest init --preset harness-only --ide cursor,agents
 
 # 日常升级
@@ -39,6 +39,14 @@ npx @cyning/harness upgrade
 npx @cyning/harness check
 ```
 
+**维护者 · 在本仓库根验证 CLI**（npm 不会为「当前包」链接 `bin`，`npx` 会报 `harness: command not found`）：
+
+```bash
+npm run harness -- check --target /tmp/foo
+# 或
+node bin/harness.js check --target /tmp/foo
+```
+
 **维护者 / 离线（clone 路径）：**
 
 ```bash

package/docs/ONBOARDING.md

@@ -10,7 +10,7 @@
 
 ## 2. 安装（v0.3+ · npx 优先）
 
-**推荐 · 新业务仓根目录：**
+**推荐 · 目标业务仓根目录**（不要在 **cyning-harness 产品仓根** 跑 `npx @cyning/harness`，否则会 `harness: command not found`；维护者用 `npm run harness -- …` 或 `node bin/harness.js`）：
 
 ```bash
 npx @cyning/harness@latest init --preset harness-only --ide cursor,agents

package/docs/methodology/ROADMAP_v1_zh.md

@@ -39,7 +39,7 @@
 | --- | --- | --- | --- |
 | **v0.2.x** | **P0 闭环** | harness-only · sync plan/apply · gate-check · 金样 10→22→30 | methodology/ 归集 · P0 gap |
 | **v0.3.0** | **A1 分发** | manifest · npx init/upgrade/check · S5 git-clean · **✅ 2026-06-15**（Release/npm 留维护者） | FailureReport 模板 · rejected→draft gate-check |
-| **v0.3.x** | **A2 Starter** | 40-self-check 帽 · `task.harness.v1.json` · depends_on 禁环 CLI | ONBOARDING npx 优先 |
+| **v0.3.x** | **A2 Starter** | 40-self-check 帽 · `task.harness.v1.json` · depends_on 禁环 CLI · **✅ 2026-06-15** | ONBOARDING npx 优先 |
 | **v0.4.0** | **A3 + push** | ontology.yaml · D7 HG-RELEASE · demo_checkout 脱敏 · MIT public | ETCLOVG 映射页 · README 叙事 |
 | **v1.0.0** | **A4 stable** | ICVO audit CLI · invoke_index · gate-check --graph（Inform） | CHANGELOG 冻结 · B2 量化进 README |
 
@@ -58,7 +58,7 @@
 
 | 轨 | STRATEGY 名 | 本路线重点 | 当前 |
 | --- | --- | --- | --- |
-| **A** | 产品包 | §2 表 · v0.2→v1.0 | **A1 done** · A2 next |
+| **A** | 产品包 | §2 表 · v0.2→v1.0 | **A2 40 绿** · A3 / B next |
 | **B** | kimi-code-meta 试点 | oss-fork-meta / kimi-code-meta preset · 上游 PR 证据 · **#8 B2+micro-bench（1+3 主链）** · **#9 Agent-shell（2 并行）** | B0 · 证据方案待审 |
 | **C** | Runtime | harness ctx · Worker · **HGM 不替代 C** | 后置 |
 | **D** | 对外叙事 | ICVO · §7.5 对比 · 理论文章（见 prompts/） | 待 P0 绿 |
@@ -100,8 +100,8 @@ Epic 与子 task 真值：`Projects/docs/harness/tasks/active/`
 | [`TASK_epic_cyning_harness_roadmap_v0_2_to_v1_v1.md`](../../../../docs/harness/tasks/active/TASK_epic_cyning_harness_roadmap_v0_2_to_v1_v1.md) | 全文 |
 | #1 P0 golden close | v0.2.x · **done** 2026-06-15 |
 | #2 A1 npx | v0.3.0 · **done** 2026-06-15 |
-| #3 A2 Starter | v0.3.x · **next** |
-| #4 B kimi dogfood | Track B |
+| #3 A2 Starter | v0.3.x · **done 2026-06-15** |
+| #4 B kimi dogfood | Track B · **next** |
 | #5 D 续篇 | Track D · 篇 1 已 draft |
 | #6 A3 public push | v0.4.0 |
 | #7 A4 v1.0 | v1.0.0 · 引用 #8 |

package/examples/demo_checkout/task_demo_p0_golden_v1.harness.json

@@ -0,0 +1,12 @@
+{
+  "schema_version": "1",
+  "task_slug": "demo_p0_golden",
+  "test_strategy": "not_applicable",
+  "test_strategy_note": "金样仅验证 SDD 链与 gate-check · 无产品代码测试",
+  "depends_on": [],
+  "parallel_group": null,
+  "git_branch": "task/demo-p0-golden",
+  "worktree_root": "examples/demo_checkout/_sandbox",
+  "status": "draft",
+  "task_markdown": "examples/demo_checkout/task_demo_p0_golden_v1.md"
+}

package/harness/prompts/40-self-check.md

@@ -0,0 +1,48 @@
+# 帽子：自检（执行者）（Harness · Starter 子集）
+
+> **完整版 POINTER**（Ink 工作区）：`docs/harness/prompts/40-self-check.md`  
+> **本文件**：嵌入用户仓 `docs/harness/prompts/` 的 **精简真值** · A2 Starter 闭包 **10/22/30/40**。
+
+## 身份
+
+**执行者自检**：与 30 执行帽 **可同上下文连续**；把「声称完成」变成 **可核对证据**。
+
+## 只做什么
+
+- **逐条**对照 task **验收标准**，标记 pass / fail  
+- **必须**运行 task 所列 **验证命令**（与子仓 CI 对齐者优先），摘要 **退出码与关键输出**  
+- fail 时定位：命令、文件路径、错误摘要、是否可重试  
+- **必须**回填 task 正文 **`### 自检结论（执行者）`**（命令列表、退出码、验收表摘要、已知未测项）
+
+## 禁止什么
+
+- 不凭记忆声称「测过」；无命令输出则 **不勾选** 验收项  
+- 不把 **50 独立复检** 的深度走查塞满本帽（本帽以 **命令与验收表** 为主）  
+- **禁止**改 `docs/tasks/` · `reviews/` · `invokes/by-task/`（S2）
+
+## 输入假设
+
+- 当前分支 **diff**、task 全文、本地可运行环境（或说明 CI 替代）  
+- 可选 sidecar：`<task>.harness.json` · 用 `harness task check` 校验
+
+## 输出形状
+
+- **验收表**（勾选 + 证据摘录）  
+- **命令块**：所跑命令、工作目录、退出码
+
+## 停止条件
+
+- task 列出的验证命令已跑完，或已记录 **阻塞** 并停止勾选未验证项
+
+## 交接物
+
+- 给 50 复检 / 00 统筹：**diff + 日志摘要 + 自检验收表**  
+- task 内 **`### 自检结论（执行者）`** 相对路径引用
+
+---
+
+## 修订记录
+
+| 日期 | 摘要 |
+|------|------|
+| 2026-06-15 | A2 Starter 初版 · 与 Ink 完整库 POINTER 对齐 |

package/harness/prompts/README.md

@@ -9,8 +9,11 @@
 | [`10-requirements.md`](./10-requirements.md) | ✅ | 需求 / 任务分析 · 精简 + POINTER |
 | [`22-task-audit.md`](./22-task-audit.md) | ✅ | 任务审核 · 落盘 reviews · HG-AUDIT-R1 |
 | [`30-execute-code.md`](./30-execute-code.md) | ✅ v0.1.1 | 执行编码 · 强制闸扫描 · AUDIT approved |
+| [`40-self-check.md`](./40-self-check.md) | ✅ v0.3.2 | 自检 · 命令证据 · 回填 task |
 | [`TEMPLATE_30_gate_stop.md`](./TEMPLATE_30_gate_stop.md) | ✅ v0.1.1 | 30 拒开工输出模板 |
 
+**Starter 闭包**：10 / 22 / 30 / **40**（A2 · v0.3.x）
+
 ## 完整库（POINTER · 不复制全文）
 
 Ink 工作区维护完整帽子链：`docs/harness/prompts/`（00/20/40/50、TEMPLATE-*-invoke、PROMPT_*_chain_*）。

package/lib/cli.js

@@ -6,6 +6,7 @@ import {
   wizardScript,
 } from './paths.js';
 import { runBash } from './run.js';
+import { checkTaskFile } from './task.js';
 
 function usage() {
   console.log(`@cyning/harness · cyning-harness CLI (v0.3+)
@@ -14,11 +15,13 @@ function usage() {
   npx @cyning/harness init [--preset NAME] [--ide LIST] [--target PATH] [--yes]
   npx @cyning/harness upgrade [--target PATH] [--ide LIST] [--yes] [--force] [--gate-check]
   npx @cyning/harness check [--target PATH]
+  npx @cyning/harness task check --file PATH [--no-circular] [--registry DIR]...
 
 说明:
-  init     首次接入 · 内部调用 wizard/install.sh + harness-sync.sh apply
-  upgrade  升级已接入仓 · 等价 wizard/upgrade.sh --yes
-  check    读 manifest.json · 对比当前包版本是否有可升级版本
+  init        首次接入 · 内部调用 wizard/install.sh + harness-sync.sh apply
+  upgrade     升级已接入仓 · 等价 wizard/upgrade.sh --yes
+  check       读 manifest.json · 对比当前包版本是否有可升级版本
+  task check  校验 task.harness.v1.json sidecar · --no-circular 检测 depends_on 环
 
 环境:
   CYNING_HARNESS   覆盖产品包根（维护者本地 clone 开发）
@@ -59,6 +62,10 @@ export async function runCli(argv) {
     await cmdCheck(rest, harnessRoot, pkgVersion);
     return;
   }
+  if (cmd === 'task') {
+    await cmdTask(rest);
+    return;
+  }
 
   const err = new Error(`未知命令: ${cmd}\n`);
   err.exitCode = 1;
@@ -178,3 +185,70 @@ async function cmdCheck(args, harnessRoot, pkgVersion) {
     console.log('状态: 已是最新（或版本不可 semver 比较且相同）');
   }
 }
+
+async function cmdTask(args) {
+  const [sub, ...rest] = args;
+  if (sub !== 'check') {
+    const err = new Error(`task 子命令未知: ${sub ?? '(空)'}\n用法: task check --file PATH [--no-circular] [--registry DIR]...`);
+    err.exitCode = 1;
+    throw err;
+  }
+
+  const noCircular = rest.includes('--no-circular');
+  let filePath;
+  const registryDirs = [];
+  const filtered = [];
+
+  for (let i = 0; i < rest.length; i += 1) {
+    const arg = rest[i];
+    if (arg === '--no-circular') continue;
+    if (arg === '--file') {
+      filePath = rest[i + 1];
+      i += 1;
+      continue;
+    }
+    if (arg === '--registry') {
+      registryDirs.push(rest[i + 1]);
+      i += 1;
+      continue;
+    }
+    filtered.push(arg);
+  }
+
+  if (filtered.length > 0) {
+    const err = new Error(`task check 未知参数: ${filtered.join(' ')}`);
+    err.exitCode = 1;
+    throw err;
+  }
+  if (!filePath) {
+    const err = new Error('task check 须指定 --file PATH');
+    err.exitCode = 1;
+    throw err;
+  }
+
+  const result = checkTaskFile(filePath, { noCircular, registryDirs });
+  console.log(`文件: ${result.file}`);
+  console.log(`task_slug: ${result.task_slug}`);
+
+  if (!result.validation.ok) {
+    console.log('schema: FAIL');
+    for (const msg of result.validation.errors) {
+      console.log(`  - ${msg}`);
+    }
+    const err = new Error('task sidecar 校验失败');
+    err.exitCode = 1;
+    throw err;
+  }
+
+  console.log('schema: OK');
+
+  if (noCircular) {
+    if (!result.cycle.ok) {
+      console.log(`depends_on: CYCLE ${result.cycle.cycle.join(' → ')}`);
+      const err = new Error('depends_on 存在环');
+      err.exitCode = 1;
+      throw err;
+    }
+    console.log('depends_on: acyclic');
+  }
+}

package/lib/task.js

@@ -0,0 +1,205 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+const SLUG_RE = /^[a-z0-9][a-z0-9_-]*$/;
+
+/**
+ * 读取并解析 task sidecar JSON。
+ */
+export function loadTaskSidecar(filePath) {
+  const raw = fs.readFileSync(filePath, 'utf8');
+  let data;
+  try {
+    data = JSON.parse(raw);
+  } catch (err) {
+    const e = new Error(`JSON 解析失败: ${filePath}: ${err.message}`);
+    e.exitCode = 1;
+    throw e;
+  }
+  return data;
+}
+
+/**
+ * 轻量校验 task.harness.v1（无外部 JSON Schema 依赖）。
+ */
+export function validateTaskSidecar(data, fileLabel = 'task') {
+  const errors = [];
+
+  if (data == null || typeof data !== 'object' || Array.isArray(data)) {
+    return { ok: false, errors: [`${fileLabel}: 根节点须为 object`] };
+  }
+
+  const allowed = new Set([
+    'schema_version',
+    'task_slug',
+    'test_strategy',
+    'test_strategy_note',
+    'depends_on',
+    'parallel_group',
+    'git_branch',
+    'worktree_root',
+    'epic_slug',
+    'status',
+    'task_markdown',
+  ]);
+
+  for (const key of Object.keys(data)) {
+    if (!allowed.has(key)) {
+      errors.push(`${fileLabel}: 未知字段 "${key}"`);
+    }
+  }
+
+  if (data.schema_version !== '1') {
+    errors.push(`${fileLabel}: schema_version 须为 "1"`);
+  }
+
+  if (typeof data.task_slug !== 'string' || !SLUG_RE.test(data.task_slug)) {
+    errors.push(`${fileLabel}: task_slug 无效（小写 slug）`);
+  }
+
+  const strategies = ['required', 'recommended', 'not_applicable'];
+  if (!strategies.includes(data.test_strategy)) {
+    errors.push(`${fileLabel}: test_strategy 须为 ${strategies.join(' | ')}`);
+  }
+
+  if (data.test_strategy === 'not_applicable') {
+    if (typeof data.test_strategy_note !== 'string' || !data.test_strategy_note.trim()) {
+      errors.push(`${fileLabel}: test_strategy=not_applicable 须填 test_strategy_note`);
+    }
+  }
+
+  if (data.depends_on !== undefined) {
+    if (!Array.isArray(data.depends_on)) {
+      errors.push(`${fileLabel}: depends_on 须为 array`);
+    } else {
+      const seen = new Set();
+      for (const dep of data.depends_on) {
+        if (typeof dep !== 'string' || !SLUG_RE.test(dep)) {
+          errors.push(`${fileLabel}: depends_on 项无效 "${dep}"`);
+        }
+        if (dep === data.task_slug) {
+          errors.push(`${fileLabel}: depends_on 不可自引用 "${dep}"`);
+        }
+        if (seen.has(dep)) {
+          errors.push(`${fileLabel}: depends_on 重复 "${dep}"`);
+        }
+        seen.add(dep);
+      }
+    }
+  }
+
+  if (data.status !== undefined) {
+    const statuses = ['draft', 'pending', 'in_progress', 'done'];
+    if (!statuses.includes(data.status)) {
+      errors.push(`${fileLabel}: status 无效`);
+    }
+  }
+
+  return { ok: errors.length === 0, errors };
+}
+
+/**
+ * 扫描目录下所有 *.harness.json（一层 + 递归可选）。
+ */
+export function collectTaskSidecars(dirs, { recursive = true } = {}) {
+  const map = new Map();
+
+  function scanDir(dir) {
+    if (!fs.existsSync(dir)) return;
+    const entries = fs.readdirSync(dir, { withFileTypes: true });
+    for (const ent of entries) {
+      const full = path.join(dir, ent.name);
+      if (ent.isDirectory() && recursive) {
+        scanDir(full);
+      } else if (ent.isFile() && ent.name.endsWith('.harness.json')) {
+        const data = loadTaskSidecar(full);
+        const label = path.relative(process.cwd(), full) || full;
+        map.set(data.task_slug, {
+          filePath: full,
+          label,
+          data,
+        });
+      }
+    }
+  }
+
+  for (const dir of dirs) {
+    scanDir(path.resolve(dir));
+  }
+  return map;
+}
+
+/**
+ * depends_on 有向图环检测（DFS）。
+ */
+export function detectDependsOnCycle(taskMap) {
+  const visiting = new Set();
+  const visited = new Set();
+  let cyclePath = null;
+
+  function dfs(slug, stack) {
+    if (visited.has(slug)) return false;
+    if (visiting.has(slug)) {
+      const idx = stack.indexOf(slug);
+      cyclePath = stack.slice(idx).concat(slug);
+      return true;
+    }
+    visiting.add(slug);
+    stack.push(slug);
+    const entry = taskMap.get(slug);
+    const deps = entry?.data?.depends_on ?? [];
+    for (const dep of deps) {
+      if (dfs(dep, stack)) return true;
+    }
+    stack.pop();
+    visiting.delete(slug);
+    visited.add(slug);
+    return false;
+  }
+
+  for (const slug of taskMap.keys()) {
+    if (dfs(slug, [])) {
+      return { ok: false, cycle: cyclePath };
+    }
+  }
+  return { ok: true };
+}
+
+/**
+ * 校验单文件；可选合并 registry 目录做环检测。
+ */
+export function checkTaskFile(filePath, { noCircular = false, registryDirs = [] } = {}) {
+  const abs = path.resolve(filePath);
+  const data = loadTaskSidecar(abs);
+  const label = path.basename(abs);
+  const validation = validateTaskSidecar(data, label);
+  const result = {
+    file: abs,
+    task_slug: data.task_slug,
+    validation,
+    cycle: { ok: true },
+  };
+
+  if (!validation.ok) {
+    return result;
+  }
+
+  if (noCircular) {
+    const dirs = new Set([path.dirname(abs), ...registryDirs.map((d) => path.resolve(d))]);
+    const taskMap = collectTaskSidecars([...dirs]);
+    if (!taskMap.has(data.task_slug)) {
+      taskMap.set(data.task_slug, { filePath: abs, label, data });
+    }
+    for (const dep of data.depends_on ?? []) {
+      if (!taskMap.has(dep)) {
+        validation.errors.push(`${label}: depends_on 未找到 sidecar "${dep}"`);
+        validation.ok = false;
+      }
+    }
+    if (validation.ok) {
+      result.cycle = detectDependsOnCycle(taskMap);
+    }
+  }
+
+  return result;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cyning/harness",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "description": "cyning-harness discipline package · init / upgrade / check CLI",
   "license": "MIT",
   "type": "module",
@@ -29,7 +29,8 @@
     "AGENTS.md"
   ],
   "scripts": {
-    "test": "node --test test/*.test.js"
+    "test": "node --test test/*.test.js",
+    "harness": "node bin/harness.js"
   },
   "engines": {
     "node": ">=18"

package/schema/task.harness.v1.schema.json

@@ -0,0 +1,76 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://cyning.dev/schemas/cyning-harness/task.harness.v1.json",
+  "title": "cyning-harness Task Sidecar",
+  "description": "WorkItem 机器可读元数据 sidecar · 与 task_*.md 配对（本体 WorkItem · STRATEGY A2）",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema_version", "task_slug", "test_strategy"],
+  "properties": {
+    "schema_version": {
+      "type": "string",
+      "const": "1",
+      "description": "Sidecar schema 主版本"
+    },
+    "task_slug": {
+      "type": "string",
+      "pattern": "^[a-z0-9][a-z0-9_-]*$",
+      "description": "与 task 元信息 task_slug 一致"
+    },
+    "test_strategy": {
+      "type": "string",
+      "enum": ["required", "recommended", "not_applicable"],
+      "description": "Harness V2 test_strategy 字段"
+    },
+    "test_strategy_note": {
+      "type": "string",
+      "minLength": 1,
+      "description": "test_strategy=not_applicable 时必填"
+    },
+    "depends_on": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "pattern": "^[a-z0-9][a-z0-9-]*$"
+      },
+      "uniqueItems": true,
+      "default": [],
+      "description": "Epic 编排依赖 · 须无环（harness task check --no-circular）"
+    },
+    "parallel_group": {
+      "type": ["string", "null"],
+      "description": "Epic parallel_group · 无则 null 或省略"
+    },
+    "git_branch": {
+      "type": "string",
+      "description": "建议分支名 task/<slug>"
+    },
+    "worktree_root": {
+      "type": "string",
+      "description": "Open Folder / 验证 cwd"
+    },
+    "epic_slug": {
+      "type": "string",
+      "description": "所属 Epic slug"
+    },
+    "status": {
+      "type": "string",
+      "enum": ["draft", "pending", "in_progress", "done"]
+    },
+    "task_markdown": {
+      "type": "string",
+      "description": "配对 task Markdown 相对路径（可选 · 便于 CLI 定位）"
+    }
+  },
+  "allOf": [
+    {
+      "if": {
+        "properties": { "test_strategy": { "const": "not_applicable" } },
+        "required": ["test_strategy"]
+      },
+      "then": {
+        "required": ["test_strategy_note"]
+      }
+    }
+  ]
+}

package/wizard/gate-check.sh

@@ -84,6 +84,22 @@ check_one_task() {
 
 echo "=== Harness gate-check ==="
 echo "目标: $TARGET"
+
+MANIFEST_FILE="$TARGET/.cyning-harness/manifest.json"
+if [[ -f "$MANIFEST_FILE" ]]; then
+  mf_version="$(grep -o '"version"[[:space:]]*:[[:space:]]*"[^"]*"' "$MANIFEST_FILE" | head -1 | sed -E 's/.*"([^"]+)"$/\1/')"
+  mf_preset="$(grep -o '"preset"[[:space:]]*:[[:space:]]*"[^"]*"' "$MANIFEST_FILE" | head -1 | sed -E 's/.*"([^"]+)"$/\1/')"
+  echo "manifest.version: ${mf_version:-?}"
+  echo "manifest.preset: ${mf_preset:-?}"
+  if [[ -n "${CYNING_HARNESS:-}" && -f "$CYNING_HARNESS/package.json" ]]; then
+    pkg_version="$(grep '"version"' "$CYNING_HARNESS/package.json" | head -1 | sed -E 's/.*:[[:space:]]*"([^"]+)".*/\1/')"
+    if [[ -n "$pkg_version" && -n "$mf_version" && "$mf_version" != "$pkg_version" ]]; then
+      echo "提示: manifest 版本 ($mf_version) 与产品包 ($pkg_version) 不一致 · 可运行 upgrade"
+    fi
+  fi
+else
+  echo "manifest: (未接入 · 无 $MANIFEST_FILE)"
+fi
 echo ""
 
 BLOCKED=0