coding-agent-harness 1.0.1 → 1.0.2

package/docs-release/guides/agent-installation.md

@@ -1,5 +1,7 @@
 # Agent 安装指南
 
+English mirror: `docs-release/guides/agent-installation.en-US.md`
+
 这份指南写给在目标项目里执行安装或升级的 coding agent。README 只保留给人看的定位、
 快速开始和最小命令；安装细则放在这里和 `SKILL.md`。
 
@@ -9,15 +11,35 @@
 研究命令参数、模板目录或 capability 选择；这些决策必须在 Diagnose / Decide 阶段完成，
 并在交付 summary 中说明依据。
 
+本文命令默认写成已安装的 `harness`。Agent 开始前先检查 `command -v harness`。
+如果目标环境没有 `harness` 命令，不得静默全局安装；先询问用户是否允许运行
+`npm install -g coding-agent-harness`。只有用户明确同意后才能修改全局 npm 环境。
+用户不同意或未回复时，用 `npx --yes coding-agent-harness <command>` 运行同一条 CLI。
+维护者在本源码仓调试时，可以把同一命令替换为 `node scripts/harness.mjs`。
+
+`harness init` 不会把 npm 包写进目标项目依赖；它只写 Harness 文档、模板和 registry。
+因此 agent 交付时不能暗示目标项目已经安装了 npm dependency。`npx` 第一次运行会把包
+下载到 npm 缓存；这不是项目依赖，也不是全局命令安装。需要 CLI 时继续用
+`npx --yes coding-agent-harness ...`、用户批准后的全局 `harness`，或源码仓的
+`node scripts/harness.mjs`。
+
+`npx skills add FairladyZ625/coding-agent-harness --skill coding-agent-harness`
+不是零写入操作。它会把 Skill 拷贝到目标项目的 `.agents/skills/coding-agent-harness/`
+并写入 `skills-lock.json`。如果用户要求严格只读扫描，先跳过 Skill 安装，用
+`npx --yes coding-agent-harness status` / `migrate-plan` 完成扫描；等用户确认允许写入后
+再安装 Skill 或运行初始化/迁移写入命令。
+
 使用 v1.0 六阶段流程：
 
-1. Diagnose：扫描项目结构、语言、现有文档、CI、协作方式和风险面。
-2. Decide：确定 locale、delivery model 和 capability packs。
+1. Diagnose：扫描项目结构、语言、现有文档、CI、协作方式、外部依赖和风险面。
+2. Decide：确定 locale、delivery model、capability packs，以及是否需要外部资料摄取。
 3. Scaffold：运行 `harness init` 或 `harness add-capability`。
 4. Configure：把生成文档改成项目事实；不要把模板假装成已定制标准。
 5. Verify：运行 CLI 检查和项目原生证据。
 6. Deliver：输出 residual、owner 和下一步。
 
+如果 Diagnose 阶段发现项目属于微服务、多仓、前后端分仓、平台子系统，或代码里有外部服务、SDK、API gateway、message queue、webhook、contract、schema、mock，Agent 必须询问用户是否有外部资料。资料少时作为 `Source Evidence` 链接；资料多时按 `docs/11-REFERENCE/external-source-intake-standard.md` 建立 `docs/04-DEVELOPMENT/external-source-packs/<source-key>/`，再把稳定结论投影到 `03/04/06`。
+
 ## 语言规则
 
 - 用户在场时，先问 harness 文档使用中文还是英文。
