coding-agent-harness 1.0.1 → 1.0.4

package/docs-release/guides/preset-development.md

@@ -0,0 +1,214 @@
+# Preset Development
+
+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.
+
+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.
+
+`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.
+
+## Install Location
+
+Project presets live in:
+
+```text
+<target>/.coding-agent-harness/presets/<preset-id>/
+```
+
+User-installed presets live in:
+
+```text
+~/.coding-agent-harness/presets/<preset-id>/
+```
+
+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.
+
+Bundled presets are not only fallback files. `npm install -g coding-agent-harness`
+and `harness install-user` seed them into the user preset root, while
+`harness init` seeds them into the project preset root. Re-run
+`harness preset seed` for the user root or `harness preset seed --project <target>`
+for the project root when a preset root is missing or incomplete.
+
+## Package Layout
+
+```text
+my-preset/
+  preset.yaml
+  templates/
+    task_plan.append.md
+    references/
+      upstream-contract.md
+  resources/
+    service-runbook.md
+```
+
+## Minimal Manifest
+
+```yaml
+id: custom-review
+version: 1
+purpose: Create a review task with preset evidence.
+compatibleBudgets: [standard, complex]
+localeSupport: [en-US, zh-CN]
+task:
+  kind: review-task
+  defaultTaskId: custom-review-task
+entrypoints:
+  newTask:
+    type: template
+    writes: [docs/09-PLANNING/TASKS/**]
+    audit: true
+    templates:
+      taskPlanAppend: templates/task_plan.append.md
+inputs:
+  subject:
+    type: text
+    flag: --subject
+    required: true
+templateValues:
+  subject:
+    from: inputs.subject
+metadata:
+  ReviewSubject:
+    label: Review Subject
+    from: inputs.subject
+evidence:
+  bundleDir: artifacts/preset
+  files:
+    subject:
+      path: subject.txt
+      type: text
+      value: inputs.subject
+audit:
+  manifestRequired: true
+  evidenceFiles: [preset-audit.json, preset-manifest.json, write-scope.json]
+writeScopes:
+  taskDocs:
+    path: docs/09-PLANNING/TASKS/**
+    access: write
+```
+
+## Reference Bundles
+
+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`.
+
+```yaml
+resources:
+  references:
+    upstreamContract:
+      path: references/upstream-contract.md
+      template: templates/references/upstream-contract.md
+      index:
+        id: REF-001
+        type: code
+        summary: Shared upstream {{service}} contract for every task created by this preset.
+        usedBy: coordinator,worker,reviewer
+    serviceRunbook:
+      path: references/service-runbook.md
+      source: resources/service-runbook.md
+      index:
+        id: REF-002
+        type: runbook
+        summary: Local verification notes for the shared upstream service.
+        usedBy: worker
+context:
+  requiredReads: [REF-001, REF-002]
+```
+
+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.
+
+## Artifact Bundles
+
+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`.
+
+```yaml
+resources:
+  artifacts:
+    inputPacket:
+      path: artifacts/input-packet.md
+      source: resources/artifacts/input-packet.md
+      index:
+        id: ART-001
+        type: fixture
+        summary: Shared fixture packet copied by the preset.
+        producedBy: preset
+```
+
+## Template Rendering
+
+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.
+
+`metadata` entries render first-class task plan lines such as `Review Subject: API contracts`.
+
+```md
+## Custom Review
+
+Subject: {{subject}}
+```
+
+## Inputs
+
+Supported input types:
+
+| Type | Use |
+| --- | --- |
+| `text` | Reads a CLI flag value such as `--subject "API"` |
+| `flag` | Reads a boolean CLI flag |
+| `json-file` | Reads and validates a JSON file such as `--from-session session.json` |
+
+`json-file` inputs can validate `validateOperation`, reject `planOnly`, require a target path, and route the task target from the JSON session.
+
+## Evidence
+
+Evidence files are written under the task directory and must match `writeScopes`.
+
+Supported evidence types:
+
+| Type | Output |
+| --- | --- |
+| `text` | Plain text from a value path |
+| `json` | JSON from a value path |
+| `input-json` | Raw resolved JSON input |
+| `preset-audit` | Manifest audit payload |
+| `preset-manifest` | Manifest snapshot |
+| `write-scope` | Declared write scopes |
+| `migration-verify` | Built-in migrate session verification |
+| `migration-ledger` | Built-in migration phase ledger |
+| `dashboard-hash` | Hash of the migration dashboard snapshot |
+| `target-git-status` | Target Git status from migration session |
+| `target-commit` | Current target commit |
+| `harness-version` | Current package version |
+| `generated-at` | Generation timestamp |
+
+## Commands
+
+```bash
+harness preset check ./my-preset
+harness preset install ./my-preset
+harness preset install ./my-preset --project /path/to/project
+harness preset install legacy-migration --force
+harness preset seed
+harness preset seed --project /path/to/project
+harness preset list --json /path/to/project
+harness preset inspect custom-review --json /path/to/project
+harness new-task custom-review-task --preset custom-review --subject "API contracts" /path/to/project
+harness preset uninstall custom-review
+```
+
+## Validation Method
+
+For every preset, prove both the manifest and downstream task behavior:
+
+1. Run `harness preset check ./my-preset`.
+2. Install into an isolated HOME or disposable environment.
+3. Create at least one task with `harness new-task --preset`.
+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.
+5. Run `harness status --json`, `harness task-index --json`, and `harness check --profile target-project <target>`.
+6. Inspect `task_plan.md` to confirm required reads are visible before implementation starts.
+
+## Boundaries
+
+- Presets cannot write outside declared `writeScopes`.
+- Presets do not run arbitrary JavaScript during `new-task`.
+- 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.
+- Script and check entrypoints may exist in bundled packages, but the task creation path is YAML + templates + built-in processors.
+- Use a new built-in processor only when multiple presets need the same capability and the behavior can be tested centrally.

package/docs-release/guides/repository-operating-models.en-US.md

@@ -0,0 +1,197 @@
+# Repository Operating Models
+
+Chinese mirror: `docs-release/guides/repository-operating-models.md`
+
+Coding Agent Harness can live inside different repository structures. If you choose the wrong one, the main problem is not "not enough docs." The harness itself becomes another source of confusion.
+
+This guide explains three common models:
+
+- Single-repo model: one code repository, one harness.
+- Independent multi-repo model: multiple code repositories, each with its own harness.
+- Parent-control repository model: one parent control repository owns the harness, while child repositories hold implementation facts.
+
+## Quick Choice
+
+| Model | Fits | Does not fit | Harness source of truth |
+| --- | --- | --- | --- |
+| Single repo | One product, one code repository, clear team boundary | A system already split across independently released repositories | Current repo `AGENTS.md` + `docs/` |
+| Independent multi-repo | Frontend, backend, SDK, or services evolve independently and cross-repo work is rare | Frequent cross-repo features and one shared release plan | Each repo's own `AGENTS.md` + `docs/` |
+| Parent-control repo | Microservices, many subsystems, shared roadmap, cross-repo releases, agents need one startup point | Small projects or short-lived script repositories | Parent repo `AGENTS.md` + `docs/` |
+
+## Single-Repo Model
+
+The single-repo model is the simplest. Code, plans, regression state, and walkthroughs live in one repository.
+
+```text
+product-repo/
+  AGENTS.md
+  docs/
+    03-ARCHITECTURE/
+    04-DEVELOPMENT/
+    05-TEST-QA/
+    09-PLANNING/
+    10-WALKTHROUGH/
+    11-REFERENCE/
+  src/
+  tests/
+```
+
+The agent starts at the repository root, reads `AGENTS.md`, then moves into task files and code.
+
+### When To Choose It
+
+- The application, service, script, or library is in one repository.
+- A feature usually modifies only this repository.
+- Regression commands can run inside one checkout.
+- The team wants to adopt Harness quickly without first changing repository structure.
+
+### Risk
+
+When the project later splits into several repositories, the single-repo harness can lose global visibility. Frontend, backend, and SDK repositories may each have local state, but no single place explains whether the cross-repo task is actually complete.
+
+## Independent Multi-Repo Model
+
+The independent multi-repo model gives each repository its own harness.
+
+```text
+frontend-repo/
+  AGENTS.md
+  docs/
+
+backend-repo/
+  AGENTS.md
+  docs/
+
+sdk-repo/
+  AGENTS.md
+  docs/
+```
+
+Each repository entrypoint only governs that repository. Frontend tasks are planned and closed in the frontend repo. Backend tasks are planned and closed in the backend repo.
+
+### When To Choose It
+
+- The repositories are genuinely independent from an organizational point of view.
+- Each repository has its own owners, release cadence, and review rules.
+- Cross-repo tasks are rare, or humans coordinate them manually.
+- One repository's harness should not know another repository's internal state.
+
+### Required External Context
+
+Independent multi-repo mode is not just "copy the template into every repo." If you do that, cross-repo context disappears.
+
+Each repository should document its external boundary in:
+
+- `docs/03-ARCHITECTURE/`: where this repository sits in the overall system.
+- `docs/04-DEVELOPMENT/`: sibling repo dependencies and local integration startup.
+- `docs/06-INTEGRATIONS/`: APIs, events, SDKs, queues, databases, auth, and other contracts.
+- `docs/05-TEST-QA/Regression-SSoT.md`: which checks cover this repository only and which require integration across repositories.
+- `AGENTS.md`: whether agents should stop, switch repositories, or ask humans when a task crosses repository boundaries.
+
+### Risk
+
+The risk is harness fragmentation:
+
+- The frontend local task state says a task is complete while the backend Regression SSoT is still red.
+- An SDK breaking change is not projected into the product shell.
+- An agent starts from a child repository, sees only local facts, and incorrectly treats the global task as complete.
+
+If this happens often, move to the parent-control repository model.
+
+## Parent-Control Repository Model
+
+The parent-control model puts the harness in a parent repository. Child repositories hold implementation facts.
+
+```text
+product-control-repo/
+  AGENTS.md
+  docs/
+    03-ARCHITECTURE/
+    04-DEVELOPMENT/
+    05-TEST-QA/
+    06-INTEGRATIONS/
+    09-PLANNING/
+    10-WALKTHROUGH/
+    11-REFERENCE/
+  tools/
+  frontend/   -> child repository
+  backend/    -> child repository
+  sdk/        -> child repository
+  service-a/  -> child repository
+  service-b/  -> child repository
+```
+
+The parent repository is the control plane. It owns:
+
+- Overall architecture and repo topology.
+- Cross-repo task lifecycle Ledger.
+- Delivery SSoT when release or block orchestration is needed.
+- Task plans, reviews, and walkthroughs.
+- Regression SSoT and cross-repo cadence.
+- Agent entrypoint and reading matrix.
+- Evidence for child repository commits, branches, submodule pointers, or release versions.
+
+Child repositories are the execution plane. They own:
+
+- Code implementation.
+- Repository-local dependencies and lockfiles.
+- Repository-local tests and CI.
+- Repository-local `AGENTS.md`.
+- Concrete commits and pull requests.
+
+### When To Choose It
+
+- One product is delivered by multiple repositories.
+- Features often touch frontend, backend, SDKs, or services together.
+- You want every agent to start from one entrypoint.
+- You need unified task state, review gates, and release closeout.
+- There are many services, and you cannot let each repository maintain its own global plan.
+
+### Main Benefit
+
+The parent-control model fixes global truth in one place. Even if there are 100 child repositories, the agent first reads the parent task contract, then enters the specific child repository to execute.
+
+This avoids:
+
+- Conflicting handwritten task lifecycle tables.
+- Each child repo saying "done" while the release still cannot ship.
+- Agents starting from the wrong repository and seeing only local context.
+- Cross-repo review and regression evidence scattered across many places.
+
+See `docs-release/guides/parent-control-repository-pattern.en-US.md` for the full method.
+
+## Moving Between Models
+
+### Single Repo To Multi-Repo
+
+When a single repository splits into frontend, backend, or SDK repositories, do not copy the same `docs/` tree into every repository.
+
+Decide first:
+
+- Which tasks remain global?
+- Which tasks become repository-local?
+- Does the old Regression SSoT stay at a parent layer or split into local gates?
+- Where should agents start in the future?
+
+If cross-repo features remain common, create a parent-control repository.
+
+### Independent Multi-Repo To Parent-Control
+
+Migration order:
+
+1. Create the parent `AGENTS.md` and repo topology.
+2. Move global Harness Ledger, Delivery SSoT, Regression SSoT, and walkthrough index into the parent repository.
+3. Keep local `AGENTS.md` files in child repositories, but point global planning back to the parent.
+4. Create new cross-repo tasks only in the parent repository.
+5. Treat child repository commits as evidence for parent tasks.
+
+Do not rewrite all historical tasks at once. Start by moving the current release and active features into the parent repository.
+
+## Recommended Defaults
+
+- New small project: single-repo model.
+- Several strongly independent teams: independent multi-repo model.
+- One product, multiple code repositories, one release target: parent-control model.
+- Many microservices that need unified agent collaboration: parent-control model.
+
+The real decision is not the number of repositories. It is whether global decisions need one source of truth.

package/docs-release/guides/repository-operating-models.md

@@ -0,0 +1,197 @@
+# 仓库运行模式选择指南
+
+English mirror: `docs-release/guides/repository-operating-models.en-US.md`
+
+Coding Agent Harness 可以落在不同的仓库组织方式里。选择错了，后面最常见的问题不是“文档少”，而是 Harness 自己变成新的混乱源。
+
+这份指南解释三种常见模式：
+
+- 单仓模式：一个代码仓库，一套 Harness。
+- 多仓独立模式：多个代码仓库，每个仓库有自己的 Harness。
+- 主控仓库模式：一个父级控制仓库管理 Harness，多个子仓库只承载代码执行事实。
+
+## 快速选择
+
+| 模式 | 适合 | 不适合 | Harness 事实源 |
+| --- | --- | --- | --- |
+| 单仓模式 | 单产品、单代码仓库、团队边界清楚 | 已经拆成多个独立发布仓库 | 当前仓库 `AGENTS.md` + `docs/` |
+| 多仓独立模式 | 前端、后端、SDK 等仓库长期独立迭代，跨仓任务少 | 大量跨仓 feature 和统一 release 计划 | 每个仓库自己的 `AGENTS.md` + `docs/` |
+| 主控仓库模式 | 微服务、多子系统、多仓统一路线图、跨仓 release、Agent 需要从一个地方启动 | 小项目，或只有一个短期脚本仓库 | 父仓库 `AGENTS.md` + `docs/` |
+
+## 单仓模式
+
+单仓模式最简单。代码、计划、回归、walkthrough 都在同一个仓库里。
+
+```text
+product-repo/
+  AGENTS.md
+  docs/
+    03-ARCHITECTURE/
+    04-DEVELOPMENT/
+    05-TEST-QA/
+    09-PLANNING/
+    10-WALKTHROUGH/
+    11-REFERENCE/
+  src/
+  tests/
+```
+
+Agent 从仓库根目录启动，读 `AGENTS.md`，然后进入任务文件和代码。
+
+### 什么时候选
+
+- 应用、服务、脚本或库都在一个仓库里。
+- Feature 通常只改这个仓库。
+- 回归命令可以在一个 checkout 内完成。
+- 团队希望快速接入 Harness，不想先改组织结构。
+
+### 风险
+
+当项目后来拆出多个仓库时，单仓 Harness 容易失去全局视野。前端、后端、SDK 各自都有状态，但没有一个地方能说明跨仓任务到底完成到哪一步。
+
+## 多仓独立模式
+
+多仓独立模式让每个仓库都有自己的 Harness。
+
+```text
+frontend-repo/
+  AGENTS.md
+  docs/
+
+backend-repo/
+  AGENTS.md
+  docs/
+
+sdk-repo/
+  AGENTS.md
+  docs/
+```
+
+每个仓库的 Agent 入口只管本仓库。前端任务在前端仓库计划和收口，后端任务在后端仓库计划和收口。
+
+### 什么时候选
+
+- 仓库之间组织上确实独立。
+- 每个仓库有自己的 owner、release 节奏和 review 规则。
+- 跨仓任务少，或者跨仓任务由人手动协调。
+- 某个仓库的 Harness 不应该知道另一个仓库的内部状态。
+
+### 必须补的外围文档
+
+多仓独立模式不能只给每个仓库复制一套模板。否则跨仓上下文会断。
+
+每个仓库至少要在这些位置写清楚外部边界：
+
+- `docs/03-ARCHITECTURE/`：本仓库在整体系统中的位置。
+- `docs/04-DEVELOPMENT/`：依赖哪些 sibling repo、本地联调怎么启动。
+- `docs/06-INTEGRATIONS/`：API、事件、SDK、队列、数据库、鉴权等外部契约。
+- `docs/05-TEST-QA/Regression-SSoT.md`：哪些检查只覆盖本仓库，哪些需要跨仓联调。
+- `AGENTS.md`：遇到跨仓任务时，Agent 应该停下来、切仓库，还是交给人协调。
+
+### 风险
+
+多仓独立模式的风险是 Harness 分裂：
+
+- 前端局部任务状态认为任务完成，后端 Regression SSoT 仍是红灯。
+- SDK 的 breaking change 没有投影到产品 shell。
+- Agent 从子仓库启动后，只看到局部事实，误以为全局任务已经结束。
+
+如果这种情况频繁发生，应升级到主控仓库模式。
+
+## 主控仓库模式
+
+主控仓库模式把 Harness 放在父仓库。子仓库只承载代码执行事实。
+
+```text
+product-control-repo/
+  AGENTS.md
+  docs/
+    03-ARCHITECTURE/
+    04-DEVELOPMENT/
+    05-TEST-QA/
+    06-INTEGRATIONS/
+    09-PLANNING/
+    10-WALKTHROUGH/
+    11-REFERENCE/
+  tools/
+  frontend/   -> child repository
+  backend/    -> child repository
+  sdk/        -> child repository
+  service-a/  -> child repository
+  service-b/  -> child repository
+```
+
+父仓库是 control plane。它管理：
+
+- 总体架构和 repo topology。
+- 跨仓任务生命周期 Ledger。
+- Delivery SSoT（需要 release / block 编排时）。
+- 任务计划、review、walkthrough。
+- Regression SSoT 和跨仓 cadence。
+- Agent 启动入口和读文件矩阵。
+- 子仓库 commit、分支、submodule pointer 或 release version 的证据。
+
+子仓库是 execution plane。它们管理：
+
+- 代码实现。
+- 本仓库依赖和 lockfile。
+- 本仓库局部测试和 CI。
+- 本仓库局部 `AGENTS.md`。
+- 具体提交和 PR。
+
+### 什么时候选
+
+- 一个产品由多个仓库共同交付。
+- Feature 经常跨前端、后端、SDK、微服务。
+- 你希望 Agent 永远从同一个入口启动。
+- 你需要统一的任务状态、review 门禁和 release closeout。
+- 微服务数量很多，不能让每个仓库各自维护一套全局计划。
+
+### 核心好处
+
+主控仓库模式把“全局事实”固定在一个地方。即使有 100 个子仓库，Agent 也先读父仓库的任务合同，然后再进入具体子仓库执行。
+
+这能避免：
+
+- 多个手写任务生命周期表互相冲突。
+- 每个子仓库都声称自己已经完成，但 release 仍不能发。
+- Agent 从错误仓库启动，只看到局部上下文。
+- 跨仓 review 和 regression 证据散落在不同地方。
+
+完整方法见 `docs-release/guides/parent-control-repository-pattern.md`。
+
+## 从一种模式迁移到另一种
+
+### 单仓到多仓
+
+当一个单仓拆出前端、后端、SDK 时，不要直接复制 `docs/` 到每个仓库。
+
+先决定：
+
+- 哪些任务仍是全局任务？
+- 哪些任务变成子仓库局部任务？
+- 原来的 Regression SSoT 是保留在父层，还是拆成局部 gate？
+- Agent 未来从哪里启动？
+
+如果跨仓 feature 仍然很多，优先创建主控仓库。
+
+### 多仓独立到主控仓库
+
+迁移顺序：
+
+1. 创建父仓库 `AGENTS.md` 和 repo topology。
+2. 把全局 Harness Ledger、Delivery SSoT、Regression SSoT、walkthrough index 收到父仓库。
+3. 子仓库保留局部 `AGENTS.md`，但把全局计划指向父仓库。
+4. 新跨仓任务只在父仓库创建 task。
+5. 子仓库提交只作为父任务的 evidence。
+
+不要一次性重写所有历史任务。先把当前 release 和活跃 feature 接到父仓库。
+
+## 推荐默认值
+
+- 新的小项目：单仓模式。
+- 已经有多个强独立团队：多仓独立模式。
+- 一个产品、多个代码仓库、一个 release 目标：主控仓库模式。
+- 微服务很多但需要统一 Agent 协作：主控仓库模式。
+
+真正的判断标准不是仓库数量，而是全局决策是否需要一个唯一事实源。