coding-agent-harness 1.0.0

package/references/cadence-ledger.md

@@ -0,0 +1,55 @@
+# Cadence Ledger
+
+## 目的
+
+定义"什么情况下自动触发哪些回归面"。让 agent 在 merge 或改动后自动知道该跑什么回归，不依赖人的记忆。
+
+## Cadence Ledger 结构
+
+Cadence Ledger 是一个独立文件，放在 `docs/05-TEST-QA/Cadence-Ledger.md`。
+
+包含两个部分：
+
+### 1. Trigger Rules（触发规则）
+
+定义改动范围到回归面的映射：
+
+```markdown
+## Trigger Rules
+
+| 改动范围 | 触发的 Regression Gates |
+|----------|----------------------|
+| [范围1，如 API 路由层] | RG-001, RG-003 |
+| [范围2，如前端组件] | RG-005 |
+| [范围3，如数据库 schema] | RG-001, RG-002, RG-004 |
+| [范围4，如认证/权限] | RG-006, RG-007 |
+| 任何 merge 到主干 | Full Shared Batch |
+```
+
+### 2. Shared Regression Batch Log（共享回归批次记录）
+
+记录每一轮 shared batch 的执行情况：
+
+```markdown
+## Shared Regression Batch Log
+
+| Batch | Date | Scope | Trigger | Result | Notes | Next Checkpoint |
+|-------|------|-------|---------|--------|-------|-----------------|
+| SRB-001 | YYYY-MM-DD | Full | Initial bootstrap | 3/5 🟢 2/5 🟡 | [备注] | SRB-002 after [条件] |
+```
+
+## 如何建立 Cadence Ledger
+
+1. 从 Regression SSoT 中获取所有 active gate 的 ID 和 surface
+2. 分析项目代码结构，识别哪些代码目录/模块对应哪些 surface
+3. 建立"改动范围 → gate"的映射关系
+4. 定义 merge 到主干时的 full batch 规则
+5. 跑第一轮 shared batch，记录结果
+
+## 维护规则
+
+- 新增 regression gate 时，必须同步更新 trigger rules
+- 每轮 shared batch 执行后，必须记录到 batch log
+- 定期审查 trigger rules 是否还准确（代码结构可能变化）
+- 如果本轮任务改变了 trigger rules、gate 结构或 evidence depth，收口时在 Harness Ledger 记录 `Regression=updated`
+- routine batch 只更新 `Last Verified` 且无 residual / evidence depth 变化时，不强制写 Harness Ledger

package/references/ci-cd-standard.md

@@ -0,0 +1,90 @@
+# CI/CD Standard
+
+## 核心思路
+
+每个 project harness 必须 define a project-specific CI/CD profile. Generic CI text is not enough.
+
+CI/CD design must connect the project's real stack to required merge evidence:
+
+- package manager
+- lint / typecheck / build / test commands
+- smoke or regression commands
+- workflow trigger
+- required status checks
+- residuals when a command or environment is missing
+
+## 存放位置
+
+```text
+docs/11-REFERENCE/ci-cd-standard.md
+```
+
+Workflow files usually live under:
+
+```text
+.github/workflows/
+```
+
+For non-GitHub platforms, use the native workflow location and document it here.
+
+## CI Profile
+
+Required fields:
+
+- Platform: [GitHub Actions / GitLab CI / local-only / other]
+- Runtime: [Node / Python / Go / Rust / Java / mixed / other]
+- Package manager: [npm / pnpm / yarn / uv / pip / cargo / go / other]
+- Install command
+- Lint command
+- Typecheck command
+- Test command
+- Build command
+- Smoke / regression command
+- Cache strategy
+- Required secrets
+- Unsupported checks and residuals
+
+## Workflow Requirements
+
+At minimum, CI must define:
+
+- `pull_request` trigger
+- default branch push trigger, unless explicitly residualized
+- install step
+- at least one verification step matching the project stack
+- artifact or log strategy for smoke / screenshots when relevant
+
+CI must not be a generic placeholder. Commands must either exist in the project or be marked
+`blocked-with-owner`.
+
+## Required Checks
+
+The required checks list must match actual job names in the workflow.
+
+Example:
+
+| Required check | Workflow job | Source |
+|----------------|--------------|--------|
+| lint | `ci / lint` | `.github/workflows/ci.yml` |
+| build | `ci / build` | `.github/workflows/ci.yml` |
+
+## CD / Release
+
+If the project deploys or packages artifacts, document:
+
+- release trigger
+- environment
+- approval requirement
+- rollback path
+- signing / notarization / credential boundary
+
+If deployment is out of scope, write `n/a` with a reason. Do not leave deployment undecided.
+
+## Completion Rule
+
+CI/CD setup is complete only when one is true:
+
+1. Workflow exists and required checks are documented.
+2. Platform cannot support CI yet, and the blocker has owner/action/status.
+
+Generic text without workflow or residual is incomplete.

