@cyning/harness 1.0.0 → 1.0.2

package/CHANGELOG.md

@@ -4,6 +4,35 @@
 
 ## [Unreleased]
 
+## [1.0.2] - 2026-06-16
+
+### Fixed
+
+- **`verify` 无 `--task`**：摘要不再误匹配闸表行 `❌ 拒 30`；多 task 阻塞时摘要列出 blocked task 名
+- **`verify` BLOCKED**：exit 2 时不再打印空 `Error` stack trace
+
+## [1.0.1] - 2026-06-16
+
+### Added
+
+- **业务仓 CLI 入口**：`npx @cyning/harness gate-check` · `verify` · `sync index`（读 `.cyning-harness/local.json`，无需 clone 产品包）
+- **`verify` 聚合命令**：30 前一条命令跑 gate-check + audit D5 + S5 warn + 可选 `--graph`
+- **`--help` / `--version` / `-V`**：全局与各子命令帮助
+- **Node 仓可选 `--with-scripts`**：`init|upgrade --with-scripts [--pm pnpm|npm|yarn|auto]` 写入 `devDependencies` 与 `scripts`（merge 不覆盖）
+- **业务仓 QUICKREF**：`harness/templates/QUICKREF_v1_zh.md`，install/upgrade 后写入 `.cyning-harness/QUICKREF.md`
+
+### Changed
+
+- `lib/audit.js` 使用统一 `resolveHarnessRootForTarget`，修复无 `CYNING_HARNESS` 时的路径 bug
+- `lib/cli.js` 子命令透传 `CYNING_HARNESS` 到 wizard 脚本
+- `README.md` · `docs/ONBOARDING.md` · `docs/USER_GUIDE_v1.0_zh.md` · `wizard/README.md` · IDE 片段：同步 v1.0.1 CLI 与 `verify` 用法
+- **`ontology.yaml`**：`product_semver: "1.0.1"`
+
+### Notes
+
+- **HG-RELEASE**（tag v1.0.1 · npm publish）仍留维护者人闸
+- `verify --graph` 硬挡规则与 `gate-check --graph` 一致
+
 ## [1.0.0] - 2026-06-16
 
 ### Added

package/README.md

@@ -2,7 +2,7 @@
 
 ```bash
 npx @cyning/harness@latest init --preset harness-only --ide cursor,agents
-npx @cyning/harness upgrade && npx @cyning/harness check
+npx @cyning/harness verify
 ```
 
 可 clone、可嵌入业务仓库的 **Harness 纪律包**（无业务代码，无内置 LLM）· **MIT 开源**。
@@ -33,9 +33,10 @@ npx @cyning/harness upgrade && npx @cyning/harness check
 
 ---
 
-## Quick Start（npx · v0.3+）
+## Quick Start（npx · v1.0）
 
-> 顶部三行即最小接入。须在 **目标业务仓根** 执行（勿在本产品仓根跑 `npx`，会报 `harness: command not found`）。
+> 顶部三行即最小接入。须在 **目标业务仓根** 执行（勿在本产品仓根跑 `npx`，会报 `harness: command not found`）。  
+> **陌生人完整手册**：[`docs/USER_GUIDE_v1.0_zh.md`](docs/USER_GUIDE_v1.0_zh.md)
 
 **维护者 · 在本仓库根验证 CLI**（npm 不会为「当前包」链接 `bin`，`npx` 会报 `harness: command not found`）：
 
@@ -64,33 +65,36 @@ git clone git@github.com:Cyning12/cyning-harness.git && cd cyning-harness
 ```text
 install / adopt  →  harness-sync plan/apply  →  @ task + prompts（10→22→30）
                       ↑ 产品包 git pull 后 upgrade.sh
-30 前：gate-check.sh  ·  HG-AUDIT-R1 = approved
+30 前：npx @cyning/harness verify  ·  HG-AUDIT-R1 = approved
 ```
 
 1. 阅读 [`docs/ONBOARDING.md`](docs/ONBOARDING.md)  
-2. [`wizard/install.sh`](wizard/install.sh) 或 [`adopt-existing.sh`](wizard/adopt-existing.sh)  
-3. 产品包更新：[`wizard/upgrade.sh`](wizard/upgrade.sh) 或 [`harness-sync.sh`](wizard/harness-sync.sh) `apply`  
-4. IDE `@` task + `docs/harness/prompts/`；30 前 [`gate-check.sh`](wizard/gate-check.sh)  
+2. [`npx @cyning/harness init`](docs/USER_GUIDE_v1.0_zh.md) 或 [`wizard/install.sh`](wizard/install.sh) / [`adopt-existing.sh`](wizard/adopt-existing.sh)  
+3. 产品包更新：`npx @cyning/harness upgrade` 或 [`wizard/upgrade.sh`](wizard/upgrade.sh) / [`harness-sync.sh`](wizard/harness-sync.sh) `apply`  
+4. IDE `@` task + `docs/harness/prompts/`；30 前 `npx @cyning/harness verify` 或 `npx @cyning/harness gate-check`  
 
 ---
 
 ## ICVO 机械审计（v1.0+）
 
