coding-agent-harness 1.0.0

package/templates/ssot/Module-Registry.md

@@ -0,0 +1,43 @@
+# Module Registry
+
+## Purpose
+
+Track module ownership, write scope, branch or worktree assignment, and coordinator sync state for parallel agent work.
+
+## Status Legend
+
+| Status | Meaning | Required Next Step |
+| --- | --- | --- |
+| unassigned | Module exists but has no active owner. | Assign owner before work starts. |
+| reserved | Owner and scope are assigned. | Open worktree or begin planning. |
+| active | Module work is in progress. | Keep branch, plan, and blockers current. |
+| handoff | Worker has produced a reviewable result. | Coordinator reviews and integrates. |
+| merged | Module changes are integrated. | Link merge evidence and close residuals. |
+| blocked | Module cannot proceed. | Record blocker owner and unblock condition. |
+| archived | Module assignment is historical. | Keep archive pointer if needed. |
+
+## Active Modules
+
+| ID | Module | Path Scope | Owner | Status | Branch or Worktree | Task Plan | Shared Files | Depends On | Handoff Evidence | Residual | Updated |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| M-000 | Module title | src/module/** or docs/area/** | owner | reserved | branch or worktree path | docs/09-PLANNING/TASKS/.../task_plan.md | none | none | pending | none | YYYY-MM-DD |
+
+## Shared-File Register
+
+| File | Current Owner | Coordination Rule | Active Consumers | Last Sync |
+| --- | --- | --- | --- | --- |
+| path/to/shared-file | coordinator | only coordinator edits, workers propose patches | M-000, M-001 | YYYY-MM-DD |
+
+## Routing Rules
+
+1. Define module path scope before assigning a worker.
+2. Workers must not edit outside their assigned scope without coordinator approval.
+3. Shared files need an explicit owner and sync rule before parallel work starts.
+4. Move a module to `handoff` only when the worker provides evidence, residuals, and integration notes.
+5. The coordinator owns final merge, shared-file reconciliation, and Delivery SSoT updates.
+
+## Archive Rules
+
+- Keep active, blocked, and handoff rows visible until integration completes.
+- Archive merged module rows after the delivery or release closeout is stable.
+- Preserve branch, worktree, task plan, and handoff evidence in the archive row.

package/templates/ssot/Regression-SSoT.md

@@ -0,0 +1,51 @@
+# Regression SSoT
+
+## Purpose
+
+Define the project regression gates and record their current evidence state. This file decides which checks are required before a feature, delivery, or release can close.
+
+## Status Legend
+
+| Status | Meaning | Required Next Step |
+| --- | --- | --- |
+| draft | Gate is proposed but not enforced. | Define scope, command, owner, and pass criteria. |
+| active | Gate is required for matching changes. | Run on cadence or when triggered. |
+| failing | Latest required run failed. | Assign fix owner and block affected closeout. |
+| waived | Gate is skipped for a specific reason. | Record approver, expiry, and compensating evidence. |
+| retired | Gate is no longer valid. | Link replacement or retirement rationale. |
+| archived | Gate is historical. | Preserve final state and replacement pointer. |
+
+## Regression Gates
+
+| ID | Gate | Applies To | Owner | Status | Command or Procedure | Evidence Depth | Pass Criteria | Latest Evidence | Blocks Closeout | Updated |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| RG-000 | Gate title | feature, module, route, API, release | owner | active | command or manual procedure | E1/E2/E3 | objective pass condition | path, log, screenshot, or CI run | yes | YYYY-MM-DD |
+
+## Evidence Depth
+
+| Level | Meaning | Examples |
+| --- | --- | --- |
+| E0 | Declared only; not acceptable for closeout. | "Not run", unchecked assumption. |
+| E1 | Static or local check. | Typecheck, lint, unit test, parser check. |
+| E2 | Runtime behavior check. | Browser smoke, API probe, integration test, CLI dry run. |
+| E3 | End-to-end or production-like check. | Full workflow, deployed environment, real data with redaction. |
+
+## Waivers
+
+| Gate | Scope | Reason | Approver | Compensating Evidence | Expires |
+| --- | --- | --- | --- | --- | --- |
+| RG-000 | feature, PR, or release | reason | owner | alternate command or review | YYYY-MM-DD |
+
+## Routing Rules
+
+1. Every active gate must have an owner, trigger scope, and pass criteria.
+2. Any feature or delivery closeout must cite the gates it ran or the waiver that covers the gap.
+3. Mark a gate `failing` when the latest required run fails, even if the failure is believed unrelated.
+4. Waivers must be narrow, dated, and paired with compensating evidence.
+5. Retire a gate only after its replacement or rationale is recorded.
+
+## Archive Rules
+
+- Keep active, failing, and waived gates in this file.
+- Move retired gates to the archive after consumers have been updated.
+- Preserve old gate IDs when archiving so historical walkthroughs remain traceable.

package/templates/verifier/verifier-output.md

@@ -0,0 +1,43 @@
+# Verifier Output
+
+## Verifier Metadata
+
+- template_id: harness-verifier/v1
+- verifier: agent, tool, or human name
+- target: task, pull request, release, module, or document set
+- verdict: pass / fail / inconclusive
+- date: YYYY-MM-DD
+
+## Scope Checked
+
+| Area | Included? | Evidence |
+| --- | --- | --- |
+| Implementation scope | yes / no | files, diff, commit, or PR |
+| Tests and regression | yes / no | commands, CI runs, logs, screenshots |
+| SSoT and ledger updates | yes / no | Feature, Delivery, Regression, Closeout, or Harness Ledger links |
+| Review disposition | yes / no | review path, finding IDs, or no-finding statement |
+| Lessons and references | yes / no | Lessons SSoT, detail doc, or checked-none reason |
+
+## Explicit Exclusions
+
+| Exclusion | Reason | Risk |
+| --- | --- | --- |
+| Scope not checked | why it was excluded | low / medium / high |
+
+## Findings
+
+| ID | Severity | Finding | Evidence Checked | Required Action | Open | Disposition | Blocks Release | Follow-up |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- |
+
+Allowed `Disposition` values: `open`, `mitigated`, `closed`, `deferred`, `accepted-risk`, `not-reproducible`, `out-of-scope`.
+Do not keep sample findings. If there are no findings, leave only the header and explain the no-finding basis in `Final Confidence Basis`.
+
+## Residual Routing
+
+| Residual | Owner | Due | Accepted? | Link |
+| --- | --- | --- | --- | --- |
+| risk or `none` | owner | YYYY-MM-DD or n/a | yes / no / n/a | issue, SSoT row, or none |
+
+## Final Confidence Basis
+
+State the concrete evidence that justifies the verdict. Include the strongest checks run, the most important exclusions, and why any residual risk is acceptable or blocking.

package/templates/walkthrough/Closeout-SSoT.md

@@ -0,0 +1,43 @@
+# Closeout SSoT
+
+## Purpose
+
+Track whether planned work has completed the required closeout contract: implementation evidence, regression evidence, review disposition, walkthrough, residual routing, lessons check, and ledger update.
+
+## Status Legend
+
+| Status | Meaning | Required Next Step |
+| --- | --- | --- |
+| open | Work is not ready for closeout. | Continue implementation or evidence collection. |
+| evidence | Implementation is done but verification is incomplete. | Run required checks and attach evidence. |
+| review | Evidence exists and review is pending. | Resolve findings or record `accepted-risk`. |
+| closing | Final walkthrough and ledger updates are in progress. | Finish lessons check and routing. |
+| closed | Closeout contract is complete. | Archive after the retention window. |
+| blocked | Closeout cannot finish. | Record blocker owner and unblock condition. |
+| archived | Closeout is historical. | Keep archive pointer. |
+
+## Active Closeouts
+
+| ID | Work Item | Owner | Status | Implementation Evidence | Regression Evidence | Review Disposition | Walkthrough | Lessons Check | Harness Ledger | Residual | Updated |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| CO-YYYY-MM-DD-001 | F-000 or D-000 title | owner | [open / closed / blocked] | path or pending | RG-000 or pending | pending | pending | pending | HL-000 | none | YYYY-MM-DD |
+
+## Release-Blocking Residuals
+
+| Residual | Source | Owner | Blocks Release? | Decision | Due |
+| --- | --- | --- | --- | --- | --- |
+| risk or unresolved finding | review, regression, or walkthrough | owner | yes / no | fix, accept, defer, or waive | YYYY-MM-DD |
+
+## Routing Rules
+
+1. Every shipped feature, delivery, release, and harness update needs a closeout row.
+2. Move to `closed` only after walkthrough, regression evidence, review disposition, lessons check, and Harness Ledger link are complete.
+3. `not run` verification is a residual, not a pass.
+4. Release-blocking residuals must stay visible until fixed, accepted by an owner, or moved to a follow-up with a due date.
+5. Closeout rows should link durable files rather than summarize chat decisions.
+
+## Archive Rules
+
+- Keep open, evidence, review, closing, and blocked rows in this file.
+- Archive closed rows after the next release or maintenance cycle.
+- Preserve final evidence, walkthrough, lessons check, residual decision, and archive date.

package/templates/walkthrough/walkthrough-template.md

@@ -0,0 +1,63 @@
+# Walkthrough: Short Task or Release Title
+
+## Summary
+
+One sentence describing what changed and why it matters.
+
+## Scope
+
+| Area | Details |
+| --- | --- |
+| Changed modules | List paths or module IDs. |
+| New files | List files or `none`. |
+| Removed files | List files or `none`. |
+| Out of scope | List explicitly excluded work. |
+
+## Decisions
+
+| Decision | Choice | Reason | Owner |
+| --- | --- | --- | --- |
+| Decision title | Selected option | Why this choice is acceptable | owner |
+
+## Verification
+
+| Check | Command or Procedure | Result | Evidence |
+| --- | --- | --- | --- |
+| Unit, integration, browser, CI, or manual check | command or procedure | pass / fail / not run | path, log, screenshot, or reason |
+
+## Regression Linkage
+
+| Gate | Required? | Result | Evidence Depth | Notes |
+| --- | --- | --- | --- | --- |
+| RG-000 | yes / no | pass / fail / waived / not run | E0/E1/E2/E3 | link to Regression SSoT or waiver |
+
+## Review Disposition
+
+| Source | Material Findings | Resolution | Evidence |
+| --- | --- | --- | --- |
+| reviewer, verifier, CI, or self-review | none / finding IDs | closed / mitigated / accepted-risk / out-of-scope / n/a | review path or note |
+
+## Residual Risk
+
+| Risk | Owner | Accepted? | Follow-up |
+| --- | --- | --- | --- |
+| none | owner | n/a | none |
+
+## Lessons Reflection
+
+| Question | Answer |
+| --- | --- |
+| Did this reveal a reusable reference, workflow, or checker gap? | yes / no, reason |
+| Could a future agent repeat the same mistake? | yes / no, reason |
+| Was a lesson created or updated? | L-YYYY-MM-DD-001 or checked-none: reason |
+| Lessons detail doc | path or none |
+
+## Closeout Links
+
+| Artifact | Link |
+| --- | --- |
+| Task plan | docs/09-PLANNING/TASKS/.../task_plan.md |
+| Feature or Delivery SSoT | F-000 or D-000 |
+| Harness Ledger | HL-YYYY-MM-DD-001 |
+| Closeout SSoT | CO-YYYY-MM-DD-001 |
+| Pull request or commit | link or hash |

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

@@ -0,0 +1,92 @@
+# [项目名称]
+
+> Agent 进入本仓库时先读这个文件。它负责说明项目边界、工作顺序和文档入口，不承载所有细节。
+
+## 项目概况
+
+- **项目名**：[项目名称]
+- **技术栈**：[语言 / 框架 / 运行时]
+- **仓库形态**：[单仓 / monorepo / 多仓协作]
+- **主要模块**：[列出主要子项目、包或服务]
+- **默认分支**：[例如 `main`]
+
+## 不可违反的规则
+
+1. [架构约束，例如：外部依赖必须通过 adapter 层隔离]
+2. [安全约束，例如：不得提交密钥、令牌、用户隐私数据]
+3. [流程约束，例如：非平凡任务必须先建立任务目录和计划文件]
+4. [发布约束，例如：未通过指定回归门禁不得合并或发布]
+
+## 任务阅读矩阵
+
+按任务类型读取最少但足够的上下文。不要一次性加载整套文档。
+
+| 任务类型 | 先读文件 |
+| --- | --- |
+| 架构、核心模块、跨模块改动 | `docs/11-REFERENCE/engineering-standard.md` |
+| 测试、冒烟、回归 | `docs/11-REFERENCE/testing-standard.md` |
+| 开发执行、提交、PR | `docs/11-REFERENCE/execution-workflow-standard.md` |
+| 多人协作、多仓交付、前后端分工 | `docs/11-REFERENCE/delivery-operating-model-standard.md`，再读 `docs/09-PLANNING/Delivery-SSoT.md` |
+| 仓库治理、PR 规则、分支保护 | `docs/11-REFERENCE/repo-governance-standard.md` |
+| CI/CD、必跑检查、发布门禁 | `docs/11-REFERENCE/ci-cd-standard.md` |
+| 长程任务、连续执行、子代理审查 | `docs/11-REFERENCE/long-running-task-standard.md` |
+| 对抗性审查、reviewer 报告 | `docs/11-REFERENCE/adversarial-review-standard.md` |
+| reviewer、subagent、外部审查路由 | `docs/11-REFERENCE/review-routing-standard.md` |
+| 文档治理、planning、任务目录 | `docs/11-REFERENCE/docs-library-standard.md` |
+| Harness Ledger 回写 | `docs/11-REFERENCE/harness-ledger-standard.md` |
+| Regression SSoT 维护 | `docs/11-REFERENCE/regression-ssot-governance.md` |
+| 收口记录、Closeout、Lessons | `docs/11-REFERENCE/walkthrough-standard.md`，再读 `docs/01-GOVERNANCE/Lessons-SSoT.md` 与 `docs/10-WALKTHROUGH/Closeout-SSoT.md` |
+| Worktree、并行开发、worker 隔离 | `docs/11-REFERENCE/worktree-standard.md` |
+| [前端任务] | `docs/11-REFERENCE/frontend-standard.md` |
+| [API 任务] | `docs/11-REFERENCE/api-standard.md` |
+
+## 标准执行流程
+
+1. 判断任务是否非平凡；非平凡任务先在 `docs/09-PLANNING/TASKS/` 建任务目录。
+2. 填写 `task_plan.md`，并补齐同级 `execution_strategy.md` 与 `visual_roadmap.md`。
+3. 确认本任务的 delivery operating model；涉及多人、多仓或共享交付时更新 Delivery SSoT。
+4. 如果任务可能长时间连续执行，先填写 `long-running-task-contract.md`。
+5. 如需 reviewer、subagent、release review，在任务目录维护 `review.md`。
+6. 涉及合并、PR、CI 或发布时，先读仓库治理和 CI/CD 标准。
+7. 根据任务类型回写功能 SSoT、Delivery SSoT 或 Regression SSoT。
+8. 按 worktree 标准创建独立 worktree、feature branch、contract branch 或 release branch。
+9. 实现后运行约定检查和回归门禁，并把证据写入 `progress.md` 或 artifacts index。
+10. 收口前按 `review-routing-standard.md` 触发所需审查，处理所有阻塞发现。
+11. 写 walkthrough，并引用任务计划、证据、审查结论和残余风险。
+12. 执行 Lessons 检查：有可复用经验则写入 `docs/01-GOVERNANCE/lessons/` 并更新 Lessons SSoT；无经验也要记录 `checked-none: <原因>`。
+13. 更新 `docs/10-WALKTHROUGH/Closeout-SSoT.md` 与 `docs/Harness-Ledger.md`。
+14. 清理已完成并合并的 worktree。
+
+## 子代理 / Worker 规则
+
+主 agent 作为 coordinator 调用 subagent、外部 agent 或 reviewer 时，必须先判断对方角色。
+
+- `reviewer`：默认只读，只能写审查报告、findings 或 `review.md`，不得直接改业务代码。
+- `worker`：凡是会改代码、测试、产品文档或 harness 文档的 subagent，都必须在独立 worktree 和分支内工作。
+
+Worker 的最低交付合同：
+
+1. coordinator 先分配 worktree 路径、分支名、任务目录和允许写入范围。
+2. worker 只在自己的 worktree 内编辑，不写 coordinator 当前 checkout。
+3. worker 完成后运行约定检查，并提交自己的改动。
+4. worker handoff 必须包含 worktree path、branch、commit SHA、checks、residual risks。
+5. coordinator 只集成 worker 的 commit，不把多个 worker 的未提交改动混在同一个 checkout。
+6. coordinator 合并后运行最终回归，并更新 walkthrough、Harness Ledger 和 Lessons。
+
+如果环境或用户明确要求不使用独立 worktree，必须在 `progress.md`、walkthrough 或 Harness Ledger 记录偏离原因、风险和补偿验证。
+
+## SSoT 与总账
+
+- **功能 SSoT**：`docs/09-PLANNING/[功能-SSoT].md`
+- **Delivery SSoT**：`docs/09-PLANNING/Delivery-SSoT.md`
+- **Regression SSoT**：`docs/05-TEST-QA/Regression-SSoT.md`
+- **Lessons SSoT**：`docs/01-GOVERNANCE/Lessons-SSoT.md`
+- **Cadence Ledger**：`docs/05-TEST-QA/Cadence-Ledger.md`
+- **Harness Ledger**：`docs/Harness-Ledger.md`
+- **Closeout SSoT**：`docs/10-WALKTHROUGH/Closeout-SSoT.md`
+- **仓库治理标准**：`docs/11-REFERENCE/repo-governance-standard.md`
+- **CI/CD 标准**：`docs/11-REFERENCE/ci-cd-standard.md`
+
+## 协作补充
+
+[按项目实际填写：模块 owner、共享文件锁、merge 顺序、发布审批人、环境限制等。]

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

@@ -0,0 +1,12 @@
+# 中文项目入口（Claude Code）
+
+本项目以 `AGENTS.md` 作为 coding agent 指令的唯一权威入口。
+
+Claude Code 开始任何任务前应当：
+
+1. 先读取 `AGENTS.md`。
+2. 按 `AGENTS.md` 的任务阅读矩阵选择当前任务需要的文件。
+3. 只加载必要的 `docs/11-REFERENCE/` 标准文件和任务目录上下文。
+4. 把本文件视为 Claude Code 兼容入口，而不是第二份项目规范。
+
+不要在这里复制项目规则。长期有效的项目指令应维护在 `AGENTS.md` 及其引用文档中，避免两套规则逐渐漂移。