coding-agent-harness 1.0.1 → 1.0.2

package/templates-zh-CN/reference/external-source-intake-standard.md

@@ -0,0 +1,82 @@
+# 外部资料摄取标准
+
+## 职责
+
+本标准定义 Agent 如何接收、过滤、整理外部项目或微服务团队提供的大量文档。目标是把外部资料变成可执行上下文，而不是把资料堆进 `03/04/06`。
+
+## 核心模型
+
+```text
+外部原始资料 -> source pack 索引 -> digest 摘要 -> 03/04/06 执行投影
+```
+
+`03-ARCHITECTURE`、`04-DEVELOPMENT`、`06-INTEGRATIONS` 只保存已经提炼并可用于执行的事实。外部团队丢来的原文、长文档、截图、聊天记录、导出包和历史资料先进入 `docs/04-DEVELOPMENT/external-source-packs/`，不能直接污染执行文档。
+
+## 何时询问用户
+
+在 Diagnose / Decide 阶段，只要发现以下任一信号，Agent 必须询问用户是否有外部资料：
+
+- 当前仓库属于多仓系统、微服务系统、前后端分仓或平台子系统。
+- 代码中出现外部服务、SDK、API gateway、message queue、webhook、contract、schema 或 mock。
+- 用户提到“其他仓库”“外部服务”“上下游”“接口文档”“业务知识”“系统整体设计”。
+- Agent 无法只靠当前仓库判断服务职责、接口契约或联调方式。
+
+推荐问题：
+
+1. 这个项目是否依赖外部服务或其他仓库？
+2. 你是否有外部团队提供的架构文档、接口文档、流程图、会议纪要、代码路径、链接或导出包？
+3. 这些资料能否复制进本仓？如果不能，是否只能保存本地路径或 URL？
+4. 哪些资料是可信来源，哪些只是历史参考？
+
+## 存储规则
+
+| 场景 | 存储方式 |
+| --- | --- |
+| 只有 1-4 个稳定外部文档 | 不必建独立 source pack；在对应 `03/04/06` 的 `Source Evidence` 中链接即可 |
+| 外部资料超过 5 份、跨多个主题、或会持续增长 | 创建 `docs/04-DEVELOPMENT/external-source-packs/<source-key>/` |
+| 资料含敏感信息、密钥、客户数据或不能进仓 | 不复制原文；在 source pack README 记录外部路径、owner、访问条件和摘要 |
+| 资料是可公开或可入仓的原始文档 | 可放 `raw/`，但仍要经过 digest 后才能投影到执行文档 |
+
+建议结构：
+
+```text
+docs/04-DEVELOPMENT/external-source-packs/<source-key>/
+├── README.md              # 资料索引和投影状态
+├── digests/               # 每份或每组资料的摘要
+├── raw/                   # 可入仓原文；禁止放密钥、隐私或客户数据
+└── raw-index.md           # 原文不能入仓时，用路径/URL/owner 索引替代 raw/
+```
+
+不要为每个微服务复制一套完整 `03/04/06` 目录。source pack 是资料入口；稳定执行入口仍然是：
+
+- `docs/03-ARCHITECTURE/service-catalog.md`
+- `docs/03-ARCHITECTURE/services/<service-key>.md`
+- `docs/04-DEVELOPMENT/external-context/<service-key>.md`
+- `docs/06-INTEGRATIONS/<contract>.md`
+
+## 摄取流程
+
+1. **Inventory**：列出所有外部资料，记录来源、owner、时间、可信度、是否可入仓。
+2. **Classify**：按 architecture、development、integration、security、operations、product、unknown 分类。
+3. **Sanitize**：检查密钥、token、客户数据、隐私、内部账号、不可公开链接；不能入仓的只存引用。
+4. **Digest**：用 digest 模板提炼事实、疑问、不安全假设和证据。
+5. **Project**：把稳定事实投影到 `03/04/06`，并在 source pack README 标记 projected。
+6. **Verify**：能用代码、接口测试、owner 确认或运行证据验证的，更新 `Last Verified` 和 `Confidence`。
+7. **Residual**：不能确认的内容留在 source pack，不进入执行文档，或进入 `Do Not Assume`。
+
+## 投影规则
+
+| 资料内容 | 投影位置 |
+| --- | --- |
+| 服务职责、上下游、owner、数据归属、系统拓扑 | `03-ARCHITECTURE/service-catalog.md` 或 `services/<service-key>.md` |
+| 本仓开发时如何 mock、stub、启动、联调、排查 | `04-DEVELOPMENT/external-context/<service-key>.md` |
+| endpoint、payload、auth、error、event、webhook、SDK、contract test | `06-INTEGRATIONS/<contract>.md` |
+| 仍未确认、来源冲突、过期或只作为背景参考 | 留在 source pack README / digest，不进入执行文档 |
+
+## 禁止事项
+
+- 不要把几十份外部文档直接复制到 `03-ARCHITECTURE`、`04-DEVELOPMENT` 或 `06-INTEGRATIONS` 根目录。
+- 不要把外部资料摘要当成已验证事实；必须记录 `Source Evidence`、`Last Verified` 和 `Confidence`。
+- 不要在执行文档里保留大段原文、聊天流水或历史会议记录。
+- 不要把密钥、真实 token、客户数据、个人隐私或不可公开资料提交进仓。
+- 不要为了“完整”而给每个微服务复制一套目录树；只给资料量大的外部来源建 source pack。

