trae-coding-engine 0.1.0

package/templates/.agents/skills/coding-release-merge/SKILL.md

@@ -0,0 +1,224 @@
+---
+name: coding-release-merge
+description: Use when merging the latest release branch into the current coding_engine feature branch, resolving conflicts, and reconciling newly introduced shared conventions such as API contracts, error handling rules, common helpers, config patterns, or cross-cutting refactors across both sides of the merge.
+---
+
+# coding-release-merge: Merge Latest Release Safely
+
+用于把最新 release 分支合入当前工作分支。重点不是只解决文本冲突，而是识别 release 新增的通用逻辑变化，并把当前分支和 release 侧代码都拉到同一套规范上。
+
+## Trigger
+
+用户要求“合并 release / 拉最新 release / merge 最新发布分支 / 同步 release 代码 / rebase release 分支代码”时加载。
+
+如果 merge 涉及测试、HTTP API、部署配置、DB schema、runtime adapter 等路径，继续加载 `AGENTS.md` Skill Router 中对应的领域 skill。任何代码修改仍触发 `coding-testing`。
+
+## Non-Negotiables
+
+- 不要在未确认干净工作区前开始 merge；已有用户改动必须保护。
+- 默认使用 `git merge --no-ff --no-commit`，即使没有文本冲突，也先执行通用逻辑巡检和测试，再决定提交。
+- 不要用 `git reset --hard`、`git checkout -- <file>`、`git restore <file>` 丢弃用户改动，除非用户明确要求。
+- 冲突解决不能只选择 ours/theirs；必须读双方意图，保留 release 的通用规范变更和当前分支的业务增量。
+- 每个通用逻辑变化都要做“双向巡检”：release 新规范是否被当前分支违背；当前分支若本身在改通用规范，release 新代码是否违背。
+
+## Workflow
+
+### 1. Preflight
+
+确认仓库状态和当前分支：
+
+```bash
+git status --short
+git branch --show-current
+git rev-parse --show-toplevel
+```
+
+如果工作区不干净：
+
+- 用户改动与 merge 无关：建议用户先 stash/commit；不要替用户丢弃。
+- 用户改动正是本任务的一部分：继续前记录哪些文件已有改动，后续不要误判为 merge 产物。
+
+### 2. Fetch and Select Release Ref
+
+拉取远端 release 分支：
+
+```bash
+git fetch --prune origin
+git for-each-ref --sort=-committerdate --format='%(refname:short) %(committerdate:iso8601)' 'refs/remotes/origin/release*'
+```
+
+选择规则：
+
+- 用户指定了 release ref：使用用户指定值。
+- 存在单一集成分支 `origin/release`：默认使用它。
+- 存在多个 `origin/release/*` 或 `origin/release-*`：选择 fetch 后 committerdate 最新的 release ref，并在回复中说明具体 ref。
+- 无 release ref：停止并要求用户指定。
+
+记录 merge 前锚点：
+
+```bash
+BASE_HEAD=$(git rev-parse HEAD)
+RELEASE_REF=<selected-release-ref>
+RELEASE_TIP=$(git rev-parse "$RELEASE_REF")
+MERGE_BASE=$(git merge-base HEAD "$RELEASE_REF")
+```
+
+### 3. Inspect Incoming Release Changes
+
+先看新拉下来的 commit message 和真实 diff，不要只依赖标题：
+
+```bash
+git log --oneline --decorate --no-merges "$MERGE_BASE..$RELEASE_REF"
+git diff --stat "$MERGE_BASE..$RELEASE_REF"
+git diff --name-only "$MERGE_BASE..$RELEASE_REF"
+```
+
+对可疑提交继续看细节：
+
+```bash
+git show --stat <commit>
+git show --name-only <commit>
+git show <commit> -- <path>
+```
+
+重点识别这些后端“通用逻辑变化”信号：
+
+- API/IDL/handler contract：字段必选性、错误码、Action/Version、鉴权、TOP response envelope、`base.Error` 映射。
+- 指针处理：`ptr.Of` / `ptr.To`、optional field、nil vs zero value、clone pointer、`optionalString` / `stringValue` / `cloneUUIDPtr` 等局部 helper。
+- 分页处理：`PageInput` / `PageOutput`、`shared.PageRequest` / `shared.PageResult`、`NormalizePage`、`paginateCount`、`normalizedLimit`、offset/limit 默认值。
+- request context：`requestctx.*FromContext`、`requestctx.With*`、rdb repository `rdb.DB(ctx, ...)` / `conn(ctx)`、`AgentIdentityFromContext`、tenant/workspace/user/action/version 解析规则。
+- 错误处理规范：`errno.Ensure`、`errno.Wrap`、`errno.NewWithMessage`、dependency 分类 helper、状态码映射、handler 的 `toHTTPError`。
+- 参数校验：`validate.Struct` / `validate.Required`、handler/application 局部 `invalid`、`requiredUUID`、`validateScope`、K8s quantity / JSON config validation。
+- UUID / ID：`pkg/platform/uuid` 的 `New` / `Parse` / `MustParse` / `IsZero` / `Unique`，以及 UUID 字符串转换 helper。
+- logger / observability context：`logger.WithContextFields`、`logger.ContextFields`、`logger.String` / `logger.Err` 等 field helper，metrics/log 语义变化。
+- retry/backoff：`retry.Do`、`retry.Permanent`、attempts/ctx deadline、transient vs permanent error 分类。
+- config / DB normalize：`config.LoadYAML` strict decode、`gormdb.NormalizeConfig`、`NormalizeType`、`Endpoint`、DSN/parameter/default port 规则。
+- mapper / clone / conversion：RDB mapper、`MapSlice`、DTO/domain/PO conversion、`rawJSON` / `rawJSONPtr`、slice/map/json/time clone 与 formatting helper。
+- 命名/资源名规范：`shared.NormalizeName`、Hermes/K8s `SanitizeName` / `InstanceName` / `SecretName` / `LabelValue`、label/resource length 限制。
+- 架构边界：port/interface 变化、ServiceDeps、fx wiring、adapter contract。
+- 配置/部署规范：Secret vs ConfigMap、DSN、probe/service port、默认值、镜像字段。
+- 数据/持久化规范：GORM PO、AutoMigrate owner、soft delete、repository parity、transaction context。
+- 测试规范：mock 生成、table-driven pattern、race/miniredis/testcontainers 约束。
+
+产出一个短清单：
+
+```markdown
+Incoming shared changes:
+- <commit/path>: <inferred rule> -> <affected local search terms>
+```
+
+常用搜索入口：
+
+```bash
+rg 'ptr\.Of|ptr\.To|optionalString|stringValue|clone.*Ptr|nil \|\| .*IsZero' internal pkg --glob '*.go'
+rg 'PageInput|PageOutput|PageRequest|PageResult|NormalizePage|paginateCount|normalizedLimit|Offset\(|Limit\(' internal pkg --glob '*.go'
+rg 'FromContext|With.*Context|rdb\.DB\(ctx|conn\(ctx\)|AgentIdentityFromContext|TenantID|WorkspaceID|UserFromContext' internal pkg --glob '*.go'
+rg 'errno\.Ensure|errno\.Wrap|errno\.NewWithMessage|toHTTPError|ErrInvalidArgument|ErrPersistenceError' internal pkg --glob '*.go'
+rg 'validate\.Struct|validate\.Required|requiredUUID|validateScope|invalid\(' internal pkg --glob '*.go'
+rg 'uuid\.New|uuid\.Parse|uuid\.MustParse|uuid\.IsZero|uuid\.Unique' internal pkg --glob '*.go'
+rg 'logger\.WithContextFields|logger\.ContextFields|logger\.(String|Err|Int|Bool|Any)' internal pkg --glob '*.go'
+rg 'retry\.Do|retry\.Permanent|NormalizeConfig|LoadYAML|MapSlice|rawJSON|cloneString|SanitizeName|InstanceName|SecretName|LabelValue' internal pkg --glob '*.go'
+```
+
+### 4. Merge Without Committing
+
+```bash
+git merge --no-ff --no-commit "$RELEASE_REF"
+```
+
+如果出现冲突：
+
+```bash
+git status --short
+git diff --name-only --diff-filter=U
+git diff --cc -- <conflicted-path>
+```
+
+解决顺序：
+
+1. 先解决接口、domain/application contract、config/schema 这类上游约束。
+2. 再解决 adapters/bootstrap/web 这类下游适配。
+3. 最后解决测试、文档、生成物。
+
+每个冲突文件都要回答：
+
+- release 侧是否引入了新规范？
+- 当前分支的业务改动是否还成立？
+- 合并结果是否同时满足新规范和当前分支目标？
+
+### 5. Shared Logic Reconciliation
+
+这是本 skill 的核心检查。
+
+#### A. Release introduced shared rule
+
+如果 `MERGE_BASE..RELEASE_REF` 中包含通用逻辑变化，对当前分支新增/修改代码做 targeted grep：
+
+```bash
+git diff --name-only "$MERGE_BASE..HEAD"
+rg '<old-helper|old-error-pattern|old-field|old-action|old-config-key>' <candidate-paths>
+rg '<new-helper|new-error-pattern|new-field|new-action|new-config-key>' <candidate-paths>
+```
+
+修复所有当前分支仍违背 release 新规范的地方。不要只修冲突文件；非冲突文件也可能违背。
+
+#### B. Current branch changes shared rule
+
+如果当前分支本来就在改通用逻辑，对 release 新引入代码做反向检查：
+
+```bash
+git diff --name-only "$MERGE_BASE..$RELEASE_REF"
+rg '<current-branch-new-rule-or-helper>' <release-touched-paths>
+rg '<deprecated-rule-or-helper>' <release-touched-paths>
+```
+
+修复 release 新代码中仍使用旧规范的地方，确保 merge 后整个工作树一致。
+
+#### C. Cross-layer consistency
+
+按变更面加载对应 skill 并执行其 gate：
+
+- API/handler/IDL：`coding-http-api`
+- tests：`coding-testing`
+- deploy/config/runtime config：`coding-deploy-config`
+- DB schema/GORM PO：`coding-db-schema`
+- runtime provider：`coding-runtime-adapter`
+- observability：`coding-observability`
+- domain/application/ports：`coding-architecture`
+
+若通用规则影响文档、API、配置或重要生命周期，执行 `AGENTS.md` Docs Verification Gate。
+
+### 6. Validation
+
+最少执行：
+
+```bash
+make test
+```
+
+按触发面追加：
+
+- IDL changed：`make gen-thrift`，再跑相关测试。
+- generated mocks changed：`make generate`，再跑相关测试。
+- skill changed：`make check-skills` 和 `make check-agent-md`。
+- deploy/config changed：按 `coding-deploy-config` 的渲染/grep gate。
+
+如果测试失败，先判断是否由 merge 结果或通用规范迁移造成；不要把失败简单归咎于 release。
+
+### 7. Final Report
+
+最终回复必须包含：
+
+- 使用的 release ref 和 tip commit。
+- 冲突文件列表，或说明无文本冲突。
+- 识别到的通用逻辑变化及采取的双向修复。
+- 运行过的验证命令和结果。
+- 是否已提交；默认未提交时说明 merge 处于待提交状态。
+
+如果需要提交，commit title 使用 repo whitelist scope，例如：
+
+```text
+merge: release into <branch>
+```
+
+或在发生实质修复时使用更具体的 conventional commit scope，例如 `fix:http-api`、`fix:config`、`refactor:runtime`。

