coding-agent-harness 1.0.2 → 1.0.5

package/templates-zh-CN/reference/pull-request-standard.md

@@ -0,0 +1,106 @@
+# PR 提交标准
+
+## 职责
+
+每个非平凡 PR 都必须让 maintainer 在不阅读完整 agent 对话的情况下完成审查。PR body 是审查交接包：说明改了什么、为什么改、如何验证、影响哪个版本、还剩什么风险。
+
+## 必需结构
+
+如果仓库面向中英文用户，或本次任务讨论是中文，PR 必须中英双语。公开 GitHub 读者优先读英文，所以英文在前，简体中文在后。
+
+PR body 必须包含：
+
+1. Summary / 摘要
+2. What Changed / 改动内容
+3. Version Impact / 版本影响
+4. Verification / 验证
+5. Review Evidence / 审查证据
+6. Residual Risk / 残余风险
+7. References / 关联材料
+
+## 内容规则
+
+- 必须明确目标版本。如果 `package.json` 从 `1.0.2` 变为 `1.0.3`，就在版本影响里写清楚。
+- 改动内容按用户可见面或模块总结，不要只堆文件路径。
+- 验证必须列真实命令、浏览器检查、CI run 或证据产物。没有跑的检查必须说明原因。
+- 审查证据必须说明自查、subagent 审查、人工审查或代码质量审查状态。release-blocking finding 必须在 merge 前关闭或路由。
+- 残余风险必须区分已接受风险、延期 follow-up、无关本地或私有债务。
+- 关联材料必须链接相关 task doc、SSoT 行、review 文件、commit、issue 或 PR。
+
+## 模板
+
+```markdown
+## Summary
+
+[One or two sentences explaining the intent and outcome.]
+
+## What Changed
+
+- [User-facing or module-level change.]
+- [Governance, CLI, dashboard, docs, or template change.]
+
+## Version Impact
+
+- Package version: `[old]` -> `[new]`
+- Release notes: [CHANGELOG entry or reason no release note is needed]
+
+## Verification
+
+- `[command]`: pass
+- `[browser/runtime/CI evidence]`: pass
+- Not run: [reason]
+
+## Review Evidence
+
+- Self-review: [summary]
+- Additional review: [reviewer/subagent/human result]
+- Blocking findings: [none / closed / routed]
+
+## Residual Risk
+
+- [none / accepted / deferred / unrelated debt]
+
+## References
+
+- Task: [path or issue]
+- Review: [path or PR review]
+- Evidence: [path, commit, screenshot, workflow, or dashboard]
+
+---
+
+## 摘要
+
+[用一两句话说明目标和结果。]
+
+## 改动内容
+
+- [面向用户或模块级改动。]
+- [治理、CLI、Dashboard、文档或模板改动。]
+
+## 版本影响
+
+- 包版本：`[旧版本]` -> `[新版本]`
+- 发布说明：[CHANGELOG 条目或无需发布说明的原因]
+
+## 验证
+
+- `[命令]`：通过
+- `[浏览器 / 运行时 / CI 证据]`：通过
+- 未运行：[原因]
+
+## 审查证据
+
+- 自查：[摘要]
+- 额外审查：[reviewer / subagent / human 结果]
+- 阻塞发现：[无 / 已关闭 / 已路由]
+
+## 残余风险
+
+- [无 / 已接受 / 已延期 / 无关债务]
+
+## 关联材料
+
+- 任务：[路径或 issue]
+- 审查：[路径或 PR review]
+- 证据：[路径、commit、截图、workflow 或 dashboard]
+```

package/templates-zh-CN/reference/repo-governance-standard.md

@@ -33,7 +33,7 @@
 | --- | --- |
 | 是否必须 PR | yes / no / local-only |
 | PR 标题格式 | 通常与 commit 规范一致 |
-| PR 描述要求 | 改动、原因、验证、residual、关联 task / SSoT / review |
+| PR 描述要求 | 遵守 `docs/11-REFERENCE/pull-request-standard.md`；写清改动、原因、版本影响、验证、residual、关联 task / SSoT / review |
 | 必需审查者 | reviewer、外部 agent、人类 owner 或代码 owner |
 | 必需审查类型 | self-review、subagent review、human review、security review |
 | merge method | merge commit、squash、rebase、fast-forward |
@@ -73,7 +73,7 @@
 | branch 命名 | 分支模式 |
 | owner 规则 | 谁创建、谁清理、谁集成 |
 | subagent worker 规则 | 每个可写 worker 使用独立 worktree / branch，并 handoff commit SHA |
-| 主动提交规则 | 已验证的、有意义的切片默认主动提交；暂不提交必须写明原因 |
+| 主动提交规则 | 已验证的、有意义的切片默认主动提交；暂不提交必须写明 no-commit reason、owner 和下一步 |
 | merge 顺序 | coordinator 或 release owner 决定 |
 | 清理规则 | merge 后删除，保留需写原因 |
 
