coding-agent-harness 1.0.1 → 1.0.4

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

@@ -0,0 +1,113 @@
+# 文档受众与表面边界
+
+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/` 与 `docs/Harness-Ledger.md` | Agent 和项目负责人 | 任务计划、生成的任务生命周期索引、当前状态 | 通用营销材料 |
+| 目标项目 `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/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 文档应该具体、短路径、可检查。不要把它写成文章，也不要让 Agent 从长篇叙事里猜执行合同。
+
+## 发布文档
+
+发布文档要解释 Coding Agent Harness 的公开能力，而不是记录维护者自己的开发过程。
+
+可以发布：
+
+- 架构总览。
+- 安装和迁移指南。
+- 单仓、多仓、主控仓库模式的选择指南。
+- 给 Agent 使用的公开迁移 prompt。
+- 可复用的工程方法论。
+
+不应发布：
+
+- 某个私有任务的进行中结论。
+- 私有 review 草稿。
+- 只对某台机器有效的路径。
+- 客户或团队内部状态。
+- 还没有脱敏的 ledger、handoff、walkthrough。
+
+## 写作规则
+
+1. 先判断读者，再写文件。
+2. 人读文档负责解释为什么；Agent 文档负责定义怎么做。
+3. 公开文档可以引用模式和结构，不要引用私有运行状态。
+4. 任务状态只写在 SSoT、task、review、walkthrough 和 ledger 里。
+5. 如果一个文档既要给人读又要给 Agent 执行，把它拆成两份：公开说明和执行合同。
+
+## 一个判断问题
+
+写文档前问一句：
+
+> 这个文件被谁在什么时刻读取，并且读取后要做什么动作？
+
+如果答案是“人用来理解”，放在公开指南或架构文档里。
+
+如果答案是“Agent 用来执行”，放在目标项目的入口、任务、标准或回归文件里。
+
+如果答案是“维护者记录当前仓库如何运转”，它不是公开发布文档。

package/docs-release/guides/full-legacy-migration-subagent-strategy.md