@@ -32,7 +54,17 @@
 目标项目没有旧 harness 时使用这条路径：
 
 ```bash
-node scripts/harness.mjs init \
+harness init \
+  --locale zh-CN \
+  --capabilities core,dashboard \
+  /path/to/project
+```
+
+如果目标环境没有 `harness` 命令，先询问用户是否允许全局安装；同意后运行
+`npm install -g coding-agent-harness`。未获同意时使用：
+
+```bash
+npx --yes coding-agent-harness init \
   --locale zh-CN \
   --capabilities core,dashboard \
   /path/to/project
@@ -43,7 +75,7 @@ Capability 要保守选择：
 | Capability | 默认 | 何时选择 |
 | --- | --- | --- |
 | `core` | 是 | 永远安装。这是 document kernel。 |
-| `dashboard` | 否 | 用户或 agent 需要本地只读状态页。 |
+| `dashboard` | 否 | 用户或 agent 需要本地状态页、静态证据快照，或本机动态 workbench。 |
 | `safe-adoption` | 否 | 旧 harness 项目接入 v1.0，需要保留历史文档。 |
 | `adversarial-review` | 否 | 发布、架构、安全、数据或策略风险需要独立 review artifact。 |
 | `long-running-task` | 否 | Agent 需要连续多轮执行，不能每步都询问用户。 |
@@ -55,11 +87,33 @@ Capability 要保守选择：
 - locale
 - selected capabilities，以及每个可选 capability 的选择理由
 - created / skipped files
+- nextCommands 中推荐的 `harness dev` 或 `npx --yes coding-agent-harness dev .` 日常入口
 - Configure 阶段做了哪些项目化改动
 - verification commands 和结果
 - residual owner / action / status
 - 是否提交；如果只是 dogfood 测试，是否已清理测试产物
 
+`init` 默认不会修改 `package.json`。只有用户明确希望目标项目保留 npm script 时，才使用
+`--add-npm-scripts`；该选项要求目标项目已经存在 `package.json`，并且不会覆盖已有
+`harness:dev` 或 `harness:dashboard` script。
+
+## 外部资料摄取
+
+当项目依赖外部微服务、外部仓库或外部团队文档时，Agent 不应该把外部资料直接塞进 `03-ARCHITECTURE`、`04-DEVELOPMENT` 或 `06-INTEGRATIONS`。正确顺序是：
+
+```text
+Inventory -> Classify -> Sanitize -> Digest -> Project -> Verify -> Residual
+```
+
+处理规则：
+
+- 询问用户是否有外部架构文档、接口文档、流程图、会议纪要、链接或导出包。
+- 确认资料是否能复制进仓；不能入仓的只保留路径、URL、owner、访问条件和 digest。
+- 外部资料超过 5 份、跨多个主题或会持续增长时，创建 `docs/04-DEVELOPMENT/external-source-packs/<source-key>/`。
+- `external-source-packs/` 只保存资料索引、digest 和投影状态。
+- 稳定事实必须回写到 `03-ARCHITECTURE/services/<service-key>.md`、`04-DEVELOPMENT/external-context/<service-key>.md` 或 `06-INTEGRATIONS/<contract>.md`。
+- 未确认或冲突的内容只能留在 source pack 或 `Do Not Assume`。
+
 ## 用户级注册
 
 如果用户已经通过 npm 或源码拿到了 `harness` CLI，可以把本 Skill 注册到用户级
@@ -90,50 +144,93 @@ harness doctor-user --agent codex
 
 ## 旧 Harness 迁移
 
-目标项目已经有旧版 harness 时使用这条路径。不要把旧文档重建一遍：
+目标项目已经有旧版 harness 时使用这条路径。不要把旧文档重建一遍，也不要从
+`add-capability` 手工拼流程；先用迁移轨道生成可验证 session：
 
 ```bash
-node scripts/harness.mjs add-capability safe-adoption \
+harness migrate-run \
   --locale zh-CN \
+  --session-dir /tmp/cah-migration-project \
+  --out-dir /tmp/cah-migration-project/dashboard \
   /path/to/old-project