@@ -82,5 +82,6 @@
 - 非平凡任务的 PR 或 walkthrough 必须说明 required checks 的执行结果。
 - branch protection 未 verified 时，不能声称仓库已受保护；只能写 `designed`、`implemented` 或 `blocked-with-owner`。
 - worker 结果只能通过 commit / branch 集成，不能混入 coordinator 未提交改动。
-- coordinator 自己执行时也要主动提交已验证切片；未提交状态必须有 owner、原因和下一步。
+- coordinator 自己执行时也要主动提交已验证切片；未提交状态必须有 no-commit reason、owner 和下一步。
+- 不得把无关 dirty 改动混入任务提交；CLI-owned Harness 写入应优先用本地 Harness 命令，让加锁、allowlist 和自动提交保护共享治理文件。
 - repo governance 变化必须同步 CI/CD 标准、worktree 标准和 Harness Ledger。

package/templates-zh-CN/reference/review-routing-standard.md

@@ -28,14 +28,21 @@
 
 ## 可写执行者与只读审查者的区别
 
+任务开始时，先读取当前任务 `execution_strategy.md` 的 Subagent Authorization 和 Subagent Delegation Decision，并向用户说明当前授权状态和分工判断。用户不需要知道或主动要求 subagent；coordinator 必须从用户目标主动评估。
+
 审查路由默认把 subagent 当只读 reviewer。只要 subagent 被要求直接改代码、测试、产品文档或 harness 文档，它就不再是 reviewer，而是 worker。
+Reviewer subagent 在单个任务内默认允许，可重复用于只读审查。
 
-Worker 必须走 `worktree-standard.md`：
+Worker 必须走 `worktree-standard.md`，并先在 `execution_strategy.md` 记录一次用户授权：
 
 - coordinator 先分配独立 worktree / branch、任务目录和 write scope。
 - worker 在自己的 worktree 内实现、验证并提交。
 - worker handoff 写明 branch、commit SHA、checks、residual。
 - coordinator 负责 merge、冲突处理、最终 gates 和 integration evidence。
+- 同一任务、同一范围、同一 worktree/branch 内可复用该授权；范围变化时重新请求授权。
+- 如果 worker subagent 对任务有明显帮助但尚未授权，coordinator 必须用白话主动向用户申请一次授权；可以直接说 worker subagent，但不要等用户知道或提醒使用 subagent。
+- 如果独立切片已经明显但精确文件路径还不清楚，先确认文件路径，然后在 implementation 前立刻申请独立执行助手授权。
+- 一旦 `Would a worker subagent materially help?` 的决策是 `ask-user`，必须暂停 implementation，直到 `User Authorization Decision` 记录 `authorized`、`denied` 或 `not-needed`。
 
 禁止把多个 worker 的未提交改动混在 coordinator 当前 checkout，再由 coordinator 一次性提交。
 

package/templates-zh-CN/reference/walkthrough-standard.md

@@ -69,8 +69,9 @@ Closeout SSoT 中：
 任一答案为“有”时：
 
 - 先在任务目录 `lesson_candidates.md` 写候选。
-- 人工审查后，如需沉淀，再由维护命令写 lesson 详情文档并追加 Lessons SSoT。
-- Lessons SSoT 的详情文档列必须指向该详情文档。
+- 候选进入 `needs-promotion` 时，同步写任务本地 `lessons/LC-*.md` 详情文件，并在 `Detail Artifact` 链接。
+- 人工审查后，如需沉淀，再由维护命令写 promoted lesson 详情文档。
+- `checked-created:<L-ID>` 必须能追溯到该详情文档。
 
 三个答案都为“没有”时，Closeout SSoT 和 Harness Ledger 仍要记录：
 

package/templates-zh-CN/walkthrough/Closeout-SSoT.md

@@ -39,4 +39,4 @@
 3. `证据` 必须列出实际检查、冒烟、review、运行时验证或发布证据。
 4. `残余路由` 必须写 `none`，或指向负责人、任务、Regression SSoT、Harness Ledger、issue 或接受风险记录。
 5. `Lessons 检查` 只能写 `checked-candidate: LC-...`、`queued-promotion: LC-...`、`checked-created: L-YYYY-MM-DD-NNN`，或旧任务兼容的 `checked-none: [原因]`。
-6. `checked-created` 必须同时存在 Lessons SSoT 行和 lesson 详情文档；`queued-promotion` 必须能追溯到任务目录 `lesson_candidates.md`。
+6. `checked-created` 必须存在 promoted lesson 详情文档；`queued-promotion` 必须能追溯到任务目录 `lesson_candidates.md`。

package/scripts/smoke-dashboard.mjs