-`harness audit` 在 30 执行前机械检查 ICVO 公理子集：
+`npx @cyning/harness verify` 在 30 执行前聚合检查 ICVO 公理子集：
 
 ```bash
+npx @cyning/harness verify --target /path/to/your-repo --task docs/tasks/active/task_xxx.md
+npx @cyning/harness gate-check --target /path/to/your-repo --task docs/tasks/active/task_xxx.md
 npx @cyning/harness audit --target /path/to/your-repo --task docs/tasks/active/task_xxx.md
 npx @cyning/harness upgrade --gate-check       # upgrade 前自动 audit
 ```
 
-- **D3**：`gate-check.sh` 真值唯一来源，HG-AUDIT-R1 / HG-GRAPH-MODULES pending 时拒 30  
+- **D3**：`gate-check` 真值唯一来源，HG-AUDIT-R1 / HG-GRAPH-MODULES pending 时拒 30  
 - **D5**：`test_strategy=required` 任务须声明测试路径或 CI 引用  
 - **S5**：dirty 工作区 warn，apply 须 `--force` 明示  
 
-Inform 图谱闸：`wizard/gate-check.sh --graph --target /path/to/your-repo`  
-Invoke 索引：`wizard/harness-sync.sh --index --target /path/to/your-repo`（不覆盖 S2 域）
+Inform 图谱闸：`npx @cyning/harness gate-check --graph --target /path/to/your-repo`  
+Invoke 索引：`npx @cyning/harness sync index --target /path/to/your-repo`（不覆盖 S2 域）
 
-详见 [`docs/ONBOARDING.md`](docs/ONBOARDING.md) §2.2。
+Node 仓可选：`npx @cyning/harness init --with-scripts` → `pnpm harness:verify`。  
+详见 [`docs/USER_GUIDE_v1.0_zh.md`](docs/USER_GUIDE_v1.0_zh.md) · [`docs/ONBOARDING.md`](docs/ONBOARDING.md) §2.2。
 
 ---
 
@@ -118,7 +122,7 @@ Invoke 索引：`wizard/harness-sync.sh --index --target /path/to/your-repo`（
 | --- | --- |
 | 覆盖 | S1–S4（D2 HumanGate · D3 gate-check · S2 sync 域） |
 | 结果 | **4/4 = 100%** |
-| 运行 | `./wizard/compliance-bench.sh --all` |
+| 运行 | [`./wizard/compliance-bench.sh --all`](../wizard/compliance-bench.sh) · 说明 [`examples/compliance_bench/README.md`](../examples/compliance_bench/README.md) |
 
 **免责声明**：本表为 **小样本机制证据**，非胜率承诺；Part A 与 Terminal-Bench / SWE-bench **互补、不对标**。
 
@@ -163,9 +167,9 @@ cyning-harness/
 
 | 项 | 值 |
 |----|-----|
-| 当前 | **v0.4.0** — A3 public push 准备 · ontology.yaml · MIT · 脱敏金样 |
-| 上一档 | v0.3.x — npx CLI · Starter 四帽 · manifest · S5 |
-| 许可 | **MIT** · [`LICENSE`](LICENSE) · 战略 POINTER 见 [`methodology/pointers/STRATEGY_ONTOLOGY_v1_zh.md`](docs/methodology/pointers/STRATEGY_ONTOLOGY_v1_zh.md) |
+| 当前 | **v1.0.0** — A4 stable · ICVO audit · invoke_index · gate-check --graph · B2 证据 |
+| 上一档 | v0.4.0 — A3 public push · MIT · 脱敏金样 |
+| 许可 | **MIT** · [`LICENSE`](LICENSE) · Release [`docs/RELEASE_v1.0.0.md`](docs/RELEASE_v1.0.0.md) |
 
 ---
 
@@ -175,7 +179,7 @@ cyning-harness/
 | --- | --- |
 | **总指引** | [`methodology/README.md`](docs/methodology/README.md) · [关系图](docs/methodology/DOCUMENT_MAP_v1_zh.md) · [路线 ROADMAP](docs/methodology/ROADMAP_v1_zh.md) |
 | **本体** | [DESIGN_ONTOLOGY v1.2](docs/methodology/product/DESIGN_ONTOLOGY_v1_zh.md) |
-| **落地** | [P0 差距](docs/methodology/execution/P0_V0.2_GAP.md) · [金样验收](examples/demo_checkout/ACCEPTANCE.md) · [ETCLOVG 映射](docs/ETCLOVG_MAPPING_v1_zh.md) |
+| **使用** | [**USER_GUIDE v1.0**](docs/USER_GUIDE_v1.0_zh.md) · [P0 差距](docs/methodology/execution/P0_V0.2_GAP.md) · [金样验收](examples/demo_checkout/ACCEPTANCE.md) · [ETCLOVG 映射](docs/ETCLOVG_MAPPING_v1_zh.md) |
 | **远期** | [HGM 草案](docs/methodology/graph/HARNESS_GRAPH_MODEL_design_v0_zh.md) |
 | **接入** | [ONBOARDING](docs/ONBOARDING.md) · [ARCHITECTURE](docs/ARCHITECTURE.md) |
 