package/templates-zh-CN/reference/harness-ledger-standard.md

@@ -37,7 +37,8 @@ docs/Harness-Ledger.md
 4. 状态值使用固定词，避免自由文本失控。
 5. 任务收口时最后更新 Harness Ledger。
 6. `closed` 行必须有 Lessons 检查结果。
-7. `checked-created` 必须引用 lesson ID 和详情文档。
+7. 新任务默认引用 `lesson_candidates.md`，并使用 `checked-candidate`、`queued-promotion` 或 `checked-created` 记录人工判定。
+8. `checked-created` 必须引用 lesson ID 和详情文档。
 8. 如果 closeout、review 或 regression 被跳过，必须写 `skipped-with-reason`。
 
 ## 固定状态词
@@ -46,6 +47,8 @@ docs/Harness-Ledger.md
 - `updated`
 - `created`
 - `checked-none`
+- `checked-candidate`
+- `queued-promotion`
 - `checked-created`
 - `n/a`
 - `skipped-with-reason`
@@ -66,7 +69,7 @@ docs/Harness-Ledger.md
 - [ ] Regression SSoT / Cadence Ledger 已更新，或标记 `n/a`。
 - [ ] walkthrough 已创建，或 Closeout SSoT 写明受控跳过原因。
 - [ ] walkthrough 包含 Lessons 反思。
-- [ ] Lessons 检查结果为 `checked-none: <reason>` 或 `checked-created: L-YYYY-MM-DD-NNN`。
+- [ ] Lessons 检查结果为 `checked-candidate: LC-...`、`queued-promotion: LC-...`、`checked-created: L-YYYY-MM-DD-NNN`，或旧任务兼容的 `checked-none: <reason>`。
 - [ ] Harness Ledger 行已收口，或 residual 已写明 owner 和后续路径。
 
 ## 框架更新检查清单

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

@@ -73,6 +73,7 @@
 | branch 命名 | 分支模式 |
 | owner 规则 | 谁创建、谁清理、谁集成 |
 | subagent worker 规则 | 每个可写 worker 使用独立 worktree / branch，并 handoff commit SHA |
+| 主动提交规则 | 已验证的、有意义的切片默认主动提交；暂不提交必须写明原因 |
 | merge 顺序 | coordinator 或 release owner 决定 |
 | 清理规则 | merge 后删除，保留需写原因 |
 
@@ -81,4 +82,5 @@
 - 非平凡任务的 PR 或 walkthrough 必须说明 required checks 的执行结果。
 - branch protection 未 verified 时，不能声称仓库已受保护；只能写 `designed`、`implemented` 或 `blocked-with-owner`。
 - worker 结果只能通过 commit / branch 集成，不能混入 coordinator 未提交改动。
+- coordinator 自己执行时也要主动提交已验证切片；未提交状态必须有 owner、原因和下一步。
 - repo governance 变化必须同步 CI/CD 标准、worktree 标准和 Harness Ledger。

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

@@ -55,7 +55,7 @@ docs/10-WALKTHROUGH/Closeout-SSoT.md
 Closeout SSoT 中：
 
 - walkthrough 列写实际路径，或写受控跳过原因。
-- Lessons 检查列写 `checked-created: L-YYYY-MM-DD-NNN` 或 `checked-none: <reason>`。
+- Lessons 检查列写 `checked-candidate: LC-...`、`queued-promotion: LC-...`、`checked-created: L-YYYY-MM-DD-NNN`，或旧任务兼容的 `checked-none: <reason>`。
 - 允许的跳过原因只有：`docs-only`、`no-runtime`、`superseded`、`historical-backfill`、`owner-deferred`。
 
 ## 经验沉淀反思规则
