docs(agents): add host contribution guide

AGENTS.md

@@ -3,6 +3,8 @@
 Cross-platform support is required (Windows, macOS, Linux).
 Architecture, directory routing, and template ownership live in
 [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).
+Adding support for a new Coding Agent host starts with
+[docs/adapters/contributing-new-coding-agent.md](docs/adapters/contributing-new-coding-agent.md).
 
 ## Plan & Spec
 

CONTRIBUTING.md

@@ -17,6 +17,8 @@ it and agree that it may be distributed under the repository's [MIT License](LIC
 - Read [Architecture Principles](docs/ARCHITECTURE.md) and the root
   [agent instructions](AGENTS.md) before changing ownership boundaries or
   runtime behavior.
+- Follow [Contributing a New Coding Agent Host](docs/adapters/contributing-new-coding-agent.md)
+  before adding or widening host support.
 
 Small, focused fixes can go directly to a pull request. Open an issue first when
 the change affects public behavior, schemas, report contracts, packaging,
@@ -67,6 +69,11 @@ Executable behavior, host adapters, models, hooks, packaging, and report
 contracts have additional owner and evidence requirements. Follow the complete
 extensibility matrix instead of adding a parallel implementation.
 
+For a Coding Agent host, use the dedicated
+[host contribution guide](docs/adapters/contributing-new-coding-agent.md). It
+separates shell, configured-asset, session, output, and packaging claims so a
+host can land partial support without overstating its coverage.
+
 ## Plan the Change
 
 For non-trivial behavior, hook, Skill, template, adapter, report, or review-flow

README.md

@@ -351,7 +351,7 @@ smallest surface that matches the improvement you want to make:
 | --- | --- | --- |
 | Workflow guidance and engineering practices | [`skills/`](skills/) or [`references/`](references/) | Add sourced guidance for a language, framework, review pattern, or recurring agent workflow. |
 | Review models and executable analysis | [`models/`](models/) or [`scripts/`](scripts/) | Add an evidence-backed review lens, detector, or agent-friendly analysis command with fixtures and tests. |
-| Delivery controls and host support | [`hooks/`](hooks/) or the [host adapter matrix](docs/adapters/README.md) | Add a narrow lifecycle check or document and validate evidence support for another coding-agent host. |
+| Delivery controls and host support | [`hooks/`](hooks/) or the [new Coding Agent guide](docs/adapters/contributing-new-coding-agent.md) | Add a narrow lifecycle check or document and validate evidence support for another Coding Agent host. |
 | Reports and visual language | [`templates/reporting/`](templates/reporting/) or [`templates/style/`](templates/style/) | Add a report mode, reusable reporting contract, or directive-only visual style with validation evidence. |
 | Examples and operating models | [`case-studies/`](case-studies/) | Share a redacted, evidence-bounded example of how a team applies agent review and delivery practices. |
 
@@ -361,9 +361,12 @@ To get started:
    owner and understand its contract.
 2. Follow the [contribution guide](CONTRIBUTING.md) to set up the project and
    scope the change.
-3. Add tests, fixtures, or preview evidence when the contribution changes
+3. For host support, follow the
+   [new Coding Agent contribution guide](docs/adapters/contributing-new-coding-agent.md)
+   and update the [host adapter matrix](docs/adapters/README.md).
+4. Add tests, fixtures, or preview evidence when the contribution changes
    runtime behavior or rendered output.