package/references/delivery-operating-model-standard.md

@@ -0,0 +1,145 @@
+# Delivery Operating Model Standard
+
+## 核心思路
+
+Harness 不能默认只有“一人主控 + 多 agent worktree”一种场景。项目启动时必须先识别
+delivery operating model：谁负责拆分工作、几个仓库/团队并行、agent 能看到哪些上下文、
+接口合同如何冻结、冲突和 merge 顺序由谁裁决。
+
+代码结构回答“项目是什么”，delivery operating model 回答“人和 agent 怎么交付”。
+
+## 存放位置
+
+```text
+docs/11-REFERENCE/delivery-operating-model-standard.md
+```
+
+如项目是多人或多仓交付，还应创建：
+
+```text
+docs/09-PLANNING/Delivery-SSoT.md
+```
+
+## 必填字段
+
+### Operating Model Profile
+
+- Model: `solo-orchestrator` / `team-feature-lead` / `split-repo-contract` / `program-multi-repo` / `waterfall-stage-gate` / `kanban-continuous`
+- Team shape: single human, multiple humans, multiple humans with personal agents, or mixed
+- Repo topology: single repo, monorepo, split frontend/backend repos, or program of repos
+- Primary planning owner
+- Merge/integration owner
+- Release owner
+- Agent visibility: full repo, package-scoped, API-doc-only, design-doc-only, or other
+
+### Work Decomposition Rule
+
+Define who breaks roadmap work into feature blocks:
+
+| Level | Owner | Artifact | Rule |
+|-------|-------|----------|------|
+| Roadmap | [owner] | [SSoT / issue tracker] | [how priority is chosen] |
+| Feature block | [owner] | `Delivery-SSoT.md` / Feature SSoT | [how blocks are bounded] |
+| Task | [owner] | `docs/09-PLANNING/TASKS/<task>/task_plan.md` | [who can start work] |
+| Review | [owner] | `review.md` / PR review | [required reviewers] |
+| Integration | [owner] | PR / release branch / integration branch | [merge order] |
+
+### Model-Specific Contracts
+
+#### solo-orchestrator
+
+Use when one human directs multiple agents across worktrees.
+
+- One primary Feature SSoT is enough for linear phase work.
+- Worktree concurrency is central.
+- Merge order is human-decided.
+- Cross-task conflicts are managed by task ownership and shared-file notices.
+
+**模块并行扩展**：当项目有 2+ 个可独立演进的功能域时，启用模块并行开发（见 `references/module-parallel-standard.md`）。此时：
+
+- Module Registry 替代 Feature SSoT 作为进度追踪的主要工具
+- 每个模块一个长期 worktree（`codex/<module-key>`）
+- 模块间通过 write scope 声明避免冲突
+- 跨模块修改走独立的基础设施 task
+- 发布 = git tag + 包含的步骤 ID 列表
+
+#### team-feature-lead
+
+Use when a lead decomposes sprint/week work into feature blocks and several developers each direct agents.
+
+- `Delivery-SSoT.md` is required.
+- Each feature block must have owner, repo/package scope, shared files, dependencies, integration order, and acceptance gates.
+- Shared files require owner-lock or explicit sequencing.
+- Agents must not start unassigned work just because it appears in the backlog.
+
+#### split-repo-contract
+
+Use when frontend/backend or app/service repos remain separate.
+
+- Each repo may have its own harness.
+- Cross-repo work must be driven by an interface contract, not by agents reading both repos freely.
+- Frontend agents may only rely on API schema, mock server, OpenAPI/GraphQL contract, example payloads, and agreed error semantics unless granted backend read access.
+- Backend agents may only rely on frontend consumption contract and product acceptance notes unless granted frontend read access.
+- Contract changes require paired PRs or a compatibility window.
+
+#### program-multi-repo
+
+Use when a main project coordinates several child repos.
+
+- Program-level Delivery SSoT is required.
+- Each repo keeps its own repo governance, CI/CD, and Regression SSoT.
+- Integration owner decides merge order and release train.
+- Cross-repo residuals must be represented in the program SSoT and child repo Harness Ledgers.
+
+#### waterfall-stage-gate
+
+Use when work passes through formal stages: requirements, design, implementation, verification, release.
+
+- Stage entry/exit criteria must be explicit.
+- Agents cannot skip design/review gates just because code is ready.
+- Walkthrough and Closeout SSoT map to stage closeout, not only feature closeout.
+
+#### kanban-continuous
+
+Use when work flows continuously without sprint batches.
+
+- WIP limits replace sprint allocation.
+- Delivery SSoT can be lightweight but must record active owners, blocked items, and integration order.
+- Closeout rules are identical: review, evidence, walkthrough/skip reason, Harness Ledger.
+
+## Delivery SSoT Minimum Columns
+
+| Block ID | Feature / Work Block | Owner | Agent Scope | Repo(s) | Dependencies | Shared Files / Contracts | Integration Order | Acceptance Gates | Status |
+|----------|----------------------|-------|-------------|---------|--------------|--------------------------|-------------------|------------------|--------|
+
+Status must use:
+
+- `planned`
+- `assigned`
+- `in-progress`
+- `blocked`
+- `ready-for-integration`
+- `integrated`
+- `closed`
+
+## Cross-Repo Interface Contract
+
+For split frontend/backend work, every contract-bearing feature must define:
+
+- API/schema source of truth
+- request/response examples
+- error semantics
+- compatibility rule
+- mock/stub strategy
+- owner for breaking changes
+- verification command on each side
+
+## Completion Rule
+
+Bootstrap is incomplete unless the project has:
+
+1. A selected delivery operating model.
+2. A named planning/integration owner, even if both are the same person.
+3. A rule for feature block assignment.
+4. A rule for cross-repo or shared-file conflict handling.
+5. A Delivery SSoT when the selected model is team, split-repo, program, waterfall, or kanban with multiple people.