@@ -68,14 +68,14 @@ Closeout SSoT 中：
 
 任一答案为“有”时：
 
-- 先在 `docs/01-GOVERNANCE/lessons/` 写 lesson 详情文档。
-- 再在 Lessons SSoT 追加一行。
+- 先在任务目录 `lesson_candidates.md` 写候选。
+- 人工审查后，如需沉淀，再由维护命令写 lesson 详情文档并追加 Lessons SSoT。
 - Lessons SSoT 的详情文档列必须指向该详情文档。
 
 三个答案都为“没有”时，Closeout SSoT 和 Harness Ledger 仍要记录：
 
 ```text
-checked-none: <reason>
+lesson_candidates.md: no-candidate-accepted
 ```
 
 ## 收口要求

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

@@ -38,5 +38,5 @@
 2. 实现类任务应写 walkthrough；跳过原因只用于受限场景，不用于省略收口。
 3. `证据` 必须列出实际检查、冒烟、review、运行时验证或发布证据。
 4. `残余路由` 必须写 `none`，或指向负责人、任务、Regression SSoT、Harness Ledger、issue 或接受风险记录。
-5. `Lessons 检查` 只能写 `checked-created: L-YYYY-MM-DD-NNN` 或 `checked-none: [原因]`。
-6. `checked-created` 必须同时存在 Lessons SSoT 行和 lesson 详情文档。
+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`。

package/templates-zh-CN/walkthrough/walkthrough-template.md

@@ -46,8 +46,8 @@
 | 本轮是否暴露 reference、workflow、模板或 checker 的缺口？ | [有 / 无，写一句理由] |
 | 是否出现跨模块、跨阶段、跨 agent 的重复问题？ | [有 / 无，写一句理由] |
 | 下次 agent 是否可能在同类任务中重复踩坑？ | [有 / 无，写一句理由] |
-| Lessons 结果 | `checked-created: L-YYYY-MM-DD-NNN` / `checked-none: [一句话原因]` |
-| Lessons 详情文档 | `docs/01-GOVERNANCE/lessons/[file].md` / `none` |
+| Lessons 结果 | `checked-candidate: LC-...` / `queued-promotion: LC-...` / `checked-created: L-YYYY-MM-DD-NNN` / 旧任务 `checked-none: [一句话原因]` |
+| Lessons 详情文档 | `lesson_candidates.md` / `docs/01-GOVERNANCE/lessons/[file].md` / `none` |
 
 ## 关联索引
 

package/templates-zh-CN/dashboard/assets/app.css

@@ -1,399 +0,0 @@
-:root {
-  color-scheme: light;
-  --bg: #f4f6f3;
-  --surface: #fbfcf8;
-  --surface-2: #eef2ec;
-  --ink: #182018;
-  --muted: #627061;
-  --line: #dce3d8;
-  --accent: #2e6b4f;
-  --accent-2: #9d6b2f;
-  --danger: #a83f32;
-  --warn: #9a6a13;
-  --ok: #2f7b4f;
-  --shadow: 0 18px 45px rgba(32, 43, 28, 0.10);
-  font-family: ui-sans-serif, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
-}
-
-[data-theme="dark"] {
-  color-scheme: dark;
-  --bg: #151812;
-  --surface: #1d2219;
-  --surface-2: #252d20;
-  --ink: #edf1e8;
-  --muted: #a9b4a1;
-  --line: #384230;
-  --accent: #83c69d;
-  --accent-2: #d3a15f;
-  --danger: #e17668;
-  --warn: #e0b456;
-  --ok: #85cf9b;
-  --shadow: 0 18px 45px rgba(0, 0, 0, 0.28);
-}
-
-* { box-sizing: border-box; }
-body {
-  margin: 0;
-  background: var(--bg);
-  color: var(--ink);
-}
-button, select {
-  font: inherit;
-}
-.layout {
-  min-height: 100vh;
-  display: grid;
-  grid-template-columns: 248px minmax(0, 1fr);
-}
-.sidebar {
-  border-right: 1px solid var(--line);
-  background: var(--surface);
-  padding: 22px 18px;
-  position: sticky;
-  top: 0;
-  height: 100vh;
-}
-.brand {
-  display: grid;
-  gap: 4px;
-  margin-bottom: 24px;
-}
-.brand strong { font-size: 18px; }
-.brand span { color: var(--muted); font-size: 13px; }
-.nav {
-  display: grid;
-  gap: 6px;
-}
-.nav button, .control button, .drawer-tabs button {
-  border: 0;
-  background: transparent;
-  color: var(--muted);
-  border-radius: 7px;
-  padding: 9px 10px;
-  text-align: left;
-  cursor: pointer;
-}
-.nav button.active, .nav button:hover, .control button.active, .drawer-tabs button.active {
-  background: var(--surface-2);
-  color: var(--ink);
-}
-.main {
-  padding: 24px clamp(18px, 4vw, 44px);
-  min-width: 0;
-}
-.topbar {
-  display: flex;
-  justify-content: space-between;
-  gap: 18px;
-  align-items: flex-start;
-  margin-bottom: 22px;
-}
-.eyebrow {
-  color: var(--muted);
-  font-size: 13px;
-  margin: 0 0 6px;
-}
-h1, h2, h3, p { margin-top: 0; letter-spacing: 0; }
-h1 { font-size: clamp(26px, 4vw, 42px); line-height: 1.04; max-width: 760px; }
-h2 { font-size: 20px; }
-h3 { font-size: 15px; }
-.controls {
-  display: flex;
-  flex-wrap: wrap;
-  gap: 8px;
-  justify-content: flex-end;
-}
-.control {
-  display: inline-flex;
-  border: 1px solid var(--line);
-  border-radius: 8px;
-  padding: 3px;
-  background: var(--surface);
-}
-.status-grid {
-  display: grid;
-  grid-template-columns: minmax(260px, 1.4fr) repeat(3, minmax(150px, 0.7fr));
-  gap: 12px;
-  margin-bottom: 18px;
-}
-.panel, .metric, .table-panel, .drawer {
-  background: var(--surface);
-  border: 1px solid var(--line);
-  border-radius: 8px;
-  box-shadow: var(--shadow);
-}
-.metric {
-  padding: 16px;
-  min-height: 112px;
-}
-.metric strong {
-  display: block;
-  font-size: 30px;
-  line-height: 1;
-}
-.metric span, .muted { color: var(--muted); }
-.readiness {
-  padding: 18px;
-}
-.readiness .state {
-  display: inline-flex;
-  align-items: center;
-  border-radius: 7px;
-  padding: 6px 9px;
-  font-weight: 700;
-  margin-bottom: 14px;
-}
-.state.pass, .tag.pass { background: color-mix(in srgb, var(--ok) 18%, transparent); color: var(--ok); }
-.state.warn, .tag.warn { background: color-mix(in srgb, var(--warn) 18%, transparent); color: var(--warn); }
-.state.fail, .tag.fail, .tag.open { background: color-mix(in srgb, var(--danger) 18%, transparent); color: var(--danger); }
-.page-grid {
-  display: grid;
-  grid-template-columns: minmax(0, 1fr) 410px;
-  gap: 16px;
-  align-items: start;
-}
-.page-grid > * {
-  min-width: 0;
-}
-.table-panel {
-  overflow: hidden;
-  min-width: 0;
-}
-.panel-head {
-  display: flex;
-  justify-content: space-between;
-  gap: 12px;
-  padding: 14px 16px;
-  border-bottom: 1px solid var(--line);
-}
-.table-wrap { overflow: auto; }
-table {
-  width: 100%;
-  border-collapse: collapse;
-  font-size: 14px;
-}
-[data-density="compact"] table { font-size: 13px; }
-th, td {
-  padding: 11px 12px;
-  border-bottom: 1px solid var(--line);
-  vertical-align: top;
-  text-align: left;
-}
-[data-density="compact"] th, [data-density="compact"] td { padding: 7px 9px; }
-th {
-  color: var(--muted);
-  font-size: 12px;
-  font-weight: 700;
-  text-transform: uppercase;
-}
-tr {
-  cursor: pointer;
-}
-tr:hover td {
-  background: color-mix(in srgb, var(--accent) 8%, transparent);
-}
-.linklike {
-  border: 0;
-  padding: 0;
-  background: transparent;
-  color: var(--accent);
-  font: inherit;
-  text-align: left;
-  cursor: pointer;
-  overflow-wrap: anywhere;
-}
-.linklike:hover { text-decoration: underline; }
-.tag {
-  display: inline-flex;
-  border-radius: 999px;
-  padding: 4px 8px;
-  font-size: 12px;
-  font-weight: 700;
-  background: var(--surface-2);
-}
-.bar {
-  height: 7px;
-  border-radius: 999px;
-  background: var(--surface-2);
-  overflow: hidden;
-  margin-top: 6px;
-}
-.bar i {
-  display: block;
-  height: 100%;
-  background: var(--accent);
-}
-.drawer {
-  position: sticky;
-  top: 18px;
-  min-width: 0;
-  max-height: calc(100vh - 36px);
-  overflow: hidden;
-  display: grid;
-  grid-template-rows: auto auto auto minmax(0, 1fr);
-}
-.drawer-head {
-  padding: 15px 16px;
-  border-bottom: 1px solid var(--line);
-}
-.drawer-tabs {
-  display: flex;
-  gap: 4px;
-  overflow-x: auto;
-  padding: 8px;
-  border-bottom: 1px solid var(--line);
-}
-.drawer-mode {
-  display: flex;
-  gap: 6px;
-  padding: 8px 12px;
-  border-bottom: 1px solid var(--line);
-}
-.drawer-mode button {
-  border: 1px solid var(--line);
-  background: transparent;
-  color: var(--muted);
-  border-radius: 7px;
-  padding: 6px 9px;
-  cursor: pointer;
-}
-.drawer-mode button.active {
-  color: var(--ink);
-  background: var(--surface-2);
-}
-.drawer-tabs button {
-  white-space: nowrap;
-  font-size: 13px;
-}
-.drawer-body {
-  padding: 16px;
-  overflow: auto;
-}
-.markdown {
-  line-height: 1.55;
-  color: var(--ink);
-}
-.markdown h1 { font-size: 24px; }
-.markdown h2 { font-size: 18px; margin-top: 18px; }
-.markdown pre {
-  white-space: pre-wrap;
-  background: var(--surface-2);
-  border-radius: 7px;
-  padding: 10px;
-  overflow: auto;
-}
-.rendered-table-wrap {
-  overflow: auto;
-  margin: 12px 0;
-  border: 1px solid var(--line);
-  border-radius: 7px;
-}
-.rendered-table {
-  min-width: 520px;
-  background: var(--surface);
-}
-.md-table {
-  margin: 0 0 2px;
-  box-shadow: none;
-}
-.mermaid-fallback {
-  margin: 12px 0;
-  border: 1px solid var(--line);
-  border-radius: 8px;
-  padding: 10px;
-  background: var(--surface-2);
-}
-.mermaid-rendered {
-  margin: 12px 0;
-  border: 1px solid var(--line);
-  border-radius: 8px;
-  padding: 10px;
-  background: var(--surface-2);
-  overflow-x: auto;
-}
-.mermaid-rendered figcaption {
-  font-weight: 700;
-  color: var(--accent);
-  margin-bottom: 8px;
-}
-.mermaid-rendered svg {
-  min-width: 360px;
-  width: 100%;
-  height: auto;
-}
-.mermaid-node rect {
-  fill: var(--surface);
-  stroke: var(--accent);
-  stroke-width: 1.5;
-}
-.mermaid-node text {
-  fill: var(--ink);
-  font-size: 11px;
-}
-.mermaid-edge {
-  stroke: var(--accent);
-  stroke-width: 1.5;
-  fill: none;
-}
-.mermaid-arrow {
-  fill: var(--accent);
-}
-.graph-panel {
-  margin-bottom: 16px;
-  overflow: hidden;
-}
-.graph-lanes {
-  display: grid;
-  grid-template-columns: repeat(auto-fit, minmax(170px, 1fr));
-  gap: 10px;
-  padding: 14px;
-}
-.lane {
-  display: grid;
-  gap: 5px;
-  min-height: 88px;
-  border: 1px solid var(--line);
-  border-radius: 8px;
-  padding: 10px;
-  background: var(--surface-2);
-}
-.lane span, .lane small {
-  color: var(--muted);
-  overflow-wrap: anywhere;
-}
-.mermaid-fallback figcaption {
-  font-weight: 700;
-  color: var(--accent);
-  margin-bottom: 8px;
-}
-.risk-list {
-  display: grid;
-  gap: 8px;
-}
-.risk-item {
-  border-left: 3px solid var(--accent-2);
-  padding: 8px 10px;
-  background: var(--surface-2);
-  border-radius: 6px;
-}
-.empty {
-  color: var(--muted);
-  padding: 18px;
-}
-@media (max-width: 980px) {
-  .layout { grid-template-columns: 1fr; }
-  .sidebar {
-    position: static;
-    height: auto;
-    border-right: 0;
-    border-bottom: 1px solid var(--line);
-  }
-  .nav { grid-template-columns: repeat(4, minmax(0, 1fr)); }
-  .status-grid, .page-grid { grid-template-columns: 1fr; }
-  .drawer { position: static; max-height: none; }
-}
-@media (max-width: 620px) {
-  .topbar { display: block; }
-  .controls { justify-content: flex-start; }
-  .nav { grid-template-columns: repeat(2, minmax(0, 1fr)); }
-}