+
+harness migrate-verify \
+  /tmp/cah-migration-project/session.json
+
+harness new-task \
+  --budget complex \
+  --preset legacy-migration \
+  --from-session /tmp/cah-migration-project/session.json
 ```
 
 规则：
 
 - 不覆盖已有 `AGENTS.md`、`CLAUDE.md`、`docs/Harness-Ledger.md`、SSoT、
   walkthrough、task progress 和历史 task plan。
+- 旧项目中英文混杂时，必须显式传 `--locale zh-CN` 或 `--locale en-US`。
 - 只补齐缺失的 v1.0 模板和 capability registry。
 - 已有项目事实只能 merge、append 或记录 residual；不能用泛化模板替换。
 - 历史合同缺口在普通模式下进入 `adoption-needed` warning。
 - `--strict` 必须仍然能因为旧 checker 失败或历史合同缺口而失败。
+- `migrate-verify` 必须通过，才能报告迁移输出可用；dashboard 路径必须是 HTML。
+- `new-task --preset legacy-migration --from-session` 只创建 Complex Task 骨架和证据包；不会继续迁移、改写历史、stage 或 commit。
+- 详细迁移策略见 `docs-release/guides/migration-playbook.md` 或英文镜像
+  `docs-release/guides/migration-playbook.en-US.md`。如果用户要求证明旧项目已经完整迁移，
+  还必须读取 `docs-release/guides/full-legacy-migration-subagent-strategy.md` 或中文镜像
+  `docs-release/guides/full-legacy-migration-subagent-strategy.zh-CN.md`。Agent 应读取
+  `session.json` 和 `migrate-plan.json`，再逐步迁移活跃任务、当前 review、真实采用的 capability，
+  并用 subagent 审查证明 dashboard brief 覆盖、strict check 和 final session 全部通过。
 
-## 验证命令
+## 任务生命周期
 
-安装或升级收口前，至少运行：
+初始化或迁移完成后，agent 不应手工复制任务目录。使用生命周期命令创建和推进任务：
 
 ```bash
