coding-agent-harness 1.0.2 → 1.0.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (219) hide show
  1. package/CHANGELOG.md +32 -0
  2. package/CONTRIBUTING.md +98 -0
  3. package/LICENSE +661 -21
  4. package/LICENSE-EXCEPTION.md +37 -0
  5. package/README.md +244 -87
  6. package/README.zh-CN.md +77 -35
  7. package/SKILL.md +32 -24
  8. package/docs-release/README.md +9 -5
  9. package/docs-release/architecture/overview.md +17 -5
  10. package/docs-release/architecture/overview.zh-CN.md +9 -5
  11. package/docs-release/architecture/system-explainer/01-system-overview.md +217 -0
  12. package/docs-release/architecture/system-explainer/02-module-dependency.md +257 -0
  13. package/docs-release/architecture/system-explainer/03-task-lifecycle.md +304 -0
  14. package/docs-release/architecture/system-explainer/04-check-and-governance.md +239 -0
  15. package/docs-release/architecture/system-explainer/05-data-flow.md +276 -0
  16. package/docs-release/architecture/system-explainer/06-preset-and-migration.md +303 -0
  17. package/docs-release/architecture/system-explainer/README.md +67 -0
  18. package/docs-release/architecture/system-explainer/en-US/01-system-overview.md +226 -0
  19. package/docs-release/architecture/system-explainer/en-US/02-module-dependency.md +263 -0
  20. package/docs-release/architecture/system-explainer/en-US/03-task-lifecycle.md +319 -0
  21. package/docs-release/architecture/system-explainer/en-US/04-check-and-governance.md +250 -0
  22. package/docs-release/architecture/system-explainer/en-US/05-data-flow.md +290 -0
  23. package/docs-release/architecture/system-explainer/en-US/06-preset-and-migration.md +323 -0
  24. package/docs-release/architecture/system-explainer/en-US/README.md +70 -0
  25. package/docs-release/assets/dashboard-overview.png +0 -0
  26. package/docs-release/guides/agent-installation.en-US.md +39 -15
  27. package/docs-release/guides/agent-installation.md +43 -16
  28. package/docs-release/guides/contributing.md +100 -0
  29. package/docs-release/guides/contributing.zh-CN.md +99 -0
  30. package/docs-release/guides/document-audience-and-surfaces.en-US.md +3 -2
  31. package/docs-release/guides/document-audience-and-surfaces.md +3 -2
  32. package/docs-release/guides/full-legacy-migration-subagent-strategy.md +2 -2
  33. package/docs-release/guides/full-legacy-migration-subagent-strategy.zh-CN.md +2 -2
  34. package/docs-release/guides/legacy-migration-agent-prompt.md +0 -11
  35. package/docs-release/guides/legacy-migration-agent-prompt.zh-CN.md +0 -11
  36. package/docs-release/guides/migration-playbook.en-US.md +14 -15
  37. package/docs-release/guides/migration-playbook.md +14 -15
  38. package/docs-release/guides/parent-control-repository-pattern.en-US.md +7 -5
  39. package/docs-release/guides/parent-control-repository-pattern.md +7 -5
  40. package/docs-release/guides/preset-development.md +238 -0
  41. package/docs-release/guides/repository-operating-models.en-US.md +5 -4
  42. package/docs-release/guides/repository-operating-models.md +5 -4
  43. package/docs-release/guides/task-state-machine.en-US.md +224 -0
  44. package/docs-release/guides/task-state-machine.md +231 -0
  45. package/docs-release/intl/en-US.md +1 -1
  46. package/docs-release/intl/zh-CN.md +1 -1
  47. package/examples/minimal-project/docs/09-PLANNING/TASKS/demo-task/INDEX.md +60 -0
  48. package/examples/minimal-project/docs/09-PLANNING/TASKS/demo-task/findings.md +7 -0
  49. package/package.json +10 -4
  50. package/presets/legacy-migration/checks/preset-check.mjs +3 -0
  51. package/presets/legacy-migration/preset.yaml +134 -0
  52. package/presets/legacy-migration/scripts/plan-work-queue.mjs +4 -0
  53. package/presets/legacy-migration/scripts/scaffold-task-contracts.mjs +4 -0
  54. package/presets/legacy-migration/templates/execution_strategy.append.md +18 -0
  55. package/presets/legacy-migration/templates/findings.seed.md +17 -0
  56. package/presets/legacy-migration/templates/review.seed.md +12 -0
  57. package/presets/legacy-migration/templates/task_plan.append.md +9 -0
  58. package/presets/legacy-migration/templates/visual_map.append.md +12 -0
  59. package/presets/legacy-migration/workbench/dashboard-panels.yaml +2 -0
  60. package/presets/legacy-migration/workbench/migration-queue.schema.json +23 -0
  61. package/presets/lesson-sedimentation/preset.yaml +23 -0
  62. package/presets/lesson-sedimentation/templates/prompt.md +23 -0
  63. package/presets/module/preset.yaml +25 -0
  64. package/presets/module/templates/execution_strategy.append.md +8 -0
  65. package/presets/module/templates/task_plan.append.md +17 -0
  66. package/presets/standard-task/preset.yaml +31 -0
  67. package/presets/standard-task/templates/task_plan.append.md +7 -0
  68. package/references/adversarial-review-standard.md +2 -2
  69. package/references/agents-md-pattern.md +2 -2
  70. package/references/delivery-operating-model-standard.md +3 -3
  71. package/references/docs-directory-standard.md +6 -7
  72. package/references/harness-ledger.md +53 -96
  73. package/references/lessons-governance.md +88 -93
  74. package/references/module-parallel-standard.md +14 -14
  75. package/references/planning-loop.md +12 -6
  76. package/references/pull-request-standard.md +118 -0
  77. package/references/repo-governance-standard.md +11 -2
  78. package/references/review-routing-standard.md +7 -1
  79. package/references/ssot-governance.md +67 -59
  80. package/references/taskr-gap-analysis.md +600 -0
  81. package/references/walkthrough-closeout.md +7 -7
  82. package/scripts/check-harness.mjs +40 -301
  83. package/scripts/commands/dashboard-command.mjs +67 -0
  84. package/scripts/commands/migration-command.mjs +126 -0
  85. package/scripts/commands/preset-command.mjs +73 -0
  86. package/scripts/commands/task-command.mjs +328 -0
  87. package/scripts/harness.mjs +59 -260
  88. package/scripts/lib/capability-registry.mjs +82 -28
  89. package/scripts/lib/check-module-parallel.mjs +230 -0
  90. package/scripts/lib/check-profiles.mjs +90 -228
  91. package/scripts/lib/check-task-contracts.mjs +55 -0
  92. package/scripts/lib/core-shared.mjs +65 -2
  93. package/scripts/lib/dashboard-data.mjs +155 -24
  94. package/scripts/lib/dashboard-workbench.mjs +131 -12
  95. package/scripts/lib/dashboard-writer.mjs +20 -4
  96. package/scripts/lib/git-status-summary.mjs +46 -0
  97. package/scripts/lib/governance-index-generator.mjs +174 -0
  98. package/scripts/lib/governance-sync.mjs +611 -0
  99. package/scripts/lib/governance-table-boundary.mjs +175 -0
  100. package/scripts/lib/harness-core.mjs +6 -0
  101. package/scripts/lib/lesson-maintenance.mjs +36 -29
  102. package/scripts/lib/markdown-utils.mjs +33 -0
  103. package/scripts/lib/migration-planner.mjs +4 -6
  104. package/scripts/lib/migration-support.mjs +1 -1
  105. package/scripts/lib/phase-kind.mjs +50 -0
  106. package/scripts/lib/preset-audit-contracts.mjs +37 -0
  107. package/scripts/lib/preset-engine.mjs +494 -0
  108. package/scripts/lib/preset-registry.mjs +776 -0
  109. package/scripts/lib/preset-resource-contracts.mjs +83 -0
  110. package/scripts/lib/review-confirm-git-gate.mjs +248 -0
  111. package/scripts/lib/status-builder.mjs +88 -0
  112. package/scripts/lib/status-dashboard-renderer.mjs +105 -0
  113. package/scripts/lib/subagent-authorization-audit.mjs +196 -0
  114. package/scripts/lib/task-audit-metadata.mjs +385 -0
  115. package/scripts/lib/task-audit-migration.mjs +350 -0
  116. package/scripts/lib/task-completion-consistency.mjs +26 -0
  117. package/scripts/lib/task-index.mjs +93 -0
  118. package/scripts/lib/task-lesson-candidates.mjs +242 -0
  119. package/scripts/lib/task-lesson-sedimentation.mjs +326 -0
  120. package/scripts/lib/task-lifecycle/create-task-helpers.mjs +67 -0
  121. package/scripts/lib/task-lifecycle/phase-sync.mjs +88 -0
  122. package/scripts/lib/task-lifecycle/review-confirm.mjs +112 -0
  123. package/scripts/lib/task-lifecycle/review-gates.mjs +73 -0
  124. package/scripts/lib/task-lifecycle/review-submission.mjs +63 -0
  125. package/scripts/lib/task-lifecycle/scaffold-provenance.mjs +49 -0
  126. package/scripts/lib/task-lifecycle/template-files.mjs +53 -0
  127. package/scripts/lib/task-lifecycle/text-utils.mjs +24 -0
  128. package/scripts/lib/task-lifecycle.mjs +338 -477
  129. package/scripts/lib/task-metadata.mjs +118 -0
  130. package/scripts/lib/task-review-model.mjs +455 -0
  131. package/scripts/lib/task-scanner.mjs +193 -372
  132. package/scripts/lib/task-tombstone-commands.mjs +140 -0
  133. package/scripts/postinstall.mjs +14 -0
  134. package/skills/preset-creator/SKILL.md +179 -0
  135. package/skills/preset-creator/references/complex-task-skeleton/README.md +31 -0
  136. package/skills/preset-creator/references/complex-task-skeleton/artifacts/INDEX.md +12 -0
  137. package/skills/preset-creator/references/complex-task-skeleton/brief.md +43 -0
  138. package/skills/preset-creator/references/complex-task-skeleton/execution_strategy.md +71 -0
  139. package/skills/preset-creator/references/complex-task-skeleton/findings.md +24 -0
  140. package/skills/preset-creator/references/complex-task-skeleton/lesson_candidates.md +70 -0
  141. package/skills/preset-creator/references/complex-task-skeleton/long-running-task-contract.md +76 -0
  142. package/skills/preset-creator/references/complex-task-skeleton/progress.md +33 -0
  143. package/skills/preset-creator/references/complex-task-skeleton/references/INDEX.md +13 -0
  144. package/skills/preset-creator/references/complex-task-skeleton/review.md +107 -0
  145. package/skills/preset-creator/references/complex-task-skeleton/task_plan.md +111 -0
  146. package/skills/preset-creator/references/complex-task-skeleton/visual_map.md +50 -0
  147. package/skills/preset-creator/references/preset-package-skeleton.md +296 -0
  148. package/templates/AGENTS.md.template +24 -18
  149. package/templates/dashboard/assets/app-src/00-state.js +13 -0
  150. package/templates/dashboard/assets/app-src/10-router.js +5 -1
  151. package/templates/dashboard/assets/app-src/20-overview.js +18 -8
  152. package/templates/dashboard/assets/app-src/30-tasks.js +92 -246
  153. package/templates/dashboard/assets/app-src/35-task-detail.js +286 -0
  154. package/templates/dashboard/assets/app-src/45-review.js +241 -22
  155. package/templates/dashboard/assets/app-src/50-migration.js +24 -10
  156. package/templates/dashboard/assets/app-src/55-presets.js +375 -0
  157. package/templates/dashboard/assets/app-src/60-shared.js +3 -1
  158. package/templates/dashboard/assets/app-src/90-bindings.js +302 -29
  159. package/templates/dashboard/assets/app.css +1501 -376
  160. package/templates/dashboard/assets/app.css.manifest.json +10 -0
  161. package/templates/dashboard/assets/app.js +1240 -101
  162. package/templates/dashboard/assets/app.manifest.json +2 -0
  163. package/templates/dashboard/assets/css-src/00-foundation.css +346 -0
  164. package/templates/dashboard/assets/css-src/10-panels-flow.css +236 -0
  165. package/templates/dashboard/assets/css-src/20-briefs-controls.css +398 -0
  166. package/templates/dashboard/assets/css-src/30-task-index.css +739 -0
  167. package/templates/dashboard/assets/css-src/35-review-workspace.css +507 -0
  168. package/templates/dashboard/assets/css-src/40-detail-modules-migration.css +489 -0
  169. package/templates/dashboard/assets/css-src/45-presets.css +516 -0
  170. package/templates/dashboard/assets/css-src/50-responsive-overrides.css +551 -0
  171. package/templates/dashboard/assets/i18n.js +263 -23
  172. package/templates/ledger/Harness-Ledger.md +13 -25
  173. package/templates/lessons/lesson-arch-process-change.md +1 -1
  174. package/templates/lessons/lesson-new-doc.md +1 -1
  175. package/templates/lessons/lesson-ref-change.md +1 -1
  176. package/templates/planning/INDEX.md +87 -0
  177. package/templates/planning/brief.md +1 -1
  178. package/templates/planning/execution_strategy.md +31 -0
  179. package/templates/planning/lesson_candidates.md +18 -6
  180. package/templates/planning/module_session_prompt.md +1 -0
  181. package/templates/planning/optional/artifacts/INDEX.md +3 -3
  182. package/templates/planning/optional/references/INDEX.md +3 -3
  183. package/templates/planning/review.md +41 -0
  184. package/templates/planning/task_plan.md +5 -21
  185. package/templates/planning/visual_map.md +13 -9
  186. package/templates/planning/visual_map.simple.md +52 -0
  187. package/templates/reference/execution-workflow-standard.md +31 -3
  188. package/templates/reference/pull-request-standard.md +80 -0
  189. package/templates/reference/repo-governance-standard.md +7 -6
  190. package/templates/reference/review-routing-standard.md +6 -0
  191. package/templates/reference/walkthrough-standard.md +2 -1
  192. package/templates/verifier/verifier-output.md +1 -1
  193. package/templates-zh-CN/AGENTS.md.template +25 -19
  194. package/templates-zh-CN/ledger/Harness-Ledger.md +17 -40
  195. package/templates-zh-CN/planning/INDEX.md +87 -0
  196. package/templates-zh-CN/planning/brief.md +1 -1
  197. package/templates-zh-CN/planning/execution_strategy.md +30 -0
  198. package/templates-zh-CN/planning/lesson_candidates.md +18 -6
  199. package/templates-zh-CN/planning/module_session_prompt.md +1 -0
  200. package/templates-zh-CN/planning/review.md +41 -1
  201. package/templates-zh-CN/planning/task_plan.md +4 -44
  202. package/templates-zh-CN/planning/visual_map.md +14 -7
  203. package/templates-zh-CN/planning/visual_map.simple.md +48 -0
  204. package/templates-zh-CN/reference/adversarial-review-standard.md +1 -1
  205. package/templates-zh-CN/reference/docs-library-standard.md +1 -1
  206. package/templates-zh-CN/reference/execution-workflow-standard.md +33 -7
  207. package/templates-zh-CN/reference/harness-ledger-standard.md +2 -2
  208. package/templates-zh-CN/reference/pull-request-standard.md +106 -0
  209. package/templates-zh-CN/reference/repo-governance-standard.md +4 -3
  210. package/templates-zh-CN/reference/review-routing-standard.md +8 -1
  211. package/templates-zh-CN/reference/walkthrough-standard.md +3 -2
  212. package/templates-zh-CN/walkthrough/Closeout-SSoT.md +1 -1
  213. package/docs-release/assets/dashboard-overview-en.png +0 -0
  214. package/scripts/smoke-dashboard.mjs +0 -92
  215. package/scripts/test-harness.mjs +0 -1395
  216. package/templates/ssot/Feature-SSoT.md +0 -43
  217. package/templates/ssot/Lessons-SSoT.md +0 -44
  218. package/templates-zh-CN/ssot/Feature-SSoT.md +0 -49
  219. package/templates-zh-CN/ssot/Lessons-SSoT.md +0 -49