-4. Open a focused pull request that explains what changed, why, and how it was
+5. Open a focused pull request that explains what changed, why, and how it was
    validated.
 
 Not sure where an idea belongs? [Open an issue](https://github.com/QoderAI/better-harness/issues)

README.zh-CN.md

@@ -338,16 +338,18 @@ Canvas 预览需要已安装的 Qoder 运行时，或显式指定 `--sdk-media`/
 | --- | --- | --- |
 | 工作流指导与工程实践 | [`skills/`](skills/) 或 [`references/`](references/) | 为某种语言、框架、审查模式或重复出现的智能体工作流添加有来源支撑的指南。 |
 | 审查模型与可执行分析 | [`models/`](models/) 或 [`scripts/`](scripts/) | 添加由证据支持的审查视角、检测器，或带 fixture 和测试的智能体友好分析命令。 |
-| 交付控制与宿主支持 | [`hooks/`](hooks/) 或[宿主适配器矩阵](docs/adapters/README.md) | 添加范围明确的生命周期检查，或记录并验证另一种编码智能体宿主的证据支持情况。 |
+| 交付控制与宿主支持 | [`hooks/`](hooks/) 或[新增 Coding Agent 指南](docs/adapters/contributing-new-coding-agent.md) | 添加范围明确的生命周期检查，或记录并验证另一种 Coding Agent 宿主的证据支持情况。 |
 | 报告与视觉语言 | [`templates/reporting/`](templates/reporting/) 或 [`templates/style/`](templates/style/) | 添加报告模式、可复用的报告契约，或带验证证据的纯指令式视觉样式。 |
 | 示例与运行模型 | [`case-studies/`](case-studies/) | 分享经过脱敏且以证据为边界的示例，展示团队如何应用智能体审查与交付实践。 |
 
 开始贡献：
 
 1. 阅读[社区扩展地图](docs/community.md)，找到规范的归属位置并了解相应契约。
 2. 按照[贡献指南](CONTRIBUTING.md)设置项目并确定变更范围。
-3. 当贡献会改变运行时行为或渲染输出时，添加测试、fixture 或预览证据。
-4. 提交一个聚焦的 Pull Request，说明改了什么、为什么修改以及如何验证。
+3. 如需新增宿主支持，请遵循[新增 Coding Agent 贡献指南](docs/adapters/contributing-new-coding-agent.md)，
+   并更新[宿主适配器矩阵](docs/adapters/README.md)。
+4. 当贡献会改变运行时行为或渲染输出时，添加测试、fixture 或预览证据。
+5. 提交一个聚焦的 Pull Request，说明改了什么、为什么修改以及如何验证。
 
 不确定某个想法应该放在哪里？在创建新的顶层功能区，或修改公共报告、schema、打包或兼容性契约之前，
 请先[创建 issue](https://github.com/QoderAI/better-harness/issues)。

docs/adapters/README.md

@@ -5,6 +5,12 @@ host boundaries. Do not create `docs/adapters/claude-code.md`,
 `docs/adapters/codex.md`, `docs/adapters/qoder.md`, `docs/adapters/cursor.md`,
 or `docs/adapters/qwen.md` by default.
 
+Adding another host? Follow
+[Contributing a New Coding Agent Host](contributing-new-coding-agent.md) before
+editing the matrix. The guide separates shell, configured-asset, session,
+output, and packaging claims and links reviewed Qwen Code and GitHub Copilot
+pull requests as worked examples.
+
 Host differences enter only this matrix, capability-local configured-asset
 providers, real session-evidence adapters, and output modes. Canonical product
 judgment stays in `skills/`, `models/`, `references/`, `templates/`, and

docs/adapters/contributing-new-coding-agent.md

@@ -0,0 +1,233 @@
+# Contributing a New Coding Agent Host
+
+Adding a Coding Agent is not one manifest or one transcript parser. It is a set
+of independently evidenced support claims: native discovery, configured assets,
+session evidence, shared workflow activation, output routing, and packaging.
+Implement only the slices the host can support, and mark every other slice as
+partial or unavailable.
+
+This guide is the canonical contribution workflow for a new host. Before editing,
+read the repository [agent instructions](../../AGENTS.md),
+[contribution guide](../../CONTRIBUTING.md),
+[architecture principles](../ARCHITECTURE.md),
+[directory ownership ADR](../adrs/directory-structure.md),
+[community extension map](../community.md), and
+[host adapter matrix](README.md). Current repository contracts take precedence
+over the worked pull requests at the end of this guide.
+
+## 1. Define the Support Claim
+
+Start with a dated spec under `docs/specs/` as required by `AGENTS.md`. Give each
+claimed slice a stable acceptance id and an evidence route. Use
+`[NEEDS CLARIFICATION: ...]` instead of guessing a host contract.
+
+| Slice | Decide explicitly | Canonical owner | Minimum evidence |
+| --- | --- | --- | --- |
+| Native contract | Host/version, primary source, supported lifecycle | Spec and PR evidence | Versioned official docs or host source |
+| Shell and discovery | Native manifest, source-local shell, generated shell, or none | Thin host metadata root; generated artifacts under `scripts/packaging/` | Native install/link/discovery smoke or unavailable note |
+| Configured assets | Available, partial, or unavailable scopes | `scripts/agent-customize/providers/<host>.mjs` | Sanitized fixtures plus bounded real-host inventory smoke |
+| Session evidence | Available, partial, or unavailable fields/events | `scripts/session-analysis/platforms/<host>.mjs` | Deterministic fixtures plus workspace-qualified source/facts smoke |
+| Shared registration | Which public commands accept the host | Capability-owned registries and CLIs | Help, unknown-host, delegation, and bundle tests |
+| Output | Existing Canvas, HTML, Markdown, or a justified new mode | `templates/reporting/` and report routing | Validated render for the claimed mode |
+| Packaging | npm metadata root, runtime bundle, source-only, or none | `package.json` and `scripts/npm-package/` | `npm run pack:verify` when shipped files change |
+| Documentation | Positioning, paths, coverage, smoke, limitations | [host adapter matrix](README.md) and capability references | Link checks and commands matching observed behavior |
+
+A shell does not prove configured-asset or session support. A session parser does
+not prove the Skill is natively discoverable. Do not register one slice merely
+to make another slice appear complete.
+
+## 2. Verify the Native Host Contract
+
+Do not derive a new host contract by renaming another adapter. Record the host
+version and primary evidence in the spec or pull request, then verify the parts
+that affect the proposed support:
+
+- the native manifest filename, schema, discovery order, install/link command,
+  and version rules;
+- configuration, runtime, cache, and session roots, including environment and
+  CLI override precedence;
+- workspace identity and path normalization for spaces, Unicode, punctuation,
+  Windows drive letters, case differences, symlinks, and case-insensitive file
+  systems;
+- trust, extension enablement, configuration precedence, and inline settings
+  that can add Skills, hooks, MCP servers, rules, or commands;
+- session event shape, call/result correlation, terminal statuses, unknown
+  event handling, compaction, subagent, permission, and usage fields;
+- privacy boundaries: which fields are required for evidence, which may contain
+  credentials or user content, and which must never leave the local machine.
+
+Use real host data only for a bounded local smoke. Commit deterministic,
+synthetic, and redacted fixtures; never commit raw transcripts, prompts,
+credentials, tokens, or machine-specific absolute paths.
+
+## 3. Keep the Host Shell Thin
+
+Add a host metadata root only when the native host needs one. The shell may own
+install and discovery metadata and pointers to canonical root Skills. It must
+not copy product judgment, scoring, evidence rules, or report contracts out of
+`skills/`, `models/`, `references/`, `templates/`, or capability-owned scripts.
+
+When the shell ships in the public package, align its version with the package,
+add it to the package whitelist and verifier, and prove native discovery with
+the actual host CLI. Generated host artifacts remain validation/install output;
+their canonical source belongs under `scripts/packaging/` after the matrix split
+triggers justify a builder.
+
+## 4. Add Configured-Asset Evidence
+
+A provider under `scripts/agent-customize/providers/` should:
+
+- keep Plugin, user, project, and inherited scopes distinct;
+- follow native precedence and effective enablement rather than only checking
+  whether a file or directory exists;
+- include native inline configuration sources when the host supports them;
+- honor documented CLI and environment overrides, including empty and malformed
+  values, without silently falling back to unrelated data;
+- emit metadata needed for review without serializing secret values or private
+  file contents;
+- remain deterministic and fail closed when identity, trust, or ownership is
+  ambiguous.
+
+Register the provider through its capability-owned index. Then trace the host id
+through every public inventory, lint, evidence-bundle, help, and report path that
+claims configured-asset support.
+
+## 5. Add Session Evidence Only When It Is Defensible
+
+A platform adapter under `scripts/session-analysis/platforms/` should qualify a
+session to the requested workspace before it can influence a report. Normalize
+only observed fields into the existing session contracts:
+
+- preserve or explicitly account for unknown events instead of silently
+  dropping them;
+- represent missing token usage or lifecycle fields as unobserved, not zero;
+- map cancelled, rejected, failed, and successful operations according to the
+  host's native states;
+- correlate calls and results with native ids and deterministic fallbacks;
+- deduplicate canonical paths and session identities without double-reading the
+  same file on a case-insensitive filesystem;
+- keep partial transcript, metadata, and audit coverage visible in output.
+
+If local sessions are unavailable, unstable, encrypted, or cannot be matched to
+the workspace safely, document session evidence as unavailable. Shell or asset
+support can still land independently.
+
+## 6. Propagate the Host Identity Deliberately
+
+Host ids currently appear in more than one capability because configured assets,
+sessions, reports, and packaging have different owners. Search for the existing
+host set before editing:
+
+```bash
+rg -n "qoder|codex|claude|cursor|qwen" scripts test references templates docs package.json
+```
+
+Use the results as an inventory, not a replacement template. Typical registration
+surfaces include:
+
+- `scripts/agent-customize/providers/index.mjs` and its public inventory CLI;
+- `scripts/session-analysis/analyzer.mjs` and the platform loader/help contract;
+- `scripts/harness-analysis/evidence-bundle/` provider validation and routing;
+- report, quality, lint, baseline, integrity, and root CLI help contracts that
+  explicitly enumerate supported hosts;
+- package whitelists and manifest-version checks, when a shell ships;
+- deterministic help snapshots and tests that intentionally lock the public
+  host list.
+
+Do not add the host to a registry unless the corresponding capability and its
+tests are present. Prefer a visible unsupported error over a host id that falls
+through to another provider.
+
+## 7. Build an Evidence Ladder
+
+Map tests to the spec acceptance ids. At minimum, cover the risks that apply to
+the host:
+
+| Risk | Fixture or check |
+| --- | --- |
+| Invented native contract | Pinned source/doc reference plus native CLI smoke |
+| Path mismatch | POSIX and Windows paths, spaces, Unicode, punctuation, case, symlink/canonical identity |
+| Wrong home or precedence | CLI override, environment override, default, empty, and malformed cases |
+| Foreign workspace evidence | Positive and negative workspace qualification fixtures |
+| Lost or inflated events | Unknown events, missing fields, call/result correlation, every terminal status |
+| Duplicate evidence | Canonical-path and case-insensitive deduplication fixture |
+| Secret leakage | Credential-shaped fixture with value-level non-disclosure assertions |
+| Packaging drift | Manifest presence/version assertions and `npm run pack:verify` |
+
+During development, run focused provider, session, manifest, bundle, and CLI
+tests. Before review, run the full repository suite. When Markdown is added or
+moved, regenerate and verify the link graph:
+
+```bash
+node scripts/doc-link-graph/cli.mjs skills/better-harness
+node --test test/doc-link-graph.test.mjs
+npm test
+npm run pack:verify
+git diff --check
+```
+
+Run `npm ci` and `npm run build` from `docs/` when the published site changes.
+CI must cover Windows, macOS, and Linux for cross-platform paths or filesystem
+behavior. A real-host smoke should separately prove native discovery, configured
+assets, session source/facts when claimed, evidence-bundle propagation, and a
+validated report render. Record unavailable checks honestly.
+
+## 8. Document and Review the Delivered Boundary
+
+Update the [host adapter matrix](README.md) with positioning, shell, configured
+assets, session evidence, default output, rules/prompts, and a reproducible smoke
+route. Add or update capability references for host-specific paths and evidence
+limits. Add README installation instructions only after the native command has
+been verified. Use a host-specific adapter page only when the matrix's split
+triggers are met.
+
+Before commit or review, use the
+[Change Traceability Review](../../.agents/skills/change-traceability-review/SKILL.md)
+in Review Readiness Check mode. The pull request should state:
+
+- the host/version and primary contract evidence;
+- the claimed and unavailable support slices;
+- spec and acceptance ids, changed canonical owners, and explicit non-goals;
+- exact focused, full-suite, native-smoke, cross-platform, and packaging results;
+- privacy, compatibility, generated-file, rollback, and residual risks;
+- AI involvement and the human verification performed.
+
+Use the repository [pull request template](../../.github/pull_request_template.md).
+Do not infer Story ids, AI involvement, CI status, or native compatibility from
+branch names, prose, passing synthetic tests, or similarity to another host.
+
+## Worked Pull Request Examples
+
+These examples are review material, not templates to copy verbatim. Re-check
+their latest diff and status before citing them.
+
+- [PR #6: Qwen Code host adapter](https://github.com/QoderAI/better-harness/pull/6)
+  shows why native source verification matters. Its review and follow-ups cover
+  manifest identity, config/runtime roots, path sanitization, effective
+  enablement, inline MCP/hooks, terminal statuses, environment precedence,
+  credential boundaries, and case-insensitive filesystem deduplication. The key
+  lesson is that a green suite can consistently encode the wrong host contract.
+- [PR #22: GitHub Copilot as a first-class host](https://github.com/QoderAI/better-harness/pull/22)
+  shows a spec-led decomposition across shell, configured assets, sessions,
+  shared registries, docs, and fixtures. Its evidence model keeps missing usage
+  fields explicit, rejects foreign-workspace sessions, and accounts for unknown
+  event types. Because review can change the PR, treat it as an evolving example,
+  not proof that a capability is merged or released.
+
+## Definition of Done
+
+- [ ] The spec names each claimed, partial, and unavailable support slice.
+- [ ] Native host/version evidence backs every discovery and data-layout claim.
+- [ ] Shell metadata is thin and independently smoke-tested when present.
+- [ ] Configured assets and sessions keep scopes, workspace identity, and private
+  data boundaries explicit.
+- [ ] Registration matches implemented capabilities; no unrelated host fallback
+  is possible.
+- [ ] Deterministic fixtures cover applicable path, precedence, status, dedupe,
+  foreign-workspace, unknown-event, and secret-boundary risks.
+- [ ] Focused, full-suite, cross-platform, native-smoke, documentation, and
+  packaging results are recorded accurately.
+- [ ] The matrix, capability references, installation docs, and published site
+  match the behavior actually delivered.
+- [ ] The Review Readiness Check finds a coherent Story/Spec/Test/Risk chain and
+  a clean staged/unstaged split.