@@ -0,0 +1,334 @@
+# Full Legacy Migration Subagent Strategy
+
+Chinese mirror: `docs-release/guides/full-legacy-migration-subagent-strategy.zh-CN.md`
+
+This guide is for agents migrating a large pre-v1 Harness project all the way to a readable v1 cutover.
+
+Use it when the user needs proof that another agent can migrate an old project, not just a baseline safe-adoption report.
+
+## Definition of Done
+
+A legacy migration is complete only when all of these are true:
+
+- `migrate-plan` reports `mode=declared-capability`.
+- `migrate-plan.summary.warnings=0`.
+- `taskActions=0`, `reviewSchemaGaps=0`, `legacyReferenceGaps=0`, `legacyResiduals=0`.
+- `recommendedCapabilities=[]`.
+- `harness check --profile target-project` passes.
+- `harness check --profile target-project --strict` passes.
+- `migrate-verify <session.json>` passes on a fresh final session.
+- The dashboard opens as HTML and the task index is usable.
+- Dashboard status data reports `summary.briefCoverage.ready == total` and `missing == 0`.
+- Every task has a readable standalone `brief.md`, not just a legacy `task_plan.md` fallback.
+- Final adversarial reviews pass after any fixes.
+
+If any item above is not true, report the migration as `baseline` or `strict deferred`, not complete.
+
+## Agent-Recommend Migration Depth
+
+Full migration does not begin by asking the user to pick a mode. The target-project agent must run a read-only scan first, recommend a migration depth from evidence, and wait for user confirmation before writing files.
+
+| Mode | Purpose | Accepts residuals | Completion claim |
+| --- | --- | --- | --- |
+| `baseline-preserve` | Preserve history, create registry, produce first dashboard, expose warning queue. | Yes | "usable baseline" |
+| `status-aware-rewrite` | Use SSoT / Ledger / progress / review / git evidence to rewrite current, reopened, or current-evidence tasks; historical tasks become readable index cards or residuals. | Allowed, but must be explained. | "migration usable" or proceed to full cutover |
+| `full-semantic-rewrite` | Prove the old project can be rebuilt as a readable v1 project, with all tasks dashboard-readable and CLI strict-clean. | No, unless explicitly accepted by user. | "migration complete" |
+
+Baseline mode may leave historical tasks in legacy format. Status-aware rewrite may rewrite existing briefs, execution strategies, and visual maps, but only when evidence requires it. Full semantic rewrite may not leave missing briefs, unresolved warnings, or strict failures.
+
+## Coordinator Contract
+
+The coordinator owns orchestration and verification. Subagents own bounded migration slices.
+
+Coordinator rules:
+
+- Do not fix target files manually unless a subagent is blocked and the user accepts coordinator intervention.
+- Give each worker a disjoint write scope.
+- Tell every worker that other agents are active and that they must not revert or overwrite other work.
+- Use subagents for execution and separate subagents for adversarial review.
+- Treat subagent reports as claims until the coordinator reruns checks.
+- Regenerate the final `migrate-run` session after all cleanup. A baseline session is not final evidence.
+- Keep the target git index unstaged unless the user asks to stage.
+- The first pass is read-only scan and recommendation. Do not start write workers before the user confirms migration depth.
+
+## Phase 0: Read-Only Scan and User Confirmation
+
+Run:
+
+```bash
+git -C /path/to/project status --short --branch
+harness status --json /path/to/project > /tmp/cah-baseline-status.json
+harness migrate-plan --json --limit 1000 /path/to/project > /tmp/cah-baseline-plan.json
+```
+
+Decide locale explicitly:
+
+- Use `zh-CN` for Chinese users, Chinese operating docs, or Chinese project context.
+- Use `en-US` for English teams or English-facing project docs.
+- If mixed-language signals conflict, stop and ask the user.
+
+Turn the scan into a migration plan. It must include task count, brief coverage, canonical `visual_map.md` coverage, warning/action/residual counts, strict status, dirty file explanation, recommended mode, estimated write scope, token/time cost, subagent split, and questions for user confirmation.
+
+After the user confirms migration depth, run the baseline rail:
+
+```bash
+harness migrate-run \
+  --locale zh-CN \
+  --session-dir /tmp/cah-migration-baseline \
+  --out-dir /tmp/cah-migration-baseline/dashboard \
+  /path/to/project
+```
+
+If the target is already dirty, use `--allow-dirty` only after recording why the dirty files belong to this migration.
+
+Then run:
+
+```bash
+harness migrate-verify /tmp/cah-migration-baseline/session.json
+```
+
+This proves the migration rail works. It does not prove full migration unless all completion gates are already zero.
+
+## Phase 1: Work Queue
+
+Read:
+
+- `/tmp/cah-baseline-plan.json`
+- `/tmp/cah-migration-baseline/session.json`
+- `docs/Harness-Ledger.md`
+- `docs/10-WALKTHROUGH/Closeout-SSoT.md`
+- `docs/05-TEST-QA/Regression-SSoT.md`
+- current task `progress.md`, `review.md`, `findings.md`
+- git history when task status is unclear
+
+Build the queue in this order:
+
+1. Capability registry and locale.
+2. Task contracts: `brief.md`, `execution_strategy.md`, `visual_map.md`.
+3. Review schema.
+4. Legacy governance and reference checker failures.
+5. Dashboard readability briefs for every task.
+6. Quality repair for weak briefs or stale dashboard data.
+
+Do not move to final verification while any queue has open items.
+
+## Phase 2: Execution Subagents
+
+Use small, bounded worker roles. These roles can run sequentially or in parallel when write scopes do not overlap.
+
+| Worker | Write scope | Goal |
+| --- | --- | --- |
+| Task Contract Worker | `docs/09-PLANNING/TASKS/**/brief.md`, `execution_strategy.md`, `visual_map.md`, optional same-task `progress.md` log | Remove task contract failures; in a confirmed rewrite mode, rewrite weak old surfaces. |
+| Review/Capability Worker | `.harness-capabilities.json`, current strict review files | Declare real capabilities and normalize release-blocking review schema. |
+| Legacy Governance Worker | `AGENTS.md`, PR template or residual, `docs/11-REFERENCE/**`, Ledger, Closeout SSoT, lesson candidates/detail docs, walkthrough template | Clear legacy checker failures. |
+| Brief Coverage Workers | disjoint task-date or module ranges, missing or explicitly weak `brief.md` files | Reach dashboard brief coverage 100 percent and remove empty templates. |
+| Quality Repair Worker | only files named by reviewer | Remove weak brief patterns and stale dashboard assumptions. |
+
+Worker prompt requirements:
+
+- State the exact target path.
+- State the exact allowed write scope.
+- Tell the worker not to submit git changes.
+- Tell the worker not to overwrite existing user or other-agent changes.
+- Require local evidence, not generic templates; existing files may be rewritten only under user-confirmed rewrite scope and evidence.
+- Require a final self-check command or scan.
+- Ask for changed path summary and residuals.
+
+Example brief worker prompt:
+
+```text
+Your write scope is only docs/09-PLANNING/TASKS/2026-03-11* through 2026-03-31*/brief.md.
+Only create missing brief.md unless the coordinator explicitly assigned user-confirmed rewrite scope. Do not edit progress.md, task_plan.md, review.md, execution_strategy.md, or visual_map.md unless they are in your assigned write scope.
+Every brief must be Chinese-first if locale is zh-CN and must cite this task's task_plan.md/progress.md/findings.md/review evidence.
+Do not leave parser-failure phrases such as "unknown", "could not parse", "若干", "未能解析", "未提供 Current Focus", or "无明确 Roadmap Binding".
+```
+
+## Phase 3: Capability Registry
+
+Full cutover requires declared-capability mode.
+
+Sequentially add capabilities. Do not run `add-capability` in parallel against the same target registry.
+
+```bash
+harness add-capability safe-adoption --locale zh-CN /path/to/project
+harness add-capability dashboard --locale zh-CN /path/to/project
+harness add-capability long-running-task --locale zh-CN /path/to/project
+harness add-capability adversarial-review --locale zh-CN /path/to/project
+```
+
+Declare optional capabilities only when project facts justify them. If legacy artifacts prove the capability exists and strict migration adopts the corresponding standards, declare it.
+
+Verify:
+
+```bash
+harness migrate-plan --json --limit 1000 /path/to/project
+```
+
+Expected:
+
+- `mode=declared-capability`
+- `recommendedCapabilities=[]`
+
+## Phase 4: Task Contracts
+
+For every task that must be readable in the dashboard:
+
+- `brief.md` answers what the task is, why it matters, what a human should inspect first, current state, risks, residuals, and evidence sources.
+- `execution_strategy.md` explains how an agent should resume or verify the task.
+- `visual_map.md` is a diagram collection: include phase flow, sequence, architecture, data-flow, state, topology, or decision maps only when they help a human understand the task. Do not require every diagram type, and do not generate empty diagrams.
+
+Full readable cutover requires every task to have a standalone `brief.md`. This is stricter than baseline safe-adoption.
+
+Brief minimum structure:
+
+```markdown
+# Brief
+
+## Task Goal
+
+## First Human Read
+
+## Execution and Evidence Flow
+
+## Current Status Judgment
+
+## Risks and Residuals
+
+## Evidence Sources
+```
+
+For `zh-CN`, use Chinese headings:
+
+```markdown
+# Brief
+
+## 任务目标
+
+## 迁移后的第一眼
+
+## 执行/证据流
+
+## 当前状态判断
+
+## 风险与残余
+
+## 证据来源
+```
+
+Unacceptable brief content:
+
+- Empty template text.
+- Parser failure text such as `若干`, `未能解析`, `unknown`, `not parsed`.
+- Claims of completion without evidence.
+- A summary that does not cite local files.
+- English stub headings in a Chinese migration.
+
+## Phase 5: Legacy Governance
+
+Strict cutover may still fail after task/review cleanup because old checker rules require governance surfaces.
+
+Fix or route:
+
+- `AGENTS.md` routes to all adopted standards and SSoTs.
+- `repo-governance-standard.md` includes repo platform profile, PR policy, and branch protection.
+- `delivery-operating-model-standard.md` defines operating model profile, agent visibility, and delivery SSoT.
+- PR template exists or an explicit blocked-with-owner residual exists.
+- `Harness-Ledger.md` includes repo governance / CI-CD and Lessons Check columns.
+- `Closeout-SSoT.md` includes walkthrough, Lessons Check, and closeout status.
+- Promoted lessons live in `docs/01-GOVERNANCE/lessons/*.md`; task-local candidates stay in `lesson_candidates.md`.
+- `_walkthrough-template.md` includes Lessons Reflection.
+
+Do not overwrite business facts. Merge missing columns or append a migration section when possible.
+
+## Phase 6: Dashboard Smoke
+
+Generate a fresh final dashboard after all fixes:
+
+```bash
+rm -rf /tmp/cah-migration-final
+harness migrate-run \
+  --allow-dirty \
+  --locale zh-CN \
+  --session-dir /tmp/cah-migration-final \
+  --out-dir /tmp/cah-migration-final/dashboard \
+  /path/to/project
+```
+
+Then verify:
+
+```bash
+harness migrate-verify /tmp/cah-migration-final/session.json
+```
+
+Serve the dashboard when `file://` cannot be opened:
+
+```bash
+cd /tmp/cah-migration-final/dashboard
+python3 -m http.server 55983 --bind 127.0.0.1
+```
+
+Dashboard smoke must check:
+
+- First screen says status passed.
+- Brief coverage is `total/total`.
+- Warning count is 0.
+- Strict cutover count is 0.
+- Task index opens.
+- Task index shows `total / total`.
+- Search, status filter, and grouping controls render.
+- At least one task detail opens.
+
+Data smoke must check:
+
+```bash
+node -e '
+const fs = require("fs");
+const status = JSON.parse(fs.readFileSync("/tmp/cah-migration-final/dashboard/data/status.json", "utf8"));
+console.log(status.summary.briefCoverage);
+console.log(status.tasks.filter((task) => task.briefSource !== "standalone" || !task.briefPath).slice(0, 5));
+'
+```
+
+Expected:
+
+- `ready == total`
+- `missing == 0`
+- no task without `briefPath`
+
+## Phase 7: Adversarial Review
+
+Run at least three independent review lanes after the coordinator believes migration is done.
+
+| Reviewer | Checks | Failure examples |
+| --- | --- | --- |
+| CLI/session reviewer | `migrate-plan`, normal, strict, `migrate-verify`, session fields, dashboard data. | `legacy-compat`, stale session, strict deferred, no brief coverage summary. |
+| Brief quality reviewer | Missing brief scan and sampled brief quality across time ranges/modules. | Empty templates, parser-failure text, no evidence sources, wrong language. |
+| Boundary reviewer | Source repo cleanliness, private/public boundary, target dirty whitelist, staged files. | Private docs staged publicly, target staged files, unexpected target paths. |
+| External source reviewer (when applicable) | External material is in source packs, digests are projected into `03/04/06`, and sensitive raw material is not committed. | Raw external documents dumped into execution dirs, digest has no projection, possible secrets or customer data committed. |
+
+If any reviewer says FAIL:
+
+1. Treat it as valid until disproven with evidence.
+2. Fix the target or the harness data contract.
+3. Regenerate final session and dashboard.
+4. Re-run only the failed review plus the coordinator's full smoke.
+
+Do not end with a known FAIL review.
+
+## Final Report Template
+
+Report:
+
+- Target path.
+- Final dashboard URL/path.
+- Capability registry.
+- `migrate-plan` zero counts.
+- normal and strict check results.
+- `migrate-verify` result.
+- Dashboard brief coverage.
+- Subagent worker roles used.
+- Final adversarial review outcomes.
+- Target git status: staged count and dirty path categories.
+- Any accepted residuals. If none, say none.
+
+Do not say "complete" unless all Definition of Done gates pass.