package/templates/.agents/skills/coding-runtime-adapter/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: coding-runtime-adapter
+description: Use when adding a new runtime provider to coding_engine, modifying runtime adapter code under `internal/adapters/outbound/{hermes,workspacejob}/**`, or changing worker provider registry wiring.
+---
+
+# coding-runtime-adapter: Runtime Adapter Pattern
+
+## The Quad
+
+Every runtime provider is exactly four files in `internal/adapters/outbound/<name>/`:
+
+| File | Interface | Responsibility |
+|------|-----------|----------------|
+| `executor.go` | `runtime.AgentExecutor` | Prepare + Run + Cancel + Health |
+| `controller.go` | `runtime.RuntimeController` | K8s lifecycle (upsert/stop/delete/refresh/view) |
+| `apikey.go` / `token.go` | — | Credential cache backed by K8s Secret |
+| `discovery.go` | — | Derive HTTP/WS endpoint from tenantID+agentID (stateless) |
+
+Supporting files: `helpers.go`, `errors.go`, `statefulset_builder.go` or `crd.go`, `api_client.go` or `pool.go`.
+
+
+## Pattern Files (read when implementing each component)
+
+| Component | Pattern file |
+|-----------|-------------|
+| Executor | `.agents/skills/coding-runtime-adapter/patterns/p1-executor.md` |
+| Controller | `.agents/skills/coding-runtime-adapter/patterns/p2-controller.md` |
+| Credential Manager | `.agents/skills/coding-runtime-adapter/patterns/p3-credential-manager.md` |
+| Discovery | `.agents/skills/coding-runtime-adapter/patterns/p4-discovery.md` |
+
+## Templates (copy and adapt)
+
+| Need | Template |
+|------|----------|
+| Naming helpers (InstanceName, SecretName, SanitizeName) | `.agents/skills/coding-runtime-adapter/templates/helpers.go` |
+| CredentialManager with singleflight + RWMutex | `.agents/skills/coding-runtime-adapter/templates/credential_manager.go` |
+
+
+## Naming Helpers (quick ref)
+
+```go
+InstanceName(tenantID, agentID) → "xxx-<tenant>-<agent>"   // DNS-1123 safe
+SecretName(tenantID, agentID)   → "xxx-cred-<tenant>-<agent>"
+LabelValue(s)                   → truncated to 63 chars
+```
+
+Each adapter package is standalone — copy `helpers.go` into your package, don't import from hermes.
+
+
+## Deployment Config Sync Projection
+
+If a runtime adapter config struct or `RegistryConfig` mirror changes, load
+`coding-deploy-config` and reconcile the worker runtime surfaces there. Keep
+this skill focused on runtime mechanics, not Helm/YAML/Secret policy.
+
+
+## RegistryConfig Extension
+
+`internal/bootstrap/worker/registry.go`:
+```go
+type RegistryConfig struct {
+    Namespace              string
+    Hermes                 hermes.Config            // image + storage class + storage size
+    WorkspaceSync          runtime.WorkspaceSyncConfig
+    PlatformMCPTokenIssuer hermes.TokenIssuerConfig
+    // Xxx                 xxx.Config               // add per-provider config struct here
+}
+```
+
+Add `XxxImage` only when the provider needs a pinned image. Guard in `ProvideProviderRegistry`:
+```go
+if cfg.XxxImage == "" { return nil, fmt.Errorf("XxxImage is required") }
+```
+
+
+## Wiring Checklist (`bootstrap/worker/registry.go`)
+
+- [ ] Add `EngineKindXxx EngineKind = "xxx"` to `internal/domain/shared/enums.go`
+- [ ] Add `XxxImage string` to `RegistryConfig` if needed; add guard
+- [ ] Instantiate: `credMgr → discovery → client/pool → executor → controller`
+- [ ] `reg.Register(shared.EngineKindXxx, executor, controller)`
+
+```go
+xxxCredMgr  := xxx.NewCredManager(k8sClient, cfg.Namespace)
+xxxDiscovery := xxx.NewDiscovery(cfg.Namespace)
+xxxClient   := xxx.NewAPIClient()
+xxxExecutor := xxx.NewExecutor(xxxCredMgr, xxxDiscovery, xxxClient)
+xxxCtrl     := xxx.NewController(dynClient, k8sClient, cfg.Namespace, xxxCredMgr, xxxDiscovery, cfg.XxxImage)
+reg.Register(shared.EngineKindXxx, xxxExecutor, xxxCtrl)
+```
+
+
+## Existing Providers Quick Reference
+
+| | Hermes |
+|--|--------|
+| `EngineKind` | `"hermes"` |
+| Transport | HTTP SSE (`api_client.go` / `sse.go`) |
+| Workload | `StatefulSet` + `ClusterIP Service` |
+| Credential | `hermes-apikey-*` Secret |
+| `OnAgentStop` | scale replicas to 0 |
+| Port | 8642 (http) |
+| Image / storage in RegistryConfig | `Hermes hermes.Config` |
+
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| `Kind()` returns wrong string | Must equal `EngineKind` constant value exactly |
+| `Run()` skips type-assert on `p.Conn()` | Always assert; return `runtime.ErrInvalidPreparedRun` on failure |
+| Cache key uses only `agentID` | Must include `tenantID` — multiple tenants share one namespace |
+| Deleting K8s resources in wrong order | workload → Service → PVC → Secret |
+| `"latest"` as image tag in RegistryConfig | Guard with explicit empty-string check |
+| Forgetting `Evict` in `OnAgentDelete` | Causes credential leak across agent lifecycle |