package/bin/harness.js

@@ -2,6 +2,6 @@
 import { runCli } from '../lib/cli.js';
 
 runCli(process.argv.slice(2)).catch((err) => {
-  console.error(err.message || err);
+  if (err.message) console.error(err.message);
   process.exit(typeof err.exitCode === 'number' ? err.exitCode : 1);
 });

package/docs/ONBOARDING.md

@@ -42,28 +42,31 @@ cd your-project
 
 ## 2.2 ICVO 机械审计（v1.0+）
 
-`harness audit` 在 30 执行前扫描人工闸与测试声明，确保 ICVO 公理可机械检查：
+`npx @cyning/harness verify` 在 30 执行前聚合扫描人工闸与测试声明，确保 ICVO 公理可机械检查：
 
 ```bash
-# 扫描 active task 的 HG-AUDIT-R1 / HG-GRAPH-MODULES / HG-RELEASE
-npx @cyning/harness audit --target /path/to/your-repo
+# 30 前聚合验证（gate-check + audit D5 + S5 warn + 可选 --graph）
+npx @cyning/harness verify --target /path/to/your-repo
+npx @cyning/harness verify --target /path/to/your-repo \
+  --task docs/tasks/active/task_xxx.md
+
+# 仅人工闸
+npx @cyning/harness gate-check --target /path/to/your-repo
+npx @cyning/harness gate-check --graph --target /path/to/your-repo
 
-# 指定 task（D5 测试声明检查生效）
+# 指定 task 的 ICVO 审计
 npx @cyning/harness audit --target /path/to/your-repo \
   --task docs/tasks/active/task_xxx.md
 
-# 查看 Inform 图谱审核摘要
-/path/to/cyning-harness/wizard/gate-check.sh --graph --target /path/to/your-repo
-
 # 生成 invoke 索引（只读聚合，不覆盖 S2 域）
-/path/to/cyning-harness/wizard/harness-sync.sh --index --target /path/to/your-repo
+npx @cyning/harness sync index --target /path/to/your-repo
 ```
 
 | 公理 | 检查项 | 行为 |
 |------|--------|------|
-| **D3** | 30 前置人闸 | 复用 `gate-check.sh`，HG-AUDIT-R1 非 approved 时 audit 非 0 |
-| **D5** | 改码任务测试声明 | `test_strategy=required` 但无测试/CI 引用时 audit 非 0 |
-| **S5** | Git 工作区干净 | dirty 时 warn（不直接 fail audit，但 apply 须 `--force`） |
+| **D3** | 30 前置人闸 | 复用 `gate-check.sh`，HG-AUDIT-R1 非 approved 时 verify 非 0 |
+| **D5** | 改码任务测试声明 | `test_strategy=required` 但无测试/CI 引用时 verify 非 0 |
+| **S5** | Git 工作区干净 | dirty 时 warn（不直接 fail verify，但 apply 须 `--force`） |
 
 Audit **不替代** 维护者最终判断；Agent 首输出仍须人工复核。
 

package/docs/README.md

@@ -3,7 +3,7 @@
 | 项 | 内容 |
 | --- | --- |
 | **入口** | 本页 → **[方法论总指引](./methodology/README.md)** |
-| **接入** | [`ONBOARDING.md`](./ONBOARDING.md) · [`../wizard/README.md`](../wizard/README.md) |
+| **接入** | [**USER_GUIDE v1.0**](./USER_GUIDE_v1.0_zh.md) · [`ONBOARDING.md`](./ONBOARDING.md) · [`../wizard/README.md`](../wizard/README.md) |
 | **架构** | [`ARCHITECTURE.md`](./ARCHITECTURE.md) |
 
 ---
@@ -12,7 +12,7 @@
 
 | 读者 | 先读 |
 | --- | --- |
-| **新接入** | ONBOARDING → wizard/install → [`methodology/execution/P0_V0.2_GAP.md`](./methodology/execution/P0_V0.2_GAP.md) |
+| **新接入** | **USER_GUIDE v1.0** → ONBOARDING → [`methodology/execution/P0_V0.2_GAP.md`](./methodology/execution/P0_V0.2_GAP.md) |
 | **实现 / 扩展** | [`methodology/product/DESIGN_ONTOLOGY_v1_zh.md`](./methodology/product/DESIGN_ONTOLOGY_v1_zh.md) |
 | **战略 / 开源** | [`methodology/pointers/`](./methodology/pointers/README.md) → 工作区 STRATEGY_* |
 | **HGM 远期** | [`methodology/graph/`](./methodology/graph/README.md) |

package/docs/RELEASE_v1.0.0.md

@@ -84,6 +84,7 @@ npx @cyning/harness audit --target . --task docs/tasks/active/task_xxx.md
 
 ## 链接
 