@@ -98,17 +98,6 @@ harness migrate-verify /tmp/cah-migration-project/session.json
98
98
 
99
99
  如果后续继续清理 warning 或补活跃任务合同,第一次 session 只能作为 baseline。最终交付前要重新运行 `migrate-run` 生成新 session/dashboard,或者明确列出 baseline session 与最终检查证据的差异。
100
100
 
101
- 4. 用 session 创建 Complex Task preset:
102
-
103
- ```bash
104
- harness new-task \
105
- --budget complex \
106
- --preset legacy-migration \
107
- --from-session /tmp/cah-migration-project/session.json
108
- ```
109
-
110
- 这一步只创建任务骨架和 `evidence/<timestamp>/` 证据包,不会继续运行迁移、改写历史任务、stage 或 commit。生成的任务会写入 `Task Kind`、`Task Preset`、`Preset Version`、`Migration Target Level`、`Migration Achieved Level` 和 `Evidence Bundle`,后续 agent 应在这个 Complex Task 里推进迁移,而不是另起一套流程。
111
-
112
101
  `migrate-verify` 通过不等于 full migration complete。完整迁移还必须满足:
113
102
 
114
103
  - `migrate-plan` 是 `declared-capability`。
@@ -119,7 +108,7 @@ harness new-task \
119
108
  - 任务索引页面能打开并显示全量任务。
