coding-agent-harness 1.0.1 → 1.0.4

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,48 @@
 研究命令参数、模板目录或 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 或运行初始化/迁移写入命令。
+
+本仓库还发布嵌套的 `preset-creator` Skill，给需要制作可复用 Harness Preset 的 Agent
+使用。因为本仓库同时有根目录 `SKILL.md` 和嵌套 Skill，查看或安装它时要加
+`--full-depth`：
+
+```bash
+npx skills add FairladyZ625/coding-agent-harness --list --full-depth
+npx skills add FairladyZ625/coding-agent-harness --skill preset-creator --full-depth
+```
+
+`coding-agent-harness` 用于在目标项目中运行 Harness；`preset-creator` 只在 Agent
+需要为一类可重复任务设计 Preset 时使用，例如这些任务共享 Reference、Artifact、Evidence
+或 Complex Task 骨架叠加规则。
+
 使用 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 +67,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 +88,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 +100,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 注册到用户级
@@ -70,6 +137,16 @@ harness install-user --agent codex --global
 harness doctor-user --agent codex
 ```
 
+`npm install -g coding-agent-harness`、`harness install-user` 和 `harness init`
+都会 seed 内置 Preset：
+
+- 用户级 Preset：`~/.coding-agent-harness/presets/<preset-id>/`
+- 项目级 Preset：`<target>/.coding-agent-harness/presets/<preset-id>/`
+
+Agent 初始化或接手任务前必须运行 `harness preset list --json [target]`，
+确认可用 Preset 后再选择 `--preset`。如需修复缺失的内置 Preset，运行
+`harness preset seed` 或 `harness preset seed --project <target>`。
+
 支持的 agent target：
 
 | Agent | 用户级目录 |
@@ -86,54 +163,99 @@ harness doctor-user --agent codex
 - 默认交互确认；非交互场景必须传 `--yes` 或先用 `--dry-run`。
 - 默认不覆盖已有文件，只补缺失文件。
 - 需要强制更新时显式传 `--force`。
-- `doctor-user` 会检查 `SKILL.md`、模板、references、CLI scripts 和本指南是否存在。
+- `doctor-user` 会检查 `SKILL.md`、模板、references、内置 Preset、CLI scripts、本指南，以及用户级 Preset seed 是否存在。
 
 ## 旧 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
 ```
 
 规则：
 
 - 不覆盖已有 `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 失败或历史合同缺口而失败。
+- 旧全局表和模块索引先归档，再用 `harness governance rebuild --archive --apply` 重新生成；这些表是 Agent 索引，人看状态优先用 Dashboard。
+- `migrate-verify` 必须通过，才能报告迁移输出可用；dashboard 路径必须是 HTML。
+- 详细迁移策略见 `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 改动都必须覆盖两条路径：
+- 不要手工复制任务模板，也不要创建不完整任务目录。`harness check` 会按
+  `new-task` 创建的预算文件集校验。
+- `new-task --budget simple` 创建 `brief.md`、`task_plan.md`、`visual_map.md`
+  和 `progress.md`。
+- `new-task` 默认 `standard`，创建 simple 文件，并额外创建
+  `execution_strategy.md`、`findings.md`、`lesson_candidates.md` 和 `review.md`。
+- `new-task --budget complex` 创建 standard 文件，并额外创建
+  `references/INDEX.md` 和 `artifacts/INDEX.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，必须拒绝确认。
+- CLI-owned lifecycle 和 lesson 命令会在干净 Git root 中自动提交 allowlisted 写入；dirty 状态会出现在 `status` / dashboard 的警告里，并阻塞这些机械化提交。Agent 手工改动仍要主动提交，不能提交时记录 no-commit reason、owner 和下一步。
+- `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/contributing.md