+- **使用手册**：[`docs/USER_GUIDE_v1.0_zh.md`](./USER_GUIDE_v1.0_zh.md)
 - 文档索引：[`docs/README.md`](./README.md)
 - 接入：[`docs/ONBOARDING.md`](./ONBOARDING.md)
 - 路线：[`docs/methodology/ROADMAP_v1_zh.md`](./methodology/ROADMAP_v1_zh.md)

package/docs/RELEASE_v1.0.1.md

@@ -0,0 +1,87 @@
+# Release v1.0.1 · A5 CLI verify（A+C+D）
+
+> **包名**：`@cyning/harness@1.0.1`  
+> **许可**：MIT  
+> **日期**：2026-06-16  
+> **代号**：A5 · CLI verify patch（v1.0.0 → v1.0.1）
+
+---
+
+## 概要
+
+v1.0.0 已能 `npx init/upgrade/audit`，但业务仓若无 clone 路径或 `CYNING_HARNESS` 环境变量，Agent/维护者须手拼路径。v1.0.1 让 **任意业务仓直接跑** `npx @cyning/harness verify` / `gate-check` / `sync index`，通过 `.cyning-harness/local.json` 自动定位产品包根；并新增 Node 仓可选 `--with-scripts` 把 harness 命令写入 `package.json`。
+
+---
+
+## Quick Start
+
+在 **目标业务仓根**：
+
+```bash
+# 首次接入
+npx @cyning/harness@1.0.1 init --preset harness-only --ide cursor,agents --yes
+
+# 30 前验证	npx @cyning/harness verify --target . --task docs/tasks/active/task_xxx.md
+
+# 升级
+npx @cyning/harness@1.0.1 upgrade --target . --yes
+```
+
+Node 仓可选 scripts 路径：
+
+```bash
+npx @cyning/harness@1.0.1 upgrade --target . --yes --with-scripts --pm pnpm
+pnpm install
+pnpm harness:verify --task docs/tasks/active/task_xxx.md
+```
+
+---
+
+## 新增命令
+
+| 命令 | 用途 |
+| --- | --- |
+| `npx @cyning/harness gate-check` | 业务仓人工闸（透传 `wizard/gate-check.sh`） |
+| `npx @cyning/harness verify` | 30 前聚合：gate-check + audit D5 + S5 warn + 可选 `--graph` |
+| `npx @cyning/harness sync index` | 生成 `.cyning-harness/invoke_index.json` |
+| `npx @cyning/harness --version` / `-V` | 显示当前包版本 |
+
+## 新增 flag
+
+| flag | 命令 | 说明 |
+| --- | --- | --- |
+| `--with-scripts` | `init` · `upgrade` | 写入 `devDependencies['@cyning/harness']` 与三 scripts |
+| `--pm pnpm\|npm\|yarn\|auto` | `init` · `upgrade` | 仅用于提示与文档；scripts 值统一调用 `node_modules/.bin/harness` |
+
+---
+
+## 主要变更文件
+
+- `lib/paths.js`：`resolveHarnessRootForTarget`
+- `lib/audit.js`：使用统一根解析
+- `lib/verify.js`：新增
+- `lib/package-scripts.js`：新增
+- `lib/cli.js`：子命令路由 + help/version
+- `wizard/install.sh` · `wizard/upgrade.sh`：写 `QUICKREF.md`
+- `harness/templates/QUICKREF_v1_zh.md`：新增
+- `docs/USER_GUIDE_v1.0_zh.md` · `README.md` · `docs/ONBOARDING.md` · `wizard/README.md`
+- IDE 片段：AGENTS / CLAUDE / Cursor
+
+---
+
+## 非范围
+
+- `.cyning-harness/bin` stub 全套（方案 B）→ backlog
+- 改 compliance-bench S1–S4 语义
+- init 时自动 `pnpm install`
+- 自动写 shell alias（~/.zshrc）
+
+---
+
+## HG-RELEASE
+
+- [ ] git tag `v1.0.1`
+- [ ] npm publish `@cyning/harness@1.0.1`
+- [ ] 可选 GitHub Release v1.0.1
+
+由维护者执行。

package/docs/USER_GUIDE_v1.0_zh.md