-node scripts/harness.mjs check --profile target-project /path/to/project
-node scripts/harness.mjs status --json /path/to/project
-node scripts/harness.mjs dashboard --out /tmp/harness-dashboard.html /path/to/project
-```
+harness new-task phase-2-lifecycle \
+  --title "阶段二任务生命周期" \
+  --locale zh-CN \
+  /path/to/project
 
-开发本仓 v1.0 kernel 时，release gate 是：
+harness task-start phase-2-lifecycle \
+  --message "开始实现生命周期切片" \
+  /path/to/project
 
-```bash
-npm test
-npm run smoke:dashboard
-node scripts/harness.mjs check --profile source-package .
-node scripts/harness.mjs check --profile private-harness .harness-private
-node scripts/harness.mjs check --profile target-project examples/minimal-project
+harness task-log phase-2-lifecycle \
+  --message "完成 CLI 与模板更新" \
+  --evidence "command:TARGET:npm-test:passed" \
+  /path/to/project
+
+harness review-confirm TASKS/phase-2-lifecycle \
+  --reviewer "Human Reviewer" \
+  --confirm phase-2-lifecycle \
+  /path/to/project
+
+harness task-complete phase-2-lifecycle \
+  --message "验证闭环完成" \
+  /path/to/project
 ```
 
-## 必跑回归路径
+规则：
 
-任何 v1.0 kernel 改动都必须覆盖两条路径：
+- `new-task` 创建 `brief.md`、`task_plan.md`、`execution_strategy.md`、
+  `visual_map.md`、`findings.md`、`progress.md` 和 `review.md`。
+- 已存在的任务目录不会被覆盖；需要改名或继续旧任务时，由 coordinator 决定。
+- `task-start`、`task-block`、`task-complete` 只更新 `progress.md` 的生命周期状态和日志。
+- `task-log` 只追加执行记录；证据使用 `type:PATH:summary`，例如
+  `command:TARGET:npm-test:passed`。
+- `review-confirm` 会向 `review.md` 追加人工审查确认，并向 `progress.md` 追加日志；如果存在 `Open: yes` 或 `Blocks Release: yes` 的开放 P0/P1/P2 finding，必须拒绝确认。
+- `status --json` 保留旧 `task.state` 用于兼容，并新增 `lifecycleState`、`reviewStatus`、`closeoutStatus` 和 `stateConflicts`。`done` 只表示实现完成，不等于 `closed`。
+- 人工操作入口使用本地 HTML workbench：`harness dev /path/to/project`。它会启动只绑定 `127.0.0.1` 的动态页面、自动选择端口、打开浏览器并随 docs 变更刷新。无 GUI 或 CI 场景使用 `harness dev --no-open /path/to/project`。
+- 底层兼容入口仍是 `harness dashboard --workbench --out-dir /tmp/harness-workbench /path/to/project`。静态 dashboard 文件仍然只读，不能承载人工确认动作。
+- `task-list --json` 和 `status --json` 是 dashboard、reviewer 和后续 agent 的读取入口。
 
-| 路径 | 必须证明 |
-| --- | --- |
-| 新项目初始化 | 空项目 `init --locale zh-CN\|en-US --capabilities core,...` 后，模板语言一致、registry 正确、`status --json` 不误报 `safe-adoption`。 |
-| 旧 harness 迁移 | 旧项目 `add-capability safe-adoption --locale ...` 后，旧文件不被覆盖，缺失 v1.0 模板被补齐，普通模式 warning，strict 模式能阻塞历史缺口。 |
+## 验证命令
+
+安装或升级收口前，至少运行：
 
-真实项目 dogfood 默认清理测试产物，除非用户明确要求保留并提交。
+```bash
+harness check --profile target-project /path/to/project
+harness status --json /path/to/project
+harness dev --no-open --out-dir /tmp/harness-workbench /path/to/project
+harness dashboard --out /tmp/harness-dashboard.html /path/to/project
+```

package/docs-release/guides/document-audience-and-surfaces.en-US.md

@@ -0,0 +1,112 @@
+# Document Audiences And Surfaces
+
+Chinese mirror: `docs-release/guides/document-audience-and-surfaces.md`
+
+Coding Agent Harness documentation is not one uniform pile of Markdown. It serves three audiences:
+
+- Humans who need to understand the product, architecture, migration path, and project state.
+- Agents that need executable entrypoints, rules, task contracts, and evidence paths.
+- Release systems that need to know which files can ship publicly and which files are only local operating state.
+
+If these audiences are mixed, the documentation becomes unclear. Humans cannot find the decision, and agents cannot tell which file is authoritative.
+
+## Principle
+
+Human-facing docs explain intent and judgment.
+
+Agent-facing docs define facts, paths, gates, and next actions.
+
+Release docs explain public methodology and product capability. They do not carry a team's private operating ledger.
+
+## Documentation Surfaces
+
+| Surface | Primary reader | Contains | Does not contain |
+| --- | --- | --- | --- |
+| `README.md` | Humans | What the project is, how to start, key links | Long-running task state, private ledgers |
+| `docs-release/` | Humans and evaluators | Public architecture, guides, patterns, migration tutorials | Private task plans, internal reviews, customer-specific operating state |
+| `references/` | Agents and maintainers | Reusable standards such as testing, workflow, review, worktree rules | A project's current schedule |
+| `templates/` | CLI and agents | Files generated into target projects | Evidence from completed work |
+| Target `AGENTS.md` | Agents | Entrypoint, routing, hard rules, reading matrix | Long background essays |
+| Target `docs/09-PLANNING/` | Agents and project owners | Feature SSoT, task plans, current state | Generic marketing material |
+| Target `docs/05-TEST-QA/` | Agents, QA, human reviewers | Regression SSoT, Cadence Ledger, quality gates | Requirement brainstorm drafts |
+| Target `docs/10-WALKTHROUGH/` | Reviewers and handoff agents | Closeout evidence, residuals, human confirmation | Unverified plans |
+
+## Human-Facing Docs
+
+Human-facing docs answer:
+
+- What problem does this method solve?
+- Which repository operating model should I choose?
+- What are the risks when migrating an old project?
+- What evidence should make me trust that the agent stayed on track?
+
+Typical files:
+
+- `docs-release/architecture/overview.md`
+- `docs-release/guides/repository-operating-models.en-US.md`
+- `docs-release/guides/parent-control-repository-pattern.en-US.md`
+- `docs-release/guides/migration-playbook.en-US.md`
+
+Human-facing docs may explain tradeoffs, examples, and decisions, but they should not be the only source of truth. Live project state belongs in SSoTs, task files, reviews, walkthroughs, and regression files.
+
+## Agent-Facing Docs
+
+Agent-facing docs answer:
+
+- Where do I start reading?
+- Which files are authoritative?
+- Which paths may I edit?
+- Which checks must I run after editing?
+- When must I stop and ask a human?
+
+Typical files:
+
+- `AGENTS.md`
+- `docs/09-PLANNING/Feature-SSoT.md`
+- `docs/09-PLANNING/TASKS/<task>/task_plan.md`
+- `docs/09-PLANNING/TASKS/<task>/progress.md`
+- `docs/05-TEST-QA/Regression-SSoT.md`
+- `docs/10-WALKTHROUGH/<date>-<task>.md`
+- `docs/11-REFERENCE/*.md`
+
+Agent-facing docs should be concrete, path-oriented, and checkable. Do not turn them into essays, and do not make agents infer execution contracts from narrative prose.
+
+## Release Docs
+
+Release docs explain the public capability of Coding Agent Harness. They should not record the maintainers' private development process.
+
+Good release docs include:
+
+- Architecture overviews.
+- Installation and migration guides.
+- Single-repo, multi-repo, and parent-control operating model guidance.
+- Public migration prompts for agents.
+- Reusable engineering methodology.
+
+Do not publish:
+
+- In-progress conclusions from private tasks.
+- Private review drafts.
+- Machine-local paths that only work for one maintainer.
+- Customer or team internal state.
+- Ledgers, handoffs, or walkthroughs that have not been sanitized for release.
+
+## Writing Rules
+
+1. Identify the reader before choosing the file.
+2. Human docs explain why; agent docs define how.
+3. Public docs may describe patterns and structures, but not private operating state.
+4. Task state belongs in SSoTs, task files, reviews, walkthroughs, and ledgers.
+5. If one document tries to be both a human explanation and an agent execution contract, split it into a public guide and an execution contract.
+
+## A Useful Test
+
+Before writing a document, ask:
+
+> Who reads this file, at what moment, and what action should they take after reading it?
+
+If the answer is "a human uses it to understand," put it in a public guide or architecture doc.
+
+If the answer is "an agent uses it to execute," put it in the target project's entrypoint, task, standard, or regression files.
+
+If the answer is "a maintainer records how this source repository is being operated," it is not a public release document.

package/docs-release/guides/document-audience-and-surfaces.md

@@ -0,0 +1,112 @@
+# 文档受众与表面边界
+
+English mirror: `docs-release/guides/document-audience-and-surfaces.en-US.md`
+
+Coding Agent Harness 的文档不是一类东西。它同时服务三种读者：
+
+- 人：需要理解产品、架构、迁移方式和项目状态。
+- Agent：需要可执行的入口、规则、任务合同和证据路径。
+- 发布系统：需要知道哪些文件可以进入公开包，哪些文件只是本地运行状态。
+
+如果不区分受众，文档会变成一堆 Markdown。人看不出重点，Agent 也不知道应该信哪一份。
+
+## 总原则
+
+人读的文档解释意图和判断。
+
+Agent 读的文档定义事实、路径、门禁和下一步动作。
+
+发布文档说明方法论和产品能力，不携带某个团队的私有运行台账。
+
+## 文档表面
+
+| 表面 | 主要读者 | 放什么 | 不放什么 |
+| --- | --- | --- | --- |
+| `README.md` | 人 | 项目是什么、如何开始、关键链接 | 长任务状态、私有 ledger |
+| `docs-release/` | 人和评估者 | 公开架构、指南、模式说明、迁移教程 | 私有任务计划、内部 review、客户现场状态 |
+| `references/` | Agent 和维护者 | 可复用标准，例如 testing、workflow、review、worktree | 某个项目的当前排期 |
+| `templates/` | CLI 和 Agent | 初始化目标项目时生成的文件 | 已经执行过的任务证据 |
+| 目标项目 `AGENTS.md` | Agent | 入口、路由、硬规则、读文件矩阵 | 大段背景叙事 |
+| 目标项目 `docs/09-PLANNING/` | Agent 和项目负责人 | Feature SSoT、任务计划、当前状态 | 通用营销材料 |
+| 目标项目 `docs/05-TEST-QA/` | Agent、QA、人审 | Regression SSoT、Cadence Ledger、质量门禁 | 需求讨论草稿 |
+| 目标项目 `docs/10-WALKTHROUGH/` | 人审、接手 Agent | 收口证据、残留项、人工确认 | 未验证的计划 |
+
+## 人读文档
+
+人读文档要回答：
+
+- 这套方法解决什么问题？
+- 我应该选择哪种仓库组织方式？
+- 迁移旧项目时风险在哪里？
+- 什么证据能让我相信 Agent 没有跑偏？
+
+典型文件：
+
+- `docs-release/architecture/overview.zh-CN.md`
+- `docs-release/guides/repository-operating-models.md`
+- `docs-release/guides/parent-control-repository-pattern.md`
+- `docs-release/guides/migration-playbook.md`
+
+人读文档可以讲取舍、例子和判断过程，但不能成为唯一事实源。真正的项目状态必须落到 SSoT、task、review、walkthrough 和 regression 文件里。
+
+## Agent 读文档
+
+Agent 读文档要回答：
+
+- 我从哪里开始读？
+- 哪些文件是事实源？
+- 我可以改哪些路径？
+- 改完要跑哪些检查？
+- 什么条件下必须停下来问人？
+
+典型文件：
+
+- `AGENTS.md`
+- `docs/09-PLANNING/Feature-SSoT.md`
+- `docs/09-PLANNING/TASKS/<task>/task_plan.md`
+- `docs/09-PLANNING/TASKS/<task>/progress.md`
+- `docs/05-TEST-QA/Regression-SSoT.md`
+- `docs/10-WALKTHROUGH/<date>-<task>.md`
+- `docs/11-REFERENCE/*.md`
+
+Agent 文档应该具体、短路径、可检查。不要把它写成文章，也不要让 Agent 从长篇叙事里猜执行合同。
+
+## 发布文档
+
+发布文档要解释 Coding Agent Harness 的公开能力，而不是记录维护者自己的开发过程。
+
+可以发布：
+
+- 架构总览。
+- 安装和迁移指南。
+- 单仓、多仓、主控仓库模式的选择指南。
+- 给 Agent 使用的公开迁移 prompt。
+- 可复用的工程方法论。
+
+不应发布：
+
+- 某个私有任务的进行中结论。
+- 私有 review 草稿。
+- 只对某台机器有效的路径。
+- 客户或团队内部状态。
+- 还没有脱敏的 ledger、handoff、walkthrough。
+
+## 写作规则
+
+1. 先判断读者，再写文件。
+2. 人读文档负责解释为什么；Agent 文档负责定义怎么做。
+3. 公开文档可以引用模式和结构，不要引用私有运行状态。
+4. 任务状态只写在 SSoT、task、review、walkthrough 和 ledger 里。
+5. 如果一个文档既要给人读又要给 Agent 执行，把它拆成两份：公开说明和执行合同。
+
+## 一个判断问题
+
+写文档前问一句：
+
+> 这个文件被谁在什么时刻读取，并且读取后要做什么动作？
+
+如果答案是“人用来理解”，放在公开指南或架构文档里。
+
+如果答案是“Agent 用来执行”，放在目标项目的入口、任务、标准或回归文件里。
+
+如果答案是“维护者记录当前仓库如何运转”，它不是公开发布文档。