package/templates/.agents/skills/coding-testing/SKILL.md

@@ -0,0 +1,169 @@
+---
+name: coding-testing
+description: Use when writing, reviewing, fixing, or running any test in coding_engine, including unit tests, integration tests, external-service manual checks, and deployed-environment coverage (E2E P0/P1/P2 smoke & regression, DFX stability/load, Eval quality). There is no QA team — Claude owns test correctness. Covers which strategy applies to each layer, required tooling, mandatory test run commands, and what "done" means before marking work complete.
+---
+
+# coding-testing: Testing Strategy (No QA — Claude Owns This)
+
+## THE RULE
+
+**There is no QA team. Every feature, fix, and refactor ships with tests. Work is not done until tests pass.**
+
+No exceptions. No "I'll add tests later." No "this is simple, it doesn't need tests."
+
+> **Deployed-system coverage:** Black-box TOP/HTTP coverage against a deployed
+> cluster lives under Strategy 6: `tests/e2e/` (P0/P1/P2 smoke & regression),
+> `tests/dfx/` (stability/load/QPS), and `tests/eval/` (chat quality). Shell
+> scenario suites have been retired — do not create new curl-based scenario
+> scripts for routine smoke or regression.
+>
+> **Repository gate fixtures:** `scripts/test/*.test.sh` files test CI /
+> repository-governance scripts, not product Go behavior. Run them with
+> `make test-scripts`; `make check` is the umbrella CI gate that includes them.
+> Do not wire `make test-scripts` into `make test`; keep `make test` focused on
+> `go test -race ./...`.
+>
+> **External service tests:** tests that call real third-party SaaS / OpenTOP / cloud services use `//go:build external` and files named `*_external_test.go`. They are manual developer checks only: run the specific package or test with `go test -tags=external ...` when credentials are available. Do not add a shared Make target, and do not wire them into CI, `make test`, or `make check`.
+
+
+## Step 1 — Identify your strategy
+
+First decide whether the test calls a real third-party service. If yes, use the
+`external` convention above (`//go:build external`, `*_external_test.go`, manual
+`go test -tags=external ...`). If the test calls a deployed coding cluster over
+TOP/HTTP (including E2E smoke/regression, DFX load/stability, or Eval quality),
+use Strategy 6 with the corresponding build tag (`e2e`, `dfx`, or `eval`). The
+numbered strategies below cover normal unit/integration tests; choose the
+narrowest one that proves the behavior.
+
+```
+New code in...                            → Strategy
+application/<domain>/service.go           → 1
+application/<domain>/                     → 1
+adapters/inbound/http/handlers/           → 4
+adapters/outbound/openclaw/               → 2
+adapters/outbound/llm/                    → 2
+application/evolution/acl/                → 1 (in-process cross-context ACL adapters, ADR 0058)
+adapters/outbound/runtimeregistry/        → 1
+adapters/outbound/speccatalog/            → 1 (config-backed in-memory spec catalog)
+adapters/outbound/up/                     → 2
+adapters/outbound/artifact/               → 2 (ArtifactServer SDK adapter tests with fake / httptest)
+adapters/outbound/arkskillhub/            → 2 (Ark Skill Hub HTTP adapter tests with fake / httptest)
+adapters/outbound/aigw/                   → 2 (AIGW SDK HTTP adapter tests with fake / httptest)
+adapters/outbound/clawsentry/             → 2 (ClawSentry adapter tests with fake / httptest; real service checks use external)
+adapters/outbound/hiagent/                → 2 (HiAgent HTTP TOP adapter tests with fake / httptest)
+adapters/outbound/mcp/                    → 2 (MCP client transports)
+adapters/outbound/<other-runtime>/        → 2
+adapters/outbound/hermes/                 → 2
+adapters/outbound/secretcodec/            → 2 (crypto-backed secret adapter)
+adapters/outbound/volcid/                 → 2 (Volcengine ID SDK adapter tests with fake / httptest)
+adapters/outbound/iam/                    → 2 (IAM SDK adapter tests with fake / httptest)
+adapters/outbound/workspacejob/           → 2 (Kubernetes Job helper)
+adapters/outbound/channels/               → 2 (HTTP integrations — feishu, wecom)
+adapters/outbound/media/                  → 2 (shared media utils — STT HTTP client, MIME/tag, inbound file processor)
+adapters/outbound/diagnostics/            → 2 (coding doctor checkers — rdb via injected openDB fake, redis via miniredis)
+adapters/outbound/metricquery/            → 2 (Prometheus-compatible HTTP query adapters with httptest)
+adapters/outbound/metrics/                → 2 (OTel/metrics outbound adapters with fake reader or httptest)
+adapters/outbound/echo/                   → 1 (in-process placeholder runtime)
+adapters/outbound/queue/                  → 3 (redisstreams — miniredis)
+adapters/outbound/eventbus/rediseventbus/ → 3
+adapters/outbound/messagebus/redismessagebus/ → 3
+adapters/outbound/presence/               → 3 (miniredis — Redis-backed presence registry, ADR 0018)
+adapters/outbound/gatewaypresence/        → 3 (miniredis — Redis ZSET live-instance set for the gateway multi-replica guard, ADR 0086)
+adapters/outbound/ownership/              → 3 (miniredis — Redis SSE-ownership registry + pub/sub backplane for the gateway ownership fabric, ADR 0086)
+adapters/outbound/sessionlease/           → 3 (miniredis — Redis-backed session lease + Lua scripts, ADR 0025)
+adapters/outbound/sessionkeylock/          → 3 (Redis-backed session key uniqueness lock, ADR 0069)
+adapters/outbound/lane/redislane/         → 3 (miniredis)
+adapters/outbound/redismsgbus/            → 3 (miniredis)
+adapters/outbound/lane/locallane/         → 1 (in-process channel)
+adapters/outbound/messagebus/localmsgbus/ → 1 (in-process channel)
+adapters/outbound/eventbus/localeventbus/ → 1 (in-process channel)
+adapters/outbound/messagebus/middleware/  → 1 (message bus middleware — debug log decorator)
+adapters/outbound/metering/               → 2 (HTTP push adapter)
+adapters/outbound/persistence/postgres/   → 5
+domain/<aggregate>/                       → 1
+pkg/platform/<util>/                      → 1
+pkg/platform/<util>/                      → 1
+bootstrap/                                → 1
+tests/e2e/                                → 6 (deployed-environment E2E; P0 owns smoke)
+tests/dfx/                                → 6 (deployed-environment DFX: stability/load/QPS)
+tests/eval/                               → 6 (deployed-environment Eval: chat quality)
+```
+
+## Step 2 — Copy the template (if scaffolding a new file)
+
+Do not write boilerplate from memory. Read and adapt the relevant template:
+
+| Need | Template |
+|------|----------|
+| New repository dependency mock | Add `//go:generate go run go.uber.org/mock/mockgen ...` on the domain repository interface and run `make generate` |
+| New `tests/integration/*_test.go` | `.agents/skills/coding-testing/templates/integration_test_setup.go` |
+| New `export_test.go` for white-box access | `.agents/skills/coding-testing/templates/export_test.go` |
+
+For integration tests, do not copy local DB / Redis container setup into the
+test file. The integration suite owns shared fixtures in
+`tests/integration/testutil/`; strategy 5 documents the required entry points.
+
+## Step 3 — Read the detail file
+
+After identifying your strategy, read the corresponding file:
+
+| Strategy | File |
+|----------|------|
+| 1 — App service unit tests | `.agents/skills/coding-testing/strategies/s1-app-services.md` |
+| 2 — K8s / HTTP adapter unit tests | `.agents/skills/coding-testing/strategies/s2-k8s-adapters.md` |
+| 3 — Redis adapter tests | `.agents/skills/coding-testing/strategies/s3-redis.md` |
+| 4 — HTTP handler tests | `.agents/skills/coding-testing/strategies/s4-http-handlers.md` |
+| 5 — Integration / persistence tests | `.agents/skills/coding-testing/strategies/s5-integration.md` |
+| 6 — Deployed-environment black-box (E2E/DFX/Eval) | `.agents/skills/coding-testing/strategies/s6-deployed-blackbox.md` |
+
+
+## Commands
+
+| Command | When |
+|---------|------|
+| `make test` | Always — `go test -race ./...` |
+| `make test-scripts` | When `scripts/**` or `scripts/test/**` changes — offline fixture/workflow regression tests for CI and repository gate scripts; also covered by `make check` |
+| `go test -tags=external ./<package> -run '<test regex>' -count=1` | Manual only, when intentionally validating one adapter against a real third-party service with local credentials |
+| `go test -tags=integration ./tests/integration/... -run '^$'` | Any `persistence/rdb` repository, GORM PO, repository constructor/mapper, or Redis-backed code change — proves integration tests still compile |
+| `go test -tags=integration ./tests/integration/<affected_file>_test.go -run '^$'` | Any integration test file changed — proves the file can be run directly without relying on sibling `_test.go` helpers |
+| `go test -tags=integration ./tests/integration/... -run '<affected test regex>' -count=1 -parallel=2` | Any database repository or Redis-backed behavior change — run the corresponding integration tests against real DB/Redis testcontainers |
+| `make test-e2e` | When validating deployed-environment TOP/HTTP behavior with `CODING_E2E_*` env configured |
+| `CODING_E2E_REQUIRE=1 CODING_E2E_PRIORITY=P0 go test -tags=e2e ./tests/e2e -count=1 -v` | Post-deploy smoke sweep and golden-path HTTP regression coverage |
+| `go test -tags=e2e ./tests/e2e -run '<affected test regex>' -count=1 -v` | Any changed or newly added E2E case |
+| `go test -tags=dfx ./tests/dfx -run '<test regex>' -count=1 -v` | Manual DFX stability/load/QPS run against a deployed environment |
+| `go test -tags=eval ./tests/eval -run '<test regex>' -count=1 -v` | Manual chat quality evaluation against a deployed environment |
+| `make generate` | When generated code or mocks need refresh |
+| `make gen-thrift` | When IDL changed |
+| `make check-skills` | When new `adapters/outbound/` package added |
+
+Generated mocks go next to their interfaces: domain repositories in `internal/domain/<agg>/mocks/`, application ports in `internal/application/port/mocks/`. Service tests should use generated mocks for repository dependencies.
+
+
+## Done Checklist
+
+- [ ] New code has tests (correct strategy applied)
+- [ ] `make test` passes, zero races
+- [ ] If `scripts/**` or `scripts/test/**` changed: `make test-scripts` passes; for CI gate scripts, `make check` remains the final umbrella gate
+- [ ] If a real third-party service contract changed: note whether the affected `*_external_test.go` was manually run with local credentials
+- [ ] If any rdb repository / PO / mapper / constructor / transaction helper changed: `make check-repository-transactions` passes
+- [ ] If database repository or Redis-backed code changed: integration tests compile and the affected integration tests pass; if Docker/testcontainers is unavailable, report that blocker explicitly
+- [ ] If an integration test file changed: the file compiles by itself with `go test -tags=integration ./tests/integration/<file>_test.go -run '^$'`
+- [ ] If deployed TOP/HTTP behavior, post-deploy smoke, HTTP regression, DFX, or Eval coverage changed: the corresponding Strategy 6 suite case(s) pass; P0 smoke uses `CODING_E2E_REQUIRE=1 CODING_E2E_PRIORITY=P0`; DFX/Eval runs use `-count=1`
+- [ ] If generated code changed: `make generate` and/or `make gen-thrift` run
+- [ ] Error paths tested, not just happy path
+- [ ] `t.Parallel()` on every unit test function
+
+
+## Common Mistakes
+
+| Mistake | Correct |
+|---------|---------|
+| Hand-written `fakeXXXRepository` in service tests | Use generated GoMock repository mocks |
+| testcontainers outside `tests/integration/` | Integration tests only, with `//go:build integration` |
+| `time.Now()` in tests | Inject `func() time.Time` via `ServiceDeps.Now` |
+| Missing `t.Parallel()` | Every test that doesn't mutate global state must call it |
+| Only happy path tested | Every public method needs error path too |
+| `make test` broken by unrelated code | Fix it — broken tests anywhere block everything |
+| Real third-party service calls hidden in `integration` / `e2e` | Use `//go:build external` and `*_external_test.go`; run the exact package/test manually |
+| Shell curl regression added as a scenario script | Add or update a Strategy 6 case in `tests/e2e/`, `tests/dfx/`, or `tests/eval/`; P0 owns routine smoke |