120
109
  - 至少一轮 subagent 对抗审查 PASS。
121
110
 
122
- 5. 按计划继续人工/agent 清理:
111
+ 4. 按计划继续人工/agent 清理:
123
112
 
124
113
  - `MP-01`:确认兼容层和 locale,保证历史文档没有被覆盖。
125
114
  - `MP-02`:选择 capability,只声明项目事实已经支持的能力。
@@ -128,14 +117,14 @@ harness new-task \
128
117
  - `MP-05`:升级当前 release/architecture/security/data review,不重写所有历史 review。
129
118
  - `MP-06`:普通检查 warning 都有 owner/action/status 后,再使用 strict 作为门禁。
130
119
 
131
- 6. 普通迁移验证:
120
+ 5. 普通迁移验证:
132
121
 
133
122
  ```bash
134
123
  harness check --profile target-project /path/to/project
135
124
  harness dashboard --out-dir /tmp/harness-dashboard /path/to/project
136
125
  ```
137
126
 
138
- 7. 严格切换验证:
127
+ 6. 严格切换验证:
139
128
 
140
129
  ```bash
141
130
  harness check --profile target-project --strict /path/to/project
@@ -175,6 +164,16 @@ Baseline 模式下,只有 `current-active` 或 “仍被 SSoT 引用为当前
175
164
 
176
165
  Status-aware rewrite 模式下,已有 `brief.md`、`execution_strategy.md`、`visual_map.md` 不是自动保留;如果证据显示它们只是旧模板、解析残留、语言错误或不能让人判断当前状态,就重写。历史任务可以只写可读索引卡或 residual,但这个判断必须有证据。
177
166
 
167
+ 全局表和模块索引迁移不是人工重填。新版本只把任务生命周期汇总生成到 `Harness-Ledger.md`;旧的 `Feature-SSoT.md` 和 `Private-Feature-SSoT.md` 是 legacy 生命周期投影,切换时应先归档,不再重建。模块 `module_plan.md` 的 Steps 表和模块 `visual_map.md` 的拓扑表仍由模块任务文件生成。人看当前状态应优先看 Dashboard,Agent 需要快速定位时用 `task-list` / `task-index` 查询。旧项目切换前,先把旧生命周期表归档,再用生成器从任务文件重建当前索引:
168
+
169
+ ```bash
170
+ harness governance rebuild --dry-run --archive /path/to/project
171
+ harness governance rebuild --archive --apply /path/to/project
172
+ harness task-list --json --search "keyword" /path/to/project
173
+ ```
174
+
175
+ 归档目录会保留旧生命周期表快照。确认 Dashboard、`task-list` / `task-index` 查询和新生成 Ledger 都能反映当前任务后,再由项目 owner 决定是否删除旧归档;迁移 agent 不应直接删除历史表证据。Delivery、Regression、Cadence、Closeout、Module Registry 等非任务生命周期治理表不是本步骤的删除对象,除非后续版本提供等价 scanner 和生成器。
176
+
178
177
  Full semantic rewrite 模式下,所有任务都需要 standalone `brief.md`,但不能写空模板。历史任务的 brief 应该是“可读索引卡”:说明任务目标、第一眼应该看什么、证据来自哪里、状态判断和 residual。`visual_map.md` 是图表集合,不是路线图模板;只画能提高理解速度的 phase flow、sequence、architecture、data-flow、state、topology 或 decision map,不能为了过检查生成空图。
179
178
 
180
179
  如果旧项目属于微服务、多仓、前后端分仓或依赖外部系统,迁移计划还必须询问用户是否有外部资料。不要把外部团队给的几十份文档直接迁入 `03/04/06`。先按 `external-source-intake-standard.md` 建立 `docs/04-DEVELOPMENT/external-source-packs/<source-key>/`,完成 source index 和 digest,再把稳定事实投影到 service profile、external context 和 integration contract。
@@ -286,7 +285,7 @@ Full cutover 的 dashboard smoke 必须验证:
286
285
  | --- | --- | --- |
287
286
  | Task Contract Worker | `docs/09-PLANNING/TASKS/**/brief.md`、`execution_strategy.md`、`visual_map.md`、同任务 `progress.md` 追加 | 清掉 task contract 缺口;在已确认 rewrite 模式下重写薄弱旧表面。 |
288
287
  | Review/Capability Worker | `.harness-capabilities.json`、当前 strict review 文件 | 声明真实 capability,修 release-blocking review schema。 |
289
- | Legacy Governance Worker | `AGENTS.md`、PR template、`docs/11-REFERENCE/**`、Ledger、Closeout SSoT、Lessons SSoT、walkthrough template | 清掉 legacy checker 聚合错误。 |
288
+ | Legacy Governance Worker | `AGENTS.md`、PR template、`docs/11-REFERENCE/**`、Ledger、Closeout SSoT、lesson candidates/detail docs、walkthrough template | 清掉 legacy checker 聚合错误。 |
290
289
  | Brief Coverage Workers | 按日期段或模块划分,写缺失或被点名薄弱的 `brief.md` | 把 dashboard brief coverage 变成 100%,并移除空模板。 |
291
290
  | Quality Repair Worker | 只写 reviewer 点名的问题文件 | 修掉自动解析痕迹、空模板、语言不一致和证据薄弱。 |
292
291
 
@@ -16,7 +16,7 @@ Multi-repo projects often run into these failures:
16
16
 
17
17
  - Frontend, backend, SDK, and services each have their own plans, and no one can tell where the global release is blocked.
18
18
  - An agent starts inside a child repository, reads only local `AGENTS.md`, and misses cross-repo architecture constraints.
19
- - Each repository maintains its own Feature SSoT, and the states conflict.
19
+ - Each repository maintains its own handwritten task lifecycle table, and the states conflict.
20
20
  - Review evidence, test evidence, and walkthroughs are scattered across repositories, making it hard to prove that a cross-repo task is complete.
21
21
 
22
22
  The parent-control pattern solves a control-plane problem. It does not force code back into a monorepo. It moves the harness source of truth into one place.
@@ -62,7 +62,8 @@ It should contain:
62
62
  - `docs/03-ARCHITECTURE/repository-topology.md`: repository topology, owners, boundaries, dependency direction.
63
63
  - `docs/04-DEVELOPMENT/local-development.md`: cross-repo local startup, integration workflow, dependency setup.
64
64
  - `docs/06-INTEGRATIONS/`: cross-service APIs, events, SDKs, databases, permissions, and external contracts.
65
- - `docs/09-PLANNING/Feature-SSoT.md`: global feature and release state.
65
+ - `docs/Harness-Ledger.md`: generated global task lifecycle index from task files.
66
+ - `docs/09-PLANNING/Delivery-SSoT.md`: cross-repo feature blocks, dependencies, and release orchestration.
66
67
  - `docs/09-PLANNING/TASKS/`: cross-repo task contracts.
67
68
  - `docs/05-TEST-QA/Regression-SSoT.md`: cross-repo regression gates.
68
69
  - `docs/05-TEST-QA/Cadence-Ledger.md`: which changes trigger which checks.
@@ -94,7 +95,7 @@ They should contain:
94
95
  - Repository-local reviews or pull requests.
95
96
  - Repository-local test evidence.
96
97
 
97
- Child repositories should not independently maintain the global Feature SSoT, and they should not decide whether a cross-repo release is complete.
98
+ Child repositories should not independently maintain global task lifecycle tables, and they should not decide whether a cross-repo release is complete.
98
99
 
99
100
  A child repository `AGENTS.md` can be short:
100
101
 
@@ -228,7 +229,7 @@ The agent does not need to read all docs in 100 repositories at startup. It read
228
229
 
229
230
  Avoid:
230
231
 
231
- - Each child repository maintaining its own global Feature SSoT.
232
+ - Each child repository maintaining its own global task lifecycle table.
232
233
  - A parent repository with only a README and no task, regression, or closeout surface.
233
234
  - Child `AGENTS.md` files copying large sections from the parent, causing drift.
234
235
  - Starting cross-repo tasks from a child repository and backfilling parent records at the end.
@@ -241,7 +242,8 @@ To adopt the parent-control model, start with:
241
242
 
242
243
  - Parent `AGENTS.md` states that this is the control repository.
243
244
  - `docs/03-ARCHITECTURE/repository-topology.md` lists all child repositories.
244
- - `docs/09-PLANNING/Feature-SSoT.md` is the global feature source of truth.
245
+ - `docs/Harness-Ledger.md` is generated from task files as the global task lifecycle index.
246
+ - `docs/09-PLANNING/Delivery-SSoT.md` is maintained only when cross-repo release or block orchestration is needed.
245
247
  - `docs/05-TEST-QA/Regression-SSoT.md` defines local, contract, integration, and release gates.
246
248
  - Each child repository has only a short local `AGENTS.md`.
247
249
  - New cross-repo tasks are created only in the parent repository.
@@ -16,7 +16,7 @@ English mirror: `docs-release/guides/parent-control-repository-pattern.en-US.md`
16
16
 
17
17
  - 前端、后端、SDK、微服务各有自己的计划,没人知道全局 release 到底卡在哪里。
18
18
  - Agent 从某个子仓库启动,只看到局部 `AGENTS.md`,忽略了跨仓架构约束。
19
- - 每个仓库各自维护 Feature SSoT,状态互相冲突。
19
+ - 每个仓库各自维护手写任务生命周期表,状态互相冲突。
20
20
  - Review 证据、测试证据、walkthrough 分散在不同仓库,最后无法证明一个跨仓任务真正完成。
21
21
 
22
22
  主控仓库模式解决的是控制面问题。它不是要求把代码放回单仓,而是把 Harness 的事实源收回一个地方。
@@ -62,7 +62,8 @@ product-control-repo/
62
62
  - `docs/03-ARCHITECTURE/repository-topology.md`:仓库拓扑、owner、边界、依赖方向。
63
63
  - `docs/04-DEVELOPMENT/local-development.md`:跨仓本地启动、联调、依赖安装。
64
64
  - `docs/06-INTEGRATIONS/`:跨服务 API、事件、SDK、数据库、权限、外部系统契约。
65
- - `docs/09-PLANNING/Feature-SSoT.md`:全局 feature 和 release 状态。
65
+ - `docs/Harness-Ledger.md`:由任务文件生成的全局任务生命周期索引。
66
+ - `docs/09-PLANNING/Delivery-SSoT.md`:跨仓 feature block、依赖和 release 编排。
66
67
  - `docs/09-PLANNING/TASKS/`:跨仓任务合同。
67
68
  - `docs/05-TEST-QA/Regression-SSoT.md`:跨仓 regression gates。
68
69
  - `docs/05-TEST-QA/Cadence-Ledger.md`:哪些变更触发哪些检查。
@@ -94,7 +95,7 @@ node tools/check-harness.mjs
94
95
  - 本仓库局部 review 或 PR。
95
96
  - 本仓库局部测试证据。
96
97
 
97
- 子仓库不应该单独维护全局 Feature SSoT,也不应该自己决定跨仓 release 是否完成。
98
+ 子仓库不应该单独维护全局任务生命周期表,也不应该自己决定跨仓 release 是否完成。
98
99
 
99
100
  一个子仓库 `AGENTS.md` 可以很短:
100
101
 
@@ -228,7 +229,7 @@ Agent 不需要在启动时读 100 个仓库的所有文档。它先读父任务
228
229
 
229
230
  避免这些做法:
230
231
 
231
- - 每个子仓库各自维护全局 Feature SSoT。
232
+ - 每个子仓库各自维护全局任务生命周期表。
232
233
  - 父仓库只有 README,没有任务、回归和 closeout。
233
234
  - 子仓库 `AGENTS.md` 复制父仓库大段内容,导致漂移。
234
235
  - 跨仓任务从子仓库启动,最后再补父仓库记录。
@@ -241,7 +242,8 @@ Agent 不需要在启动时读 100 个仓库的所有文档。它先读父任务
241
242
 
242
243
  - 父仓库 `AGENTS.md` 写清楚它是 control repo。
243
244
  - `docs/03-ARCHITECTURE/repository-topology.md` 列出所有子仓库。
244
- - `docs/09-PLANNING/Feature-SSoT.md` 成为全局 feature source of truth。
245
+ - `docs/Harness-Ledger.md` 由任务文件生成全局任务生命周期索引。
246
+ - `docs/09-PLANNING/Delivery-SSoT.md` 只在需要跨仓 release / block 编排时维护。
245
247
  - `docs/05-TEST-QA/Regression-SSoT.md` 定义局部、契约、集成、发布 gate。
246
248
  - 每个子仓库只有短的局部 `AGENTS.md`。
247
249
  - 新跨仓任务只在父仓库创建。
@@ -0,0 +1,238 @@
1
+ # Preset Development
2
+
3
+ Harness presets are declarative task method packages. A preset can add task metadata, render Markdown templates, require CLI inputs, generate evidence files, and pre-load shared reference bundles without writing JavaScript.
4
+
5
+ Use a preset when multiple tasks should start from the same method, evidence contract, or shared context. Do not create a preset for one-off prose. Good presets encode repeatable task behavior: required inputs, task kind, review/evidence expectations, shared references, and a small amount of task-plan guidance that tells the next agent what to read first.
6
+
7
+ `preset.yaml` uses the Harness manifest subset: nested mappings, scalar strings/numbers/booleans, and inline arrays such as `[standard, complex]`. Do not use block strings or dash-list YAML forms in preset manifests.
8
+
9
+ ## Install Location
10
+
11
+ Project presets live in:
12
+
13
+ ```text
14
+ <target>/.coding-agent-harness/presets/<preset-id>/
15
+ ```
16
+
17
+ User-installed presets live in:
18
+
19
+ ```text
20
+ ~/.coding-agent-harness/presets/<preset-id>/
21
+ ```
22
+
23
+ When a target is supplied, Harness discovers project presets first, then user presets, then bundled presets under the package `presets/` directory. Use project presets when a repository needs to override or pin a task method. Use user presets for personal reusable methods across repositories.
24
+
25
+ Bundled presets are not only fallback files. `npm install -g coding-agent-harness`
26
+ and `harness install-user` seed them into the user preset root, while
27
+ `harness init` seeds them into the project preset root. Re-run
28
+ `harness preset seed` for the user root or `harness preset seed --project <target>`
29
+ for the project root when a preset root is missing or incomplete.
30
+
31
+ ## Dashboard Management
32
+
33
+ The Dashboard exposes a Presets view for the target project. Static dashboards
34
+ show a read-only catalog of discovered project, user, and bundled presets,
35
+ including source, purpose, compatible budgets, task kind, manifest path, and
36
+ resource counts.
37
+
38
+ Use the local dynamic Workbench when you want to manage presets from the web UI:
39
+
40
+ ```bash
41
+ harness dev /path/to/project
42
+ ```
43
+
44
+ In Workbench mode, the Presets view can check presets, install a local preset
45
+ directory, `.zip` archive, or bundled preset id into the project or user scope,
46
+ seed bundled presets into either scope, and uninstall project/user presets.
47
+ Bundled package presets are immutable from the Dashboard: they can be inspected,
48
+ checked, and used as install or seed sources, but not edited or deleted.
49
+
50
+ The CLI and filesystem remain canonical. The Dashboard calls the same preset
51
+ registry operations as `harness preset ...`; it does not store independent preset
52
+ state.
53
+
54
+ ## Package Layout
55
+
56
+ ```text
57
+ my-preset/
58
+ preset.yaml
59
+ templates/
60
+ task_plan.append.md
61
+ references/
62
+ upstream-contract.md
63
+ resources/
64
+ service-runbook.md
65
+ ```
66
+
67
+ ## Minimal Manifest
68
+
69
+ ```yaml
70
+ id: custom-review
71
+ version: 1
72
+ purpose: Create a review task with preset evidence.
73
+ compatibleBudgets: [standard, complex]
74
+ localeSupport: [en-US, zh-CN]
75
+ task:
76
+ kind: review-task
77
+ defaultTaskId: custom-review-task
78
+ entrypoints:
79
+ newTask:
80
+ type: template
81
+ writes: [docs/09-PLANNING/TASKS/**]
82
+ audit: true
83
+ templates:
84
+ taskPlanAppend: templates/task_plan.append.md
85
+ inputs:
86
+ subject:
87
+ type: text
88
+ flag: --subject
89
+ required: true
90
+ templateValues:
91
+ subject:
92
+ from: inputs.subject
93
+ metadata:
94
+ ReviewSubject:
95
+ label: Review Subject
96
+ from: inputs.subject
97
+ evidence:
98
+ bundleDir: artifacts/preset
99
+ files:
100
+ subject:
101
+ path: subject.txt
102
+ type: text
103
+ value: inputs.subject
104
+ audit:
105
+ manifestRequired: true
106
+ evidenceFiles: [preset-audit.json, preset-manifest.json, write-scope.json]
107
+ writeScopes:
108
+ taskDocs:
109
+ path: docs/09-PLANNING/TASKS/**
110
+ access: write
111
+ ```
112
+
113
+ ## Reference Bundles
114
+
115
+ Use `resources.references` when a family of tasks shares the same outside context, such as another microservice, API contract, migration packet, reviewer input, or local verification runbook. Harness copies or renders these files into each created task directory, appends `references/INDEX.md` rows, and can add a required-read section to `task_plan.md`.
116
+
117
+ ```yaml
118
+ resources:
119
+ references:
120
+ upstreamContract:
121
+ path: references/upstream-contract.md
122
+ template: templates/references/upstream-contract.md
123
+ index:
124
+ id: REF-001
125
+ type: code
126
+ summary: Shared upstream {{service}} contract for every task created by this preset.
127
+ usedBy: coordinator,worker,reviewer
128
+ serviceRunbook:
129
+ path: references/service-runbook.md
130
+ source: resources/service-runbook.md
131
+ index:
132
+ id: REF-002
133
+ type: runbook
134
+ summary: Local verification notes for the shared upstream service.
135
+ usedBy: worker
136
+ context:
137
+ requiredReads: [REF-001, REF-002]
138
+ ```
139
+
140
+ Use `template` when the file needs `{{valueName}}` substitution. Use `source` when the file should be copied as static Markdown. `path`, `source`, and `template` must stay inside the preset package and generated task directory boundaries.
141
+
142
+ ## Artifact Bundles
143
+
144
+ Use `resources.artifacts` for preset-provided fixtures, generated input packets, or review material that supports the task but is not a reference source of truth. Harness writes these files into the task's `artifacts/` area and appends `artifacts/INDEX.md`.
145
+
146
+ ```yaml
147
+ resources:
148
+ artifacts:
149
+ inputPacket:
150
+ path: artifacts/input-packet.md
151
+ source: resources/artifacts/input-packet.md
152
+ index:
153
+ id: ART-001
154
+ type: fixture
155
+ summary: Shared fixture packet copied by the preset.
156
+ producedBy: preset
157
+ ```
158
+
159
+ ## Template Rendering
160
+
161
+ Templates use `{{valueName}}` placeholders from `templateValues`. `templateValues` and `metadata` support literal `value`, `default`, and dot-path `from` references such as `inputs.subject` or `task.title`; they do not evaluate arbitrary expressions.
162
+
163
+ `metadata` entries render first-class task plan lines such as `Review Subject: API contracts`.
164
+
165
+ ```md
166
+ ## Custom Review
167
+
168
+ Subject: {{subject}}
169
+ ```
170
+
171
+ ## Inputs
172
+
173
+ Supported input types:
174
+
175
+ | Type | Use |
176
+ | --- | --- |
177
+ | `text` | Reads a CLI flag value such as `--subject "API"` |
178
+ | `flag` | Reads a boolean CLI flag |
179
+ | `json-file` | Reads and validates a JSON file such as `--from-session session.json` |
180
+
181
+ `json-file` inputs can validate `validateOperation`, reject `planOnly`, require a target path, and route the task target from the JSON session.
182
+
183
+ ## Evidence
184
+
185
+ Evidence files are written under the task directory and must match `writeScopes`.
186
+
187
+ Supported evidence types:
188
+
189
+ | Type | Output |
190
+ | --- | --- |
191
+ | `text` | Plain text from a value path |
192
+ | `json` | JSON from a value path |
193
+ | `input-json` | Raw resolved JSON input |
194
+ | `preset-audit` | Manifest audit payload |
195
+ | `preset-manifest` | Manifest snapshot |
196
+ | `write-scope` | Declared write scopes |
197
+ | `migration-verify` | Built-in migrate session verification |
198
+ | `migration-ledger` | Built-in migration phase ledger |
199
+ | `dashboard-hash` | Hash of the migration dashboard snapshot |
200
+ | `target-git-status` | Target Git status from migration session |
201
+ | `target-commit` | Current target commit |
202
+ | `harness-version` | Current package version |
203
+ | `generated-at` | Generation timestamp |
204
+
205
+ ## Commands
206
+
207
+ ```bash
208
+ harness preset check ./my-preset
209
+ harness preset install ./my-preset
210
+ harness preset install ./my-preset.zip
211
+ harness preset install ./my-preset --project /path/to/project
212
+ harness preset install legacy-migration --force
213
+ harness preset seed
214
+ harness preset seed --project /path/to/project
215
+ harness preset list --json /path/to/project
216
+ harness preset inspect custom-review --json /path/to/project
217
+ harness new-task --title "Custom review task" --preset custom-review --subject "API contracts" /path/to/project
218
+ harness preset uninstall custom-review
219
+ ```
220
+
221
+ ## Validation Method
222
+
223
+ For every preset, prove both the manifest and downstream task behavior:
224
+
225
+ 1. Run `harness preset check ./my-preset`.
226
+ 2. Install the folder and, if distributing an archive, install the `.zip` into an isolated HOME or disposable environment.
227
+ 3. Create at least one task with `harness new-task --preset`.
228
+ 4. For reference bundles, create two different tasks from the same preset and verify both contain the same shared `references/` files and independent audit/evidence bundles.
229
+ 5. Run `harness status --json`, `harness task-index --json`, and `harness check --profile target-project <target>`.
230
+ 6. Inspect `task_plan.md` to confirm required reads are visible before implementation starts.
231
+
232
+ ## Boundaries
233
+
234
+ - Presets cannot write outside declared `writeScopes`.
235
+ - Presets do not run arbitrary JavaScript during `new-task`.
236
+ - Reference bundles are task-local snapshots. If the shared upstream context changes later, create a new preset version or a follow-up task rather than silently mutating historical tasks.
237
+ - Script and check entrypoints may exist in bundled packages, but the task creation path is YAML + templates + built-in processors.
238
+ - Use a new built-in processor only when multiple presets need the same capability and the behavior can be tested centrally.
@@ -92,7 +92,7 @@ Each repository should document its external boundary in:
92
92
 
93
93
  The risk is harness fragmentation:
94
94
 
95
- - The frontend Feature SSoT says a task is complete while the backend Regression SSoT is still red.
95
+ - The frontend local task state says a task is complete while the backend Regression SSoT is still red.
96
96
  - An SDK breaking change is not projected into the product shell.
97
97
  - An agent starts from a child repository, sees only local facts, and incorrectly treats the global task as complete.
98
98
 
@@ -124,7 +124,8 @@ product-control-repo/
124
124
  The parent repository is the control plane. It owns:
125
125
 
126
126
  - Overall architecture and repo topology.
127
- - Cross-repo Feature SSoT.
127
+ - Cross-repo task lifecycle Ledger.
128
+ - Delivery SSoT when release or block orchestration is needed.
128
129
  - Task plans, reviews, and walkthroughs.
129
130
  - Regression SSoT and cross-repo cadence.
130
131
  - Agent entrypoint and reading matrix.
@@ -152,7 +153,7 @@ The parent-control model fixes global truth in one place. Even if there are 100
152
153
 
153
154
  This avoids:
154
155
 
155
- - Conflicting Feature SSoTs.
156
+ - Conflicting handwritten task lifecycle tables.
156
157
  - Each child repo saying "done" while the release still cannot ship.
157
158
  - Agents starting from the wrong repository and seeing only local context.
158
159
  - Cross-repo review and regression evidence scattered across many places.
@@ -179,7 +180,7 @@ If cross-repo features remain common, create a parent-control repository.
179
180
  Migration order:
180
181
 
181
182
  1. Create the parent `AGENTS.md` and repo topology.
182
- 2. Move global Feature SSoT, Regression SSoT, and walkthrough index into the parent repository.
183
+ 2. Move global Harness Ledger, Delivery SSoT, Regression SSoT, and walkthrough index into the parent repository.
183
184
  3. Keep local `AGENTS.md` files in child repositories, but point global planning back to the parent.
184
185
  4. Create new cross-repo tasks only in the parent repository.
185
186
  5. Treat child repository commits as evidence for parent tasks.
@@ -92,7 +92,7 @@ sdk-repo/
92
92
 
93
93
  多仓独立模式的风险是 Harness 分裂:
94
94
 
95
- - 前端 Feature SSoT 认为任务完成,后端 Regression SSoT 仍是红灯。
95
+ - 前端局部任务状态认为任务完成,后端 Regression SSoT 仍是红灯。
96
96
  - SDK 的 breaking change 没有投影到产品 shell。
97
97
  - Agent 从子仓库启动后,只看到局部事实,误以为全局任务已经结束。
98
98
 
@@ -124,7 +124,8 @@ product-control-repo/
124
124
  父仓库是 control plane。它管理:
125
125
 
126
126
  - 总体架构和 repo topology。
127
- - 跨仓 Feature SSoT
127
+ - 跨仓任务生命周期 Ledger
128
+ - Delivery SSoT(需要 release / block 编排时)。
128
129
  - 任务计划、review、walkthrough。
129
130
  - Regression SSoT 和跨仓 cadence。
130
131
  - Agent 启动入口和读文件矩阵。
@@ -152,7 +153,7 @@ product-control-repo/
152
153
 
153
154
  这能避免:
154
155
 
155
- - 多个 Feature SSoT 互相冲突。
156
+ - 多个手写任务生命周期表互相冲突。
156
157
  - 每个子仓库都声称自己已经完成,但 release 仍不能发。
157
158
  - Agent 从错误仓库启动,只看到局部上下文。
158
159
  - 跨仓 review 和 regression 证据散落在不同地方。
@@ -179,7 +180,7 @@ product-control-repo/
179
180
  迁移顺序:
180
181
 
181
182
  1. 创建父仓库 `AGENTS.md` 和 repo topology。
182
- 2. 把全局 Feature SSoT、Regression SSoT、walkthrough index 收到父仓库。
183
+ 2. 把全局 Harness Ledger、Delivery SSoT、Regression SSoT、walkthrough index 收到父仓库。
183
184
  3. 子仓库保留局部 `AGENTS.md`,但把全局计划指向父仓库。
184
185
  4. 新跨仓任务只在父仓库创建 task。
185
186
  5. 子仓库提交只作为父任务的 evidence。