@@ -0,0 +1,284 @@
+# cyning-harness v1.0 · 使用手册
+
+> **读者**：要在 **自己的业务仓库** 里落地 AI 辅助研发纪律的开发者（非 cyning-harness 维护者）。  
+> **版本**：[`@cyning/harness@1.0.1`](https://www.npmjs.com/package/@cyning/harness) · MIT  
+> **仓库**：<https://github.com/Cyning12/cyning-harness>  
+> **更短入口**：[`README.md`](../README.md) Quick Start · [`ONBOARDING.md`](./ONBOARDING.md) 接入细节  
+> **Release**：[`RELEASE_v1.0.1.md`](./RELEASE_v1.0.1.md) · [`CHANGELOG.md`](../CHANGELOG.md)
+
+---
+
+## 1. 这是什么 · 不是什么
+
+**cyning-harness** 是一套可嵌入任意 Git 仓库的 **SDD 过程纪律包**：
+
+- 提供：task 模板、审核 prompt、人工闸约定、同步脚本、CI 样例、架构图谱模板
+- **不提供**：业务代码、LLM API、Agent 编排 SDK（与 LangChain 等 **互补**）
+
+**v1.0 解决什么问题**：陌生人不仅能在空仓库 `npx init`，还能用 **`audit` / `gate-check` / `sync --index`** 机械检查「Inform / Constrain / Verify / Orchestrate（ICVO）」是否在仓库里就绪，而不是只靠口头约定。
+
+---
+
+## 2. 前置条件
+
+| 项 | 要求 |
+| --- | --- |
+| Git | 目标业务仓已是 Git 仓库（或 `git init` 后使用） |
+| Node.js | 能运行 `npx`（仅安装/升级 CLI 时需要） |
+| IDE | 推荐带 Agent 的编辑器（Cursor、Claude Code 等） |
+| 工程习惯 | 至少有 lint、test 或 build 之一（便于对齐 `ci/` 样例） |
+
+---
+
+## 3. 五分钟上手（推荐路径）
+
+在 **你的业务仓库根目录** 执行（**不要**在 clone 下来的 `cyning-harness` 产品仓根跑 `npx`，会报 `harness: command not found`）：
+
+```bash
+# 1. 首次安装（钉 preset 与 IDE 入口）
+npx @cyning/harness@1.0.1 init --preset harness-only --ide cursor,agents --yes
+
+# 2. 30 前验证（gate-check + audit D5 + S5 warn）
+npx @cyning/harness verify --target . --task docs/tasks/active/task_xxx.md
+
+# 3. 产品包升级时（拉取模板更新）
+npx @cyning/harness upgrade --yes
+```
+
+**安装后你会得到**（典型）：
+
+```text
+your-repo/
+├── .cyning-harness/
+│   ├── manifest.json      # 钉住的 harness 版本与 preset
+│   └── profile.json       # 同步轨道配置
+├── docs/
+│   ├── tasks/active/      # 你的 task 单（Agent 不覆盖）
+│   ├── tasks/done/        # 关账归档
+│   ├── harness/prompts/   # Starter 四帽 10/22/30/40
+│   ├── harness/invokes/   # 执行快照约定
+│   ├── _tech_graph/       # 架构图谱（按需填写）
+│   ├── coding_wiki/       # LLM 读序
+│   └── standards/         # 编码规范模板
+└── AGENTS.md 等 IDE 入口片段
+```
+
+---
+
+## 4. 典型 SDD 工作流（Starter 四帽）
+
+```text
+10 需求/任务分析  →  22 任务审核  →  gate-check  →  30 执行编码  →  40 自检  →  关账
+     ↑                    ↑              ↑
+  prompts/10        落盘 reviews/    HG-AUDIT-R1 = approved
+```
+
+### 4.1 新建一张 task
+
+1. 复制 [`docs/harness/templates/`](../harness/templates/) 或金样 [`task_demo_p0_golden_v1.md`](../examples/demo_checkout/task_demo_p0_golden_v1.md) 到 `docs/tasks/active/task_xxx.md`
+2. 填写：背景、范围、验收标准、`test_strategy`（`required` / `recommended` / `not_applicable`）
+3. 在 task 表填写 **人工闸**（至少 `HG-TASK-DRAFT`、`HG-AUDIT-R1`）
+
+### 4.2 在 IDE 里执行
+
+1. `@` 你的 task 文件 + `@docs/harness/prompts/10-requirements.md` → 产出需求/范围（帽说明见 [`harness/prompts/README.md`](../harness/prompts/README.md)）
+2. `@` [`22-task-audit.md`](../harness/prompts/22-task-audit.md) → 审核员落盘 `docs/harness/reviews/` · 维护者签 **`HG-AUDIT-R1 = approved`**
+3. **30 之前** 跑 gate-check（见 §5）
+4. `@` [`30-execute-code.md`](../harness/prompts/30-execute-code.md) → 改代码
+5. `@` [`40-self-check.md`](../harness/prompts/40-self-check.md) → 命令证据 · 回填 task
+6. 关账：`git mv` task → `docs/tasks/done/<domain>/`（见 [`ONBOARDING.md`](./ONBOARDING.md) §6 · [`FRAGMENT_task_domain_infer`](../harness/templates/FRAGMENT_task_domain_infer_v1_zh.md)）
+
+### 4.3 练手金样（零风险）
+
+不碰生产仓库时，在 `/tmp` 跑通一遍：
+
+```bash
+mkdir -p /tmp/harness-demo && cd /tmp/harness-demo && git init -q
+npx @cyning/harness@1.0.1 init --preset harness-only --ide cursor,agents --yes
+# 30 前验证：npx @cyning/harness verify --target . --task docs/tasks/active/task_demo_p0_golden_v1.md
+# 金样 task（二选一）：
+# · 已 clone 产品仓：cp /path/to/cyning-harness/examples/demo_checkout/task_demo_p0_golden_v1.md docs/tasks/active/
+# · 仅 npx：从 GitHub 浏览 examples/demo_checkout/ 复制 task 内容
+# 逐步验收：examples/demo_checkout/ACCEPTANCE.md（见下方链接）
+```
+
+分步勾选：[`examples/demo_checkout/README.md`](../examples/demo_checkout/README.md) · [`ACCEPTANCE.md`](../examples/demo_checkout/ACCEPTANCE.md) · 差距说明 [`P0_V0.2_GAP.md`](./methodology/execution/P0_V0.2_GAP.md)
+
+---
+
+## 5. 人工闸与 gate-check（30 前必做）
+
+**原则**：Agent 可以写 task 和 review，**人工闸只有维护者能签**。
+
+```bash
+# 30 前聚合验证（gate-check + audit D5 + S5 warn + 可选 --graph）
+npx @cyning/harness verify --target . --task docs/tasks/active/task_xxx.md
+
+# 仅人工闸
+npx @cyning/harness gate-check --target . --task docs/tasks/active/task_xxx.md
+npx @cyning/harness gate-check --graph --target .    # Inform 图谱闸
+
+# 等价底层脚本（离线 clone 产品仓路径 · 见 wizard/README）
+/path/to/cyning-harness/wizard/gate-check.sh --target .
+```
+
+脚本说明：[`wizard/README.md`](../wizard/README.md) · [`wizard/gate-check.sh`](../wizard/gate-check.sh)
+
+| 闸 ID | 含义 | 30 影响 |
+| --- | --- | --- |
+| `HG-AUDIT-R1` | 22 审核通过 | **非 approved → 拒 30** |
+| `HG-TASK-DRAFT` | task 初稿维护者签 | pending 且 blocks 含 30 → 拒 30 |
+| `HG-GRAPH-MODULES` | 架构模块表人签 | pending → 拒改码 30 |
+| `HG-RELEASE` | 发版闸（产品仓） | 一般业务仓不涉及 |
+
+**Inform 图谱闸（v1.0）**：改码类 task 前，确保 `docs/_tech_graph/` 模块表已维护者签 `HG-GRAPH-MODULES = approved`。存量大仓可按 [`ONBOARDING.md`](./ONBOARDING.md) §3 选 S0–S3 档位，**不必一次画完所有 Mermaid**。
+
+---
+
+## 6. v1.0 CLI 命令速查
+
+| 命令 | 用途 |
+| --- | --- |
+| `npx @cyning/harness init` | 首次安装模板与 manifest（可选 `--with-scripts`） |
+| `npx @cyning/harness upgrade` | 同步产品包更新（可加 `--gate-check` 先 audit） |
+| `npx @cyning/harness check` | 检查是否有新版本 |
+| `npx @cyning/harness verify` | 30 前聚合：gate-check + audit D5 + S5 warn + 可选 `--graph` |
+| `npx @cyning/harness gate-check` | 仅人工闸（`--graph` / `--json`） |
+| `npx @cyning/harness audit` | ICVO 机械审计（D3/D5/S5） |
+| `npx @cyning/harness sync index` | 生成 `.cyning-harness/invoke_index.json` |
+| [`harness-sync.sh`](../wizard/harness-sync.sh) `plan/apply` | 预览/应用模板同步 |
+
+**ICVO audit 检查什么**：
+
+| 公理 | 行为 |
+| --- | --- |
+| **D3** | 30 前人闸 · 同 gate-check |
+| **D5** | `test_strategy=required` 须有测试路径或 CI 引用 |
+| **S5** | 工作区 dirty 时 warn；`sync apply` 须 `--force` 明示 |
+
+Audit **不替代** 维护者判断；22 内容质量仍须人读 review。详见 [`ONBOARDING.md`](./ONBOARDING.md) §2.2。
+
+### 6.1 SDD-Compliance bench（维护者 · 可选）
+
+> **业务仓日常不必跑**；用于验证 `gate-check` / `sync` 公理行为，或对照 README「试点证据」中的 bench 数字。
+
+仅在 **clone 下来的 cyning-harness 产品仓根** 执行：
+
+```bash
+cd /path/to/cyning-harness
+./wizard/compliance-bench.sh --all          # 逐项解释 + 摘要（推荐人工看）
+./wizard/compliance-bench.sh --quiet --all  # stdout 仅合规率数字；说明在 stderr
+```
+
+| 输出 | 含义 |
+| --- | --- |
+| **`100`** | S1–S4 四个合成场景全 PASS · **不是** LLM 解题分数 |
+| **`< 100`** | 有场景 FAIL · 见 `--all` 输出或 stderr 摘要表 |
+
+场景与公理解读：[`examples/compliance_bench/README.md`](../examples/compliance_bench/README.md) · 脚本 [`wizard/compliance-bench.sh`](../wizard/compliance-bench.sh)
+
+---
+
+## 7. 同步边界（重要 · S2）
+
+`harness-sync` **不会覆盖** 你的业务数据：
+
+- `docs/tasks/**`
+- `docs/harness/reviews/**`
+- `docs/harness/invokes/by-task/**`（按 task 域的执行快照）
+
+纪律层（prompts 模板、wizard 脚本引用）与业务 task **分离**。升级产品包前建议：
+
+```bash
+git status          # 应干净，或知晓 S5 warn
+npx @cyning/harness upgrade --yes
+```
+
+---
+
+## 8. Preset 怎么选
+
+| preset | 适合 |
+| --- | --- |
+| **`harness-only`**（默认） | 任意栈 · 只要 SDD 过程轨 + IDE 入口 |
+| `fullstack-node-py` | Node 前端 + Python 后端全栈五轨 |
+| `oss-fork-meta` | 个人 OSS fork · 过程轨与 upstream 双分支（见 [`examples/oss-fork/README.md`](../examples/oss-fork/README.md)） |
+
+交互式问卷：`wizard/install.sh`（离线 clone 路径）。
+
+---
+
+## 9. 离线 / 无 npx 环境
+
+```bash
+git clone https://github.com/Cyning12/cyning-harness.git
+cd your-project
+/path/to/cyning-harness/wizard/install.sh --target . --preset harness-only --ide cursor,agents
+/path/to/cyning-harness/wizard/harness-sync.sh apply --target .
+```
+
+维护者在 **产品仓根** 验证 CLI：
+
+```bash
+npm run harness -- check --target /tmp/foo
+# 或 node bin/harness.js audit --target /path/to/your-repo
+```
+
+---
+
+## 10. 局限与诚实边界（v1.0）
+
+| 项 | 说明 |
+| --- | --- |
+| 不是胜率工具 | [`README` 试点证据 B2](../README.md) · 完整表 [`PILOT_EVIDENCE_B2_v1_zh.md`](./methodology/execution/PILOT_EVIDENCE_B2_v1_zh.md) · **小样本机制证据**，不可外推 |
+| bench `100` | [SDD-Compliance](../examples/compliance_bench/README.md) 四场景合规率 · 见上文 §6.1 |
+| Extended 帽 | 00/50/链式 PROMPT 不在 Starter 默认包 · 见 [`harness/prompts/README.md`](../harness/prompts/README.md) |
+| HGM / 图数据库 | **Track G · v2.0+ 提案**，v1.0 未实现 |
+| Agent-shell | 研究轨 #9，非 npm 功能 |
+| rejected→draft | bench S5 场景 v1 未纳入；gate-check 对非 approved 拒 30 |
+
+---
+
+## 11. 常见问题
+
+**Q：Harness 会调用我的 LLM 吗？**  
+A：不会。LLM 在你使用的 IDE 里；Harness 只提供文件、脚本与约定。
+
+**Q：必须用完 10→22→30→40 才能提交代码吗？**  
+A：团队自定。Starter 设计是 **改码前 22 审核 + gate-check**；小修可标 `test_strategy=not_applicable` 并写理由。
+
+**Q：和 `.cursor/rules` 什么关系？**  
+A：`init --ide cursor` 会生成入口片段；Harness task + prompts 是 **任务级 SDD**，rules 是 **编辑器级约束**，可同时用。
+
+**Q：升级后 task 会被覆盖吗？**  
+A：不会（S2 域）。若 prompts 模板有更新，apply 会更新 **模板侧**，不删你的 active task。
+
+**Q：如何贡献或报 issue？**  
+A：GitHub [Cyning12/cyning-harness](https://github.com/Cyning12/cyning-harness) · MIT。
+
+---
+
+## 12. 进一步阅读
+
+| 优先级 | 文档 |
+| --- | --- |
+| **本手册** | 你正在读 · 对外入口 [`docs/README.md`](./README.md) |
+| **接入** | [`ONBOARDING.md`](./ONBOARDING.md) · [`wizard/README.md`](../wizard/README.md) · [`wizard/ONBOARDING_wizard_v1_zh.md`](../wizard/ONBOARDING_wizard_v1_zh.md) |
+| **练手** | [`demo_checkout/README.md`](../examples/demo_checkout/README.md) · [`ACCEPTANCE.md`](../examples/demo_checkout/ACCEPTANCE.md) |
+| **合规 bench** | [`examples/compliance_bench/README.md`](../examples/compliance_bench/README.md) |
+| **理论** | [`methodology/README.md`](./methodology/README.md) · [`DESIGN_ONTOLOGY_v1_zh.md`](./methodology/product/DESIGN_ONTOLOGY_v1_zh.md) |
+| **路线** | [`methodology/ROADMAP_v1_zh.md`](./methodology/ROADMAP_v1_zh.md) |
+| **试点证据** | [`PILOT_EVIDENCE_B2_v1_zh.md`](./methodology/execution/PILOT_EVIDENCE_B2_v1_zh.md) |
+| **ETCLOVG** | [`ETCLOVG_MAPPING_v1_zh.md`](./ETCLOVG_MAPPING_v1_zh.md) |
+| **架构** | [`ARCHITECTURE.md`](./ARCHITECTURE.md) |
+| **变更** | [`CHANGELOG.md`](../CHANGELOG.md) · [`RELEASE_v1.0.0.md`](./RELEASE_v1.0.0.md) |
+
+---
+
+**修订记录**
+
+| 日期 | 说明 |
+| --- | --- |
+| 2026-06-16 | v1.0 stable 首版使用手册 |
+| 2026-06-16 | 补全相对链接 · §6.1 compliance-bench · §12 阅读索引 |
+| 2026-06-16 | v1.0.1：verify / gate-check / sync index CLI · `--with-scripts` · QUICKREF |

package/docs/methodology/ROADMAP_v1_zh.md

@@ -117,7 +117,9 @@ Epic 与子 task 真值：`Projects/docs/harness/tasks/active/`
 | #6 A3 public push | v0.4.0 |
 | #7 A4 v1.0 | v1.0.0 · 引用 #8 |
 | **#8 B2 + bench** | Track B · **1+3 主证据** · P0 绿后优先 |
-| **#9 Agent-shell** | Track B · **2 并行** · 核实期 · 不挡 A3 |
+| **#9 Agent-shell** | Track B · **后置** · HGM+agent 后 | deferred · 见 §8 |
+| **I-YAML** | Track A · v1.1+ Inform | [`task_y1`](../../../../docs/harness/tasks/active/task_cyning_harness_y1_yaml_inform_v19_v1.md) · YAML P0 后 |
+| **Track G G1** | HGM v2.0 | [`task_g1`](../../../../docs/harness/tasks/active/task_cyning_harness_g1_hgm_v2_v1.md) · I-YAML + G0 后 |
 
 **证据策略（2026-06-15 锁定）**：
 
@@ -134,6 +136,24 @@ Epic 与子 task 真值：`Projects/docs/harness/tasks/active/`
 
 ---
 
+## 8. Post-v1.0 执行序（2026-06-16）
+
+维护者决策真值：工作区 [`POST_V1_0_SEQUENCE_v1_zh.md`](../../../../docs/harness/guides/POST_V1_0_SEQUENCE_v1_zh.md) · HGM 讨论 [`HGM_UPGRADE_OUTLINE_v1_zh.md`](./graph/HGM_UPGRADE_OUTLINE_v1_zh.md)
+
+| 序 | 里程碑 | 阻塞 |
+| --- | --- | --- |
+| 0 | A5 @1.0.1 · Epic CLOSE · **v1.0 公众号本周发** | — |
+| 1 | Ink 后端 Graph YAML P0 CLOSE | — |
+| 2 | 产品 Inform-YAML **v1.1+**（2.0 前） | 1 |
+| 3 | HGM G0 大纲讨论 + schema 冻结 | 1 |
+| 4 | HGM G1 **v2.0** ingest | 2 + 3 |
+| 5 | cyning-harness-agent 基础 | 4 · 待立项 |
+| 6 | B9 Agent-shell findings | 5 |
+
+**原则**：Inform YAML 在 v2.0 前并入主轨 · HGM 在后端 YAML 试点后启动 · B9 最后。
+
+---
+
 ## 7. 修订记录
 
 | 版本 | 日期 | 说明 |
@@ -146,3 +166,4 @@ Epic 与子 task 真值：`Projects/docs/harness/tasks/active/`
 | v1.3.2 | 2026-06-15 | P0 金样关账 · v0.2→v0.3 首闸满足 · A1 next |
 | v1.3.3 | 2026-06-15 | A1 实现关账 · A2 next · v0.3.0 表标注 |
 | v1.4 | 2026-06-15 | **SEM-02**：HGM Track G **v0.5/v0.6 → v2.x** · 增 §2.0 命名纪律 |
+| v1.5 | 2026-06-16 | 增 §8 Post-v1.0 序 · I-YAML v1.1+ · B9 后置 · 链 HGM 大纲 |

package/docs/methodology/graph/HARNESS_GRAPH_MODEL_design_v0_zh.md

@@ -9,6 +9,7 @@
 | **范围**   | 过程轨 **实例** 的显式图 + 事件历史 + 公理可查询                                                                                                   |
 | **非范围**  | 替代 Git/Markdown 真值 · 替代 LLM Runtime · `**GraphTrack` 架构图**（见 §0.3）                                                               |
 | **依赖**   | [`../product/DESIGN_ONTOLOGY_v1_zh.md`](../product/DESIGN_ONTOLOGY_v1_zh.md) v1.2 · P0 金样路径已建（ACCEPTANCE 待绿）· v0.3 `ontology.yaml`（未实现）· v1.0 `gate-check --graph`（Inform · 未实现） |
+| **升级大纲** | [`HGM_UPGRADE_OUTLINE_v1_zh.md`](./HGM_UPGRADE_OUTLINE_v1_zh.md) · G0 讨论入口（2026-06-16） |
 | **思想来源** | [`HARNESS_GRAPH_MODEL_dialogue_archive_v1_zh.md`](./HARNESS_GRAPH_MODEL_dialogue_archive_v1_zh.md) |