package/references/docs-directory-standard.md

@@ -0,0 +1,125 @@
+# docs/ 目录标准
+
+## 目的
+
+定义项目文档目录的标准结构。所有文档按职责分层，agent 按 Task-Type Reading Matrix 按需加载。
+
+## 标准目录结构
+
+```
+docs/
+├── Harness-Ledger.md           ← 全局 harness 上下文回写总账
+├── 00-RAW-PRDS/              ← 原始需求文档、PRD、用户故事
+│   └── _archive/              ← 本层历史文档归档（如该层会增长）
+├── 01-GOVERNANCE/             ← 项目治理规则、决策记录、经验沉淀
+│   ├── Lessons-SSoT.md        ← 经验沉淀建议表
+│   ├── lessons/               ← 具体沉淀内容
+│   └── _archive/              ← 已处理条目归档
+├── 02-PRODUCT/                ← 产品设计、用户流程、功能规格
+│   └── _archive/              ← 本层历史文档归档（如该层会增长）
+├── 03-ARCHITECTURE/           ← 架构设计、技术方案、ADR
+│   └── _archive/              ← 本层历史文档归档（如该层会增长）
+├── 04-DEVELOPMENT/            ← 开发指南、环境配置、本地开发说明
+│   └── _archive/              ← 本层历史文档归档（如该层会增长）
+├── 05-TEST-QA/                ← 测试策略、Regression SSoT、Cadence Ledger
+│   └── _archive/              ← 废弃 regression gate / 旧 evidence pack 归档
+├── 06-INTEGRATIONS/           ← 第三方集成文档、API 对接说明
+│   └── _archive/              ← 本层历史文档归档（如该层会增长）
+├── 07-OPERATIONS/             ← 部署、运维、监控、告警
+│   └── _archive/              ← 本层历史文档归档（如该层会增长）
+├── 08-SECURITY/               ← 安全策略、权限模型、审计日志
+│   └── _archive/              ← 本层历史文档归档（如该层会增长）
+├── 09-PLANNING/               ← 排期、任务计划
+│   ├── TASKS/                 ← 任务目录（每个任务一个子目录）
+│   │   └── _task-template/    ← 任务模板
+│   ├── MODULES/               ← 模块并行开发计划（启用时）
+│   │   └── _archive/          ← 已完成 / 暂停过久模块归档
+│   ├── _archive/              ← 历史任务、旧 Feature SSoT 明细、过期排期归档
+│   ├── Delivery-SSoT.md       ← 多人 / 多仓 / 传统流程下的交付排期和集成顺序
+│   └── [Feature-SSoT].md     ← 实施排期表
+├── 10-WALKTHROUGH/            ← Walkthrough 收口记录与 Closeout SSoT
+│   └── _archive/              ← 历史 walkthrough 批量归档（迁移 / 年度收束时）
+├── 11-REFERENCE/              ← 标准文件（agent 按需加载）
+│   └── _archive/              ← 旧版标准归档
+└── 99-TMP/                    ← 临时文件（定期清理）
+```
+
+## 裁剪规则
+
+不是每个项目都需要全部目录。根据诊断结果裁剪：
+
+| 目录 | 何时可省略 |
+|------|-----------|
+| 00-RAW-PRDS | 没有正式 PRD 流程的小项目 |
+| 01-GOVERNANCE | 仅实验性 Lite 项目且明确不启用 Lessons / 归档时 |
+| 02-PRODUCT | 纯技术项目（库、CLI 工具） |
+| 06-INTEGRATIONS | 没有第三方集成 |
+| 07-OPERATIONS | 没有部署需求（纯库） |
+| 08-SECURITY | 没有安全敏感场景 |
+| 99-TMP | 可选 |
+
+以下目录是 harness 的核心，不可省略：
+- 01-GOVERNANCE
+- 03-ARCHITECTURE
+- 05-TEST-QA
+- 09-PLANNING（含 TASKS/）
+- 10-WALKTHROUGH
+- 11-REFERENCE
+
+`docs/Harness-Ledger.md` 不是目录，但属于核心 harness 文件，不可省略。它是
+`docs/` 根目录允许存在的全局控制文件；普通过程文件仍然不得放在根目录。
+
+`docs/10-WALKTHROUGH/Closeout-SSoT.md` 是 closed task 的收口索引和硬门槛；
+每个 closed Harness Ledger row 必须在这里登记 walkthrough 或受控 skip reason。
+
+## 通用归档规则
+
+归档是目录级基础设施，不是单张表的特例。任何会持续增长的目录都应该有同级
+`_archive/` 目录；如果目录本身不会增长，可以暂不创建，但第一次归档前必须创建。
+
+### 硬规则
+
+- Active 文件只保存当前事实和最近需要操作的事实。
+- 历史事实移入同级 `_archive/`，不要长期堆在 Active 表底部。
+- 归档不改变原始 ID，不删除 task plan、walkthrough、SSoT 或 Ledger 的可追溯引用。
+- 归档后 Active 文件必须留下归档索引或指针，说明历史在哪里。
+- 归档文件必须按时间或范围命名：`<name>-archive-YYYY-QN.md`、`<name>-phase-1-11.md`、`YYYY-MM-DD-<name>.md`。
+- 新增归档规则时，同步更新 `docs-library-standard.md` 和对应 checker。
+
+### 推荐触发条件
+
+| 对象 | 触发条件 | 归档位置 |
+|------|----------|----------|
+| Feature SSoT Active 表 | 模块并行切换、release 完成、或 completed rows 超过 20 条 | `09-PLANNING/_archive/` |
+| Delivery SSoT | 集成 wave 结束或 completed/superseded blocks 超过 20 条 | `09-PLANNING/_archive/` |
+| Module Registry / module_plan | 模块 completed 或 paused 超过 60 天 | `09-PLANNING/MODULES/_archive/<key>/` |
+| Regression SSoT | gate 废弃或长期不再运行 | `05-TEST-QA/_archive/` |
+| Lessons SSoT | merged/rejected 条目超过 20 条 | `01-GOVERNANCE/_archive/` |
+| Harness Ledger | closed/superseded 超过 50 条 | `01-GOVERNANCE/_archive/` |
+| Walkthrough | 年度/阶段迁移或目录过大 | `10-WALKTHROUGH/_archive/` |
+
+## Reference 标准文件清单
+
+`docs/11-REFERENCE/` 下的标准文件，按项目需要选择：
+
+| 文件 | 职责 | 必需？ |
+|------|------|--------|
+| testing-standard.md | 测试规范、框架选择、覆盖率要求 | 是 |
+| execution-workflow-standard.md | 开发执行流程、commit 规范、PR 流程 | 是 |
+| delivery-operating-model-standard.md | 工程组织形态、feature block 拆分、跨仓/团队协作模型 | 是 |
+| repo-governance-standard.md | repo platform、branch protection、PR policy、required checks、worktree concurrency | 是 |
+| ci-cd-standard.md | CI/CD profile、workflow、required checks、release/CD residual | 是 |
+| long-running-task-standard.md | 长程任务合同、连续执行权限、review loop、停止条件 | 是 |
+| adversarial-review-standard.md | 对抗性 review 报告、finding 分级、no-finding 结论、residual 路由 | 是 |
+| review-routing-standard.md | reviewer / subagent / external agent / human review 触发和路由规则 | 是 |
+| docs-library-standard.md | 文档治理规范、命名规则、归档规则 | 是 |
+| harness-ledger-standard.md | Harness Ledger 写入规范、closeout 检查 | 是 |
+| regression-ssot-governance.md | Regression SSoT 治理规范 | Standard+ |
+| walkthrough-standard.md | Walkthrough 写作规范 | 是 |
+| worktree-standard.md | Worktree 命名、分支、清理规范 | Standard+ |
+| engineering-standard.md | 工程规范、代码风格、架构约束 | 推荐 |
+| frontend-standard.md | 前端规范（如有前端） | 按需 |
+| api-standard.md | API 设计规范（如有 API） | 按需 |
+| security-standard.md | 安全规范（如有安全需求） | 按需 |
+| deployment-standard.md | 部署规范（如有部署需求） | 按需 |
+| debugging-playbook.md | 调试经验手册 | 推荐 |