@@ -0,0 +1,100 @@
+# Contributor Guide
+
+This guide is for external contributors working on the public Coding Agent Harness repository.
+
+## Working Model
+
+Coding Agent Harness is more than documentation. The public repository includes:
+
+- CLI implementation under `scripts/`
+- tests under `tests/`
+- installable templates under `templates/` and `templates-zh-CN/`
+- bundled presets under `presets/`
+- public documentation under `docs-release/`
+- examples under `examples/`
+- an optional GUI submodule under `harness-gui/`
+
+Keep pull requests focused on one change family when possible. Documentation, CLI behavior, target-project templates, presets, and GUI work have different verification paths.
+
+## Local Setup
+
+Use Node.js 18 or newer. CI runs Node.js 20.
+
+```bash
+npm install
+```
+
+If your change touches the GUI submodule:
+
+```bash
+cd harness-gui
+npm ci
+```
+
+## Required Checks
+
+Run the checks that match your change. For larger PRs or when you are unsure, run
+the full root suite.
+
+| Change type | Minimum local checks |
+| --- | --- |
+| Docs only | `git diff --check` |
+| CLI/runtime | `npm test`, `npm run check`, `git diff --check` |
+| Templates or examples | `npm test`, `node scripts/harness.mjs check --profile target-project examples/minimal-project`, `git diff --check` |
+| Dashboard | `npm test`, `npm run smoke:dashboard`, `git diff --check` |
+| Package surface | `npm test`, `npm run pack:dry-run`, `git diff --check` |
+| GUI submodule | `cd harness-gui && npm ci && npm run typecheck && npm test && npm run build` |
+
+Full root suite:
+
+```bash
+npm test
+npm run smoke:dashboard
+npm run check
+node scripts/harness.mjs check --profile target-project examples/minimal-project
+npm run pack:dry-run
+git diff --check
+```
+
+GUI submodule setup and checks:
+
+```bash
+cd harness-gui
+npm ci
+npm run typecheck
+npm test
+npm run build
+```
+
+If a check cannot be run locally, say why in the PR.
+
+## PR Requirements
+
+Use the repository PR template and fill in:
+
+- summary
+- what changed
+- version impact
+- verification evidence
+- review evidence
+- residual risk
+- related issue, task, or design reference when available
+
+For docs-only or CI-only changes, "no version change" is usually correct. Runtime, template, preset, or package-surface changes may need a version decision from a maintainer.
+
+## GUI Submodule Changes
+
+`harness-gui/` is a Git submodule. GUI changes should be committed in the GUI repository first, then the parent repository should update the submodule pointer. A parent PR that updates the pointer should link to the GUI PR and include the GUI verification output.
+
+## CI
+
+GitHub Actions runs the same broad gates contributors should run locally:
+
+- root package tests
+- source/package boundary check
+- minimal target project check
+- dashboard generation and smoke test
+- npm package dry run
+- GUI submodule typecheck, tests, and build
+
+Repository owners manage branch protection and required checks in GitHub. Contributors only need to keep their PRs focused, documented, and verified.

package/docs-release/guides/contributing.zh-CN.md

@@ -0,0 +1,99 @@
+# 贡献者指南
+
+这份指南面向参与公开 `coding-agent-harness` 仓库的外部贡献者。
+
+## 工作模型
+
+Coding Agent Harness 不只是文档仓库。公开仓库包含：
+
+- `scripts/` 下的 CLI 实现
+- `tests/` 下的测试
+- `templates/` 与 `templates-zh-CN/` 下的可安装模板
+- `presets/` 下的内置 preset
+- `docs-release/` 下的公开文档
+- `examples/` 下的示例项目
+- `harness-gui/` 下的可选 GUI 子模块
+
+PR 尽量聚焦在一类改动上。文档、CLI 行为、目标项目模板、preset 和 GUI 有不同的验证路径。
+
+## 本地准备
+
+使用 Node.js 18 或更高版本。CI 当前使用 Node.js 20。
+
+```bash
+npm install
+```
+
+如果改动涉及 GUI 子模块：
+
+```bash
+cd harness-gui
+npm ci
+```
+
+## 必要检查
+
+根据改动范围运行相关检查。较大的 PR 或不确定范围时，运行完整根仓检查。
+
+| 改动类型 | 最小本地检查 |
+| --- | --- |
+| 仅文档 | `git diff --check` |
+| CLI / runtime | `npm test`, `npm run check`, `git diff --check` |
+| 模板或示例 | `npm test`, `node scripts/harness.mjs check --profile target-project examples/minimal-project`, `git diff --check` |
+| Dashboard | `npm test`, `npm run smoke:dashboard`, `git diff --check` |
+| Package surface | `npm test`, `npm run pack:dry-run`, `git diff --check` |
+| GUI 子模块 | `cd harness-gui && npm ci && npm run typecheck && npm test && npm run build` |
+
+完整根仓检查：
+
+```bash
+npm test
+npm run smoke:dashboard
+npm run check
+node scripts/harness.mjs check --profile target-project examples/minimal-project
+npm run pack:dry-run
+git diff --check
+```
+
+GUI 子模块安装和检查：
+
+```bash
+cd harness-gui
+npm ci
+npm run typecheck
+npm test
+npm run build
+```
+
+如果某个检查无法在本地运行，请在 PR 中说明原因。
+
+## PR 要求
+
+使用仓库 PR 模板，并填写：
+
+- 摘要
+- 改动内容
+- 版本影响
+- 验证证据
+- 审查证据
+- 残余风险
+- 如有相关 issue、任务或设计材料，附上链接
+
+文档或 CI-only 改动通常可以写“不改版本”。运行时、模板、preset 或 package surface 改动可能需要维护者决定版本策略。
+
+## GUI 子模块改动
+
+`harness-gui/` 是 Git submodule。GUI 改动应先提交到 GUI 仓库，再由父仓更新 submodule pointer。更新 pointer 的父仓 PR 应链接 GUI PR，并附上 GUI 验证结果。
+
+## CI
+
+GitHub Actions 会运行贡献者本地也应覆盖的主要 gate：
+
+- 根包测试
+- source/package boundary 检查
+- minimal target project 检查
+- dashboard 生成与 smoke test
+- npm package dry run
+- GUI 子模块 typecheck、测试和 build
+
+GitHub branch protection 和 required checks 由仓库 owner 在 GitHub 上管理。贡献者只需要让 PR 聚焦、说明清楚并附上验证证据。

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

@@ -0,0 +1,113 @@
+# 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/` and `docs/Harness-Ledger.md` | Agents and project owners | Task plans, generated task lifecycle index, 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/Harness-Ledger.md`
+- `docs/09-PLANNING/TASKS/<task>/task_plan.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.