@@ -1,92 +0,0 @@
-#!/usr/bin/env node
-
-import fs from "node:fs";
-import os from "node:os";
-import path from "node:path";
-import { spawnSync } from "node:child_process";
-
-const repoRoot = path.resolve(path.dirname(new URL(import.meta.url).pathname), "..");
-const node = process.execPath;
-const cli = path.join(repoRoot, "scripts/harness.mjs");
-const tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), "harness-dashboard-smoke-"));
-
-function run(args) {
-  const result = spawnSync(node, [cli, ...args], { cwd: repoRoot, encoding: "utf8" });
-  if (result.status !== 0) {
-    throw new Error(`${args.join(" ")} failed\nSTDOUT:\n${result.stdout}\nSTDERR:\n${result.stderr}`);
-  }
-  return result;
-}
-
-function assert(condition, message) {
-  if (!condition) throw new Error(message);
-}
-
-function smokeTarget(target, name) {
-  const outDir = path.join(tmpRoot, name);
-  const outFile = path.join(tmpRoot, `${name}.html`);
-  run(["dashboard", "--out-dir", outDir, target]);
-  run(["dashboard", "--out", outFile, target]);
-  for (const required of [
-    "index.html",
-    "assets/app.css",
-    "assets/app.js",
-    "assets/dashboard-data.js",
-    "data/status.json",
-    "data/tables.json",
-    "data/documents.json",
-    "data/graph.json",
-    "data/adoption.json",
-  ]) {
-    assert(fs.existsSync(path.join(outDir, required)), `${name} missing ${required}`);
-  }
-  const index = fs.readFileSync(path.join(outDir, "index.html"), "utf8");
-  assert(index.includes("dashboard-data.js"), `${name} index missing data bootstrap`);
-  const payload = fs.readFileSync(path.join(outDir, "assets/dashboard-data.js"), "utf8");
-  assert(payload.includes("__HARNESS_DASHBOARD__"), `${name} missing embedded bundle`);
-  const singleFile = fs.readFileSync(outFile, "utf8");
-  assert(singleFile.includes("window.__HARNESS_DASHBOARD__"), `${name} single-file dashboard missing inline bundle`);
-  assert(singleFile.includes("<style>"), `${name} single-file dashboard missing inline CSS`);
-  assert(!singleFile.includes("/Users/lizeyu"), `${name} single-file dashboard leaked local user path`);
-  assert(!singleFile.includes("file://"), `${name} single-file dashboard leaked file URL`);
-  const documents = fs.readFileSync(path.join(outDir, "data/documents.json"), "utf8");
-  assert(!documents.includes(repoRoot), `${name} leaked repo absolute path`);
-  for (const generated of ["data/status.json", "data/tables.json", "data/documents.json", "data/graph.json", "data/adoption.json", "assets/dashboard-data.js"]) {
-    const content = fs.readFileSync(path.join(outDir, generated), "utf8");
-    assert(!content.includes("/Users/lizeyu"), `${name} ${generated} leaked local user path`);
-    assert(!content.includes("file://"), `${name} ${generated} leaked file URL`);
-  }
-  const docs = JSON.parse(fs.readFileSync(path.join(outDir, "data/documents.json"), "utf8"));
-  const tables = JSON.parse(fs.readFileSync(path.join(outDir, "data/tables.json"), "utf8"));
-  const status = JSON.parse(fs.readFileSync(path.join(outDir, "data/status.json"), "utf8"));
-  assert(typeof status.summary?.fullCutoverEligible === "boolean", `${name} missing fullCutoverEligible`);
-  assert(Number.isFinite(Number(status.summary?.legacyVisualOnlyCount)), `${name} missing legacyVisualOnlyCount`);
-  assert(Number.isFinite(Number(status.summary?.unknownClassificationCount)), `${name} missing unknownClassificationCount`);
-  assert(Number.isFinite(Number(status.summary?.weakBriefCount)), `${name} missing weakBriefCount`);
-  assert(Number.isFinite(Number(status.summary?.missingCanonicalVisualMapCount)), `${name} missing missingCanonicalVisualMapCount`);
-  assert(!JSON.stringify(docs.documents.map((doc) => doc.path)).includes("_task-template"), `${name} documents included task template paths`);
-  assert(!JSON.stringify(tables.tables.map((table) => table.source)).includes("_task-template"), `${name} tables included task template sources`);
-  return outDir;
-}
-
-smokeTarget("examples/minimal-project", "example");
-
-const mingjingDocs = "/Users/lizeyu/Projects/mingjing-app/docs";
-if (fs.existsSync(mingjingDocs)) {
-  const mingjingRepo = path.dirname(mingjingDocs);
-  const before = spawnSync("git", ["-C", mingjingRepo, "status", "--short", "--", "docs"], { encoding: "utf8" }).stdout;
-  smokeTarget(mingjingDocs, "mingjing");
-  const after = spawnSync("git", ["-C", mingjingRepo, "status", "--short", "--", "docs"], { encoding: "utf8" }).stdout;
-  assert(before === after, "Mingjing docs changed during dashboard smoke");
-}
-
-const extraTargets = (process.env.HARNESS_DASHBOARD_SMOKE_TARGETS || "")
-  .split(",")
-  .map((target) => target.trim())
-  .filter(Boolean);
-for (const [index, target] of extraTargets.entries()) {
-  assert(fs.existsSync(target), `extra dashboard smoke target does not exist: ${target}`);
-  smokeTarget(target, `extra-${index + 1}`);
-}
-
-console.log(`Dashboard smoke passed: ${tmpRoot}`);