package/references/harness-ledger.md

@@ -0,0 +1,148 @@
+# Harness Ledger
+
+## 核心思路
+
+Harness Ledger 是 `docs/` 骨架的全局更新总账。它不保存业务事实，也不替代
+Delivery / Feature / Regression / Lessons 四张 SSoT；它只记录每个非平凡任务是否按 harness SOP
+维护了应该维护的上下文。Closeout SSoT 则记录每个 closed 任务是否有 walkthrough 或受控 skip reason。
+
+一句话定义：
+
+> SSoT 保存当前事实；Harness Ledger 记录每轮任务是否维护了这些事实。
+
+## 文件位置
+
+```text
+docs/Harness-Ledger.md
+```
+
+放在 `docs/` 根目录，而不是 `docs/01-GOVERNANCE/`。原因是它横跨 planning、
+regression、walkthrough、reference、lessons 等多个目录，是全局审计索引。
+
+## 职责边界
+
+Harness Ledger 记录：
+
+- 本任务是否创建或更新 task plan
+- 是否创建或更新 review report（如任务需要对抗性审查）
+- 是否更新或验证 Repo Governance / CI-CD guardrails
+- 是否回写 Feature SSoT
+- 是否更新 Regression SSoT 或 Cadence Ledger
+- 是否创建 walkthrough
+- 是否执行 Lessons 检查，是否产生 Lessons SSoT 条目
+- 如果产生 Lessons SSoT 条目，是否已创建 `docs/01-GOVERNANCE/lessons/` 详情文档
+- 本轮触碰了哪些 harness 文档
+- 是否有 residual 或 skipped-with-reason
+
+Harness Ledger 不记录：
+
+- 每次 `progress.md` 的过程性更新
+- 每条测试输出
+- 每个 git diff 细节
+- Feature / Regression / Lessons 的业务事实本身
+- 可以从 git history 直接恢复的逐行变更
+
+## 触发规则
+
+必须更新 Harness Ledger：
+
+1. 完成一个非平凡 task / wave / feature
+2. Bootstrap harness 完成
+3. 同步或升级最新版 coding-agent-harness
+4. 新增或修改 AGENTS.md / CLAUDE.md / reference / template
+5. 创建或更新 required review report
+6. coordinator pass 同步模块任务的全局状态、review、closeout 或 regression 结果
+7. 修改 Repo Governance / CI-CD / required checks / branch protection 状态
+8. 修改 Feature SSoT、Regression SSoT、Lessons SSoT 任一文件
+9. 创建 walkthrough
+10. Lessons approved 后合入正式 reference
+
+不需要更新 Harness Ledger：
+
+1. 小 typo
+2. 单次 `progress.md` 过程性更新
+3. 普通测试输出粘贴
+4. 只读分析
+5. routine regression batch 只更新 `Last Verified` 且无 residual /
+   evidence depth 变化
+
+## 状态词
+
+字段值必须使用固定词，避免自由文本失控：
+
+- `required`
+- `updated`
+- `created`
+- `checked-none`
+- `checked-created`
+- `n/a`
+- `skipped-with-reason`
+- `missing`
+
+## ID 规则
+
+格式：
+
+```text
+HL-YYYYMMDD-NNN
+```
+
+示例：
+
+```text
+HL-20260511-001
+```
+
+多 agent 并行时，每个 agent 只追加或更新自己负责的 row。冲突时保留双方 row，
+不要重排全表。
+
+## 归档规则
+
+Active 表保留最近 50 条。更早的 `closed` 或 `superseded` 条目按季度归档：
+
+```text
+docs/01-GOVERNANCE/_archive/Harness-Ledger-archive-YYYY-QN.md
+```
+
+归档不改变 `HL-*` ID，也不删除 walkthrough、task plan 或四张 SSoT 中的引用。
+
+## Closeout 顺序
+
+每个非平凡任务收口时按以下顺序：
+
+1. 更新 `progress.md`
+2. 跑必要验证和 regression gate
+3. 回写 Feature SSoT；模块并行 worker 只回写 module_plan 和 Coordinator Handoff，coordinator pass 再同步 Module Registry / Harness Ledger
+4. 完成 `review.md` 并处理 material findings（如适用）
+5. 回写 Repo Governance / CI-CD 状态（如适用）
+6. 回写 Regression SSoT / Cadence Ledger（如适用）
+7. 写 walkthrough
+8. 更新 Closeout SSoT
+9. 执行 Lessons 检查；如有沉淀，先写详情文档，再更新 Lessons SSoT
+10. 更新 Harness Ledger
+
+最后更新 Harness Ledger，是为了让它记录本轮所有上下文维护的最终状态。
+如果 Harness Ledger row 进入 `closed` / `closed-with-residual` / `closed-local-only`，
+必须同步在 `docs/10-WALKTHROUGH/Closeout-SSoT.md` 登记 walkthrough 或受控 skip reason。
+同时必须登记 Lessons Check：`checked-created: L-YYYY-MM-DD-NNN` 或
+`checked-none: <reason>`。
+
+## Harness Update 记录
+
+更新已有 harness 时，Ledger row 只记录本次 delta merge：
+
+- 读到了哪个最新版 Skill / reference / template
+- 新增或修补了哪些 harness 骨架文件
+- 哪些既有 SSoT / walkthrough / task history 被保留未覆盖
+- 是否产生 residual，例如某个标准暂不适合当前项目
+
+不要把模板全文、旧文档全文或逐行 diff 复制进 Ledger。细节由 git history 和
+walkthrough 保存，Ledger 只回答"这次升级维护了哪些上下文入口"。
+
+## 常见反模式
+
+- 把 Harness Ledger 写成逐行 diff 日志
+- 把 Feature / Regression / Lessons 的业务事实复制进 Ledger
+- 每次测试或每次 progress 变动都追加 row
+- 用自由文本状态导致无法快速扫描
+- 任务完成但 Ledger 标记 `missing` 没有 residual 说明