trae-coding-engine 0.1.0

package/templates/.agents/skills/coding-db-schema/SKILL.md

@@ -0,0 +1,273 @@
+---
+name: coding-db-schema
+description: Use when adding, modifying, or removing a database schema element in coding_engine — new column, dropped column, renamed column, new table, new index, type change, or new GORM model under `internal/adapters/outbound/persistence/rdb/` or `mem-svc/internal/adapters/outbound/persistence/rdb/`. Encodes explicit migration SQL ownership for the coding-engine main DB, GORM PO / SQL alignment, mem-svc AutoMigrate ownership, RDB repository behavior checks, soft-delete vs physical-delete rules, forward-only safety rules, and the breaking-change ADR trigger.
+version: 1.3.3
+last_updated: 2026-06-24
+---
+
+# coding-db-schema: Schema Ownership
+
+> coding-engine main DB schema is owned by explicit SQL migrations under top-level `migration/`, executed by the Helm migrate Job / `coding-engine migrate` CLI. GORM PO structs remain the application mapping source and must stay in parity with migration SQL.
+
+## Trigger — does this skill apply?
+
+YES if your change touches any of:
+
+- A field on a struct under `internal/adapters/outbound/persistence/rdb/po/` (the GORM models)
+- A repository under `internal/adapters/outbound/persistence/rdb/repository/`
+- Adding/removing/renaming a column, table, index, or constraint
+- Changing a column type
+- Adding a new aggregate that needs persistence
+
+NO if you're only changing application-layer code (services, handlers, DTOs).
+
+
+## The Schema Track
+
+| Track | Mechanism | Trigger | Idempotent? | Can drop? |
+|---|---|---|---|---|
+| **coding-engine main DB** | Top-level `migration/{mysql,postgres,dm}/{up,down}/vX.Y.Z/NNN.sql`; dialect directory names are lowercase; release entrypoint is `coding-engine migrate apply` via Helm migrate Job | Any main DB table/column/index/constraint/type change under `internal/adapters/outbound/persistence/rdb/**` | SQL must be idempotent or scoped to one irreversible DDL per file with a matching operational rollback plan | Yes, only through explicit `down/` SQL and compatibility review |
+
+**Decision rule:**
+- For coding-engine main DB, every PO shape change that affects schema must update both the GORM PO tag and `migration/mysql` + `migration/postgres` + `migration/dm` SQL in the same MR.
+- Adding a new table/column/index → add forward `up/vX.Y.Z/NNN.sql`; add matching `down/vX.Y.Z/NNN.sql`. If automatic rollback is unsafe but the retained schema remains component-compatible, add a comment-only down file and document the retained-schema decision in `docs/07-data-model.md` / ADR.
+- Adding an index → keep the PO GORM tag in sync where GORM can express it, and add the explicit SQL because server startup no longer owns main DB DDL.
+- Dropping / renaming / narrowing → breaking schema change; update code in a rolling-compatible sequence, add `down` only when it is meaningful, and update ADR 0003 when external or rolling-deploy compatibility is affected.
+- Rollback order for breaking changes must be explicit: roll application binaries back to a version compatible with the pre-change schema before running destructive `down` SQL, unless the ADR / rollout plan proves the reverse order is safe.
+- SQL file rule: MySQL non-baseline migrations must contain one SQL statement per file because MySQL DDL commits implicitly. PostgreSQL should also prefer one DDL per file; if a PostgreSQL file contains multiple statements, each statement must be independently idempotent and safe to retry after partial failure.
+
+
+## Delete Semantics
+
+Source of truth: `docs/07-data-model.md` §1.2.
+
+| Table kind | Delete behavior | PO shape | Repository behavior |
+|---|---|---|---|
+| Domain entity / aggregate table | **Soft delete** | Carry `deleted_at`; new bigint-based models should prefer `soft_delete.DeletedAt` with `gorm:"softDelete:milli;column:deleted_at;type:bigint;default:0"` | Use GORM `Delete` with an existing filter or primary-key condition for pure soft delete; model-path reads rely on GORM's soft-delete scope; raw SQL / alias queries must exclude deleted rows manually |
+| Relationship / binding table | **Physical delete** | No `deleted_at` by default | Unbind deletes the association row directly inside the service transaction |
+
+Examples:
+
+- Soft-delete domain entities: `agents`, `agent_channels`, `skills`, `skill_versions`, `directories`, `resources`, `envs`.
+- Physical-delete relationship rows: `agent_skills`, `agent_resources`, and other pure binding tables whose lifecycle is only "this relation exists / no longer exists".
+
+Mandatory rules:
+
+- Do not add `deleted_at` to a pure relationship table unless the relationship itself has independent domain lifecycle / audit requirements. If you need that exception, document it in `docs/07-data-model.md`.
+- Do not physically delete a domain entity row just because the product action says "delete"; implement the action as a soft delete and keep indexes compatible with the deleted marker.
+- Pure soft-delete repository methods must call GORM `Delete` with an existing filter or primary-key condition (for example `db.Delete(&po.X{}, id)` or `db.Where("id = ?", id).Delete(&po.X{})`); do not hand-roll soft delete with `Update("deleted_at", ...)` or `Updates(map{"deleted_at": ...})`.
+- Exception: if the delete operation must also change other columns in the same statement (for example unbind state, lifecycle status, or unique-key release fields), `Update(s)` is allowed. Keep the write scoped to the required fields and do not use it as a replacement for ordinary soft delete.
+- Repository reads must not surface soft-deleted rows. With GORM soft-delete models, keep queries on the model path (`Model(&po.X{})`, `Find(&[]po.X{})`, `First(&po.X{})`, `Delete(&po.X{})`) so GORM injects the predicate; do not add redundant helpers such as `scopeNotDeleted` or repeated `deleted_at = 0` on those model-path statements.
+- Raw SQL, `Table("... AS alias")`, cross-table joins, subqueries, and `Unscoped()` queries must add the matching live-row predicate manually, qualified by alias when needed.
+- Match the table's `deleted_at` representation: bigint soft-delete models use live value `0`; nullable timestamp models use `IS NULL`. Prefer the bigint `soft_delete.DeletedAt` pattern for new domain models; do not migrate existing representation without an ADR / compatibility plan.
+- Unique indexes on soft-deleted domain entities must include the deleted marker or an equivalent live-row partial index when supported, so deleting an entity frees the business key for recreate without colliding with the historical row.
+
+
+## Forward-Only Safety
+
+Preserve rolling-deploy safety in both application behavior and explicit SQL:
+
+- Adding a NOT NULL column on an existing table with rows: ship it as nullable or with a safe application default first. Single-shot mandatory fields can fail or block existing data.
+- Renaming a column: ship as add-new + dual-write + backfill + remove-old across **two releases**.
+- Dropping a column: only after every binary version that reads it has stopped running. Clean application code first, then remove the GORM PO field in a later release.
+
+If you cannot preserve forward-only safety, this is a **breaking change** — see §ADR 0003 Trigger.
+
+
+## Schema Ownership
+
+Only the **migrate CLI / Helm migrate Job** runs coding-engine main DB schema changes.
+
+- `migration/mysql/**`, `migration/postgres/**`, and `migration/dm/**` are the source SQL directories.
+- `deployments/coding-engine/sql/**` is generated from `migration/**` by `make migrate-sql`; verify with `make check-migrate-sql`.
+- Source files under `migration/**` are append-only once present on the target branch. Do not modify, delete, rename, or adjust comments in existing SQL files. For the same release version, add the next contiguous `NNN.sql` under both `up/` and `down/` as applicable; for a new release version, create a new `vX.Y.Z/` directory and start at `001.sql`. `make check-migration-sql-immutability` enforces this against the target branch.
+- When adding a new main-DB dialect directory, update the dialect whitelist used by `scripts/check-migration-sql-immutability.sh` (`MIGRATION_DIALECT_RE`) and its script fixtures in the same MR.
+- `make check-migrate-sql-syntax` statically checks each migration dialect separately for SQL statement boundaries, missing semicolons / unterminated quotes or comments, obvious cross-dialect syntax tokens, and MySQL non-baseline one-statement files. It is intentionally lightweight and does not replace database integration tests for runtime behavior.
+- `internal/adapters/outbound/persistence/rdb/po/**` remains the GORM mapping. Keep tags, table names, column names, indexes, nullability, and soft-delete representation aligned with SQL.
+- Server startup validates that the database has already been migrated to the latest schema version carried by the current image; it must not run GORM `AutoMigrate` or hand-written DDL for the main DB.
+- Worker, gateway, daemon: **never call `AutoMigrate` and never run schema SQL**. They depend on the migrate Job / CLI provisioned schema.
+- Helm must use the existing migrate Job pattern for main DB schema changes. Do not add a second schema runner or a component-private schema Job.
+
+Implication: if you add a worker-only aggregate, the PO still belongs in `internal/adapters/outbound/persistence/rdb/po/`, and the SQL still belongs under top-level `migration/{mysql,postgres,dm}/`. Don't shortcut by adding a second schema call site.
+
+History: `fix(migarte): add enable service links false` was rooted in worker startup competing with server schema readiness — separating ownership prevents that class of bug.
+
+
+## RDB Repository Behavior Gate
+
+`persistence/rdb` is the only production persistence implementation for coding-engine domain repositories. Local and all-in-one modes use the same RDB repositories; they differ only in local transport adapters such as bus/lane/lease.
+
+Trigger this gate when you:
+- Add a new rdb repository
+- Add or change a method on a domain repository interface used by rdb
+- Change rdb repository filtering, tenant/workspace scoping, sorting, pagination, duplicate checks, soft-delete visibility, binding deletion behavior, or returned not-found errors
+
+Required steps:
+1. Keep the RDB repository type asserted against the domain repository interface when practical.
+2. Add or update focused RDB repository tests for the behavior, especially filters, deletion visibility, duplicate/name checks, and transaction-required paths.
+3. Run at least:
+   ```bash
+   go test ./internal/adapters/outbound/persistence/rdb/repository
+   ```
+4. For behavior that depends on SQL semantics, compile integration tests and run the affected `tests/integration/*_repository_test.go` coverage against supported DBs.
+
+Do not add reusable in-memory repository adapters for tests. Application tests should prefer generated domain mocks or narrow same-package fakes. Use package-local RDB / sqlite fixtures only when the application workflow materially depends on transaction boundaries, SQL ordering/filtering, uniqueness, or cross-repository persistence semantics. Repository behavior itself belongs in RDB unit/integration coverage.
+
+## RDB Repository Transaction / Context Rule
+
+All SQL transactions are application-layer boundaries. RDB repositories must
+not open, commit, roll back, or otherwise control transactions.
+
+Mandatory rules for any code under
+`internal/adapters/outbound/persistence/rdb/repository/**` or
+`mem-svc/internal/adapters/outbound/persistence/rdb/repository/**`:
+
+- Do not call GORM transaction APIs in repositories: `.Transaction(...)`,
+  `.Begin(...)`, `.Commit(...)`, `.Rollback(...)`, or `*Tx` equivalents.
+- Main coding-engine rdb repositories use the single public DB entrypoint
+  `rdb.DB(ctx, r.db)` (or a package-local `conn(ctx)` wrapper that delegates to
+  it). Do not expose or call a second public transaction/context helper.
+- Repository code must not branch on whether the caller is inside a
+  transaction. It receives `ctx`, calls the unified DB helper, and lets the
+  application-layer `port.TransactionManager` decide transaction scope.
+- If a repository method requires a caller transaction because it uses row locks
+  or multi-statement read-modify-write semantics, call
+  `rdb.RequireTransaction(ctx)` once at the method boundary and use the returned
+  DB handle. Do not hand-roll `rdb.DB(ctx, nil)` probes.
+- If a repository operation needs multiple SQL statements to be atomic, move
+  the transaction boundary to the owning application service/use case and pass
+  the transactional `ctx` into the existing repository methods.
+- Any caller of an rdb repository method that performs read-modify-write with
+  row locks must run inside `port.TransactionManager.WithinTransaction`. Current
+  examples are `runtime.Repository.PatchMetadata`,
+  `runtime.Repository.PatchMetadataWithFence`, and
+  `message.Repository.NextRunSequence` followed by
+  `message.Repository.SaveRuntimeEvent`.
+- Keep GORM statements straightforward. Prefer simple chained `Model` /
+  `Where` / `Create` / `Updates` / `Delete` calls over clever SQL builder
+  abstractions when fixing transaction placement.
+
+Required check for any rdb repository / PO / mapper / constructor change:
+
+```bash
+make check-repository-transactions
+```
+
+## RDB Structured Query Rule
+
+RDB repositories must be dialect-neutral by construction. Do not fix database
+compatibility by branching on the driver in repository/business code.
+
+Mandatory rules for production files under
+`internal/adapters/outbound/persistence/rdb/repository/**` and
+`mem-svc/internal/adapters/outbound/persistence/rdb/repository/**`:
+
+- Do not branch on database type, driver name, or dialect name. Patterns such as
+  `if driver == "dm"` or `switch db.Dialector.Name()` belong outside repository
+  business logic.
+- Prefer GORM structured predicates: `clause.Eq`, `clause.IN`, `clause.And`,
+  `clause.Or`, `clause.Expr`, and package helpers such as `columnEq`,
+  `tableColumnEq`, `columnIN`, `columnEqColumn`, and `orderBy`.
+- Select field lists must quote identifiers through GORM placeholders, for
+  example `Select("? AS id", clause.Column{Table: "items", Name: "id"})`.
+  Do not write raw field lists such as `Select("items.id, items.name")`.
+- Joins must quote identifiers through GORM placeholders:
+  `Joins("JOIN ? ON ? = ?", clause.Table{Name: "..."}, clause.Column{...}, clause.Column{...})`.
+  Do not write direct table or alias SQL such as `JOIN foo AS f ON f.id = ...`.
+- Use table aliases only when they materially simplify a query shape that cannot
+  be expressed clearly with base table names. For normal joins, prefer real table
+  names plus `clause.Table` / `clause.Column`; this avoids dialect-specific
+  alias quoting issues.
+- Do not use `Raw` or `Exec` in production repositories. Schema DDL belongs in
+  explicit migration SQL, not startup/repository code.
+- Tests may query system tables or use test-only raw SQL to inspect fixtures,
+  but database-type branching must stay in test utilities or system-table
+  inspection helpers rather than leaking into repository behavior.
+
+Rare escape hatch:
+
+```go
+// coding:allow-raw-sql <why structured GORM clauses cannot model this>
+```
+
+Use this only for a narrowly scoped production query that cannot be represented
+with GORM clauses. The reason must be specific enough for code review.
+
+Required check for any rdb repository change:
+
+```bash
+make check-rdb-structured-queries
+```
+
+
+## ADR 0003 Trigger
+
+A change is a **breaking change** (and must update or add an ADR-status entry referencing `docs/adr/0003-data-model-breaking-changes.md`) when it does any of:
+
+- Renames a column that application code outside this PR may still read
+- Removes a column that any DTO or external consumer references
+- Changes a column type in a way that requires application-side parsing changes
+- Removes a status / enum value
+- Changes the `tenant_id` / `workspace_id` semantics
+
+Steps:
+1. Update the GORM PO and application code in a forward-compatible sequence
+2. Update `docs/adr/0003-data-model-breaking-changes.md` Decision section with the new bullet when the change is breaking (immutable history — append only, never edit prior bullets)
+3. Update `docs/07-data-model.md` to match
+4. Run the Docs Verification Gate (see `AGENTS.md`)
+
+Reference the ADR in nearby code or docs if the change is non-obvious.
+
+
+## Done Checklist
+
+- [ ] Forward-only safety holds OR an ADR 0003 entry was added
+- [ ] GORM struct (`po/<aggregate>.go`) updated to match the new shape
+- [ ] Main DB schema changes include matching `migration/mysql` and `migration/postgres` `up` SQL
+- [ ] Rollback-safe changes include matching executable `down` SQL; intentionally retained schema changes include matching comment-only `down` SQL and are documented in docs / ADR
+- [ ] `deployments/coding-engine/sql/**` regenerated with `make migrate-sql` and checked with `make check-migrate-sql`
+- [ ] Migration SQL immutability guard passes: `make check-migration-sql-immutability`
+- [ ] Migration SQL static guard passes: `make check-migrate-sql-syntax`
+- [ ] SQL syntax and retry safety were reviewed: MySQL non-baseline files contain one statement; PostgreSQL multi-statement files are idempotent and safe after partial failure
+- [ ] RDB repository transaction guard passes: `make check-repository-transactions`
+- [ ] RDB repository behavior has focused unit or integration coverage for every new or changed repository behavior
+- [ ] Application tests use mocks/fakes for pure service behavior, or package-local RDB / sqlite fixtures when the workflow depends on persistence semantics
+- [ ] Delete semantics match `docs/07-data-model.md`: domain entity soft delete, relationship / binding physical delete
+- [ ] Repository read paths exclude soft-deleted rows, including raw SQL / `Table(...)` queries
+- [ ] If a column was dropped: every Go reference to it removed (handler, DTO, mapper, events)
+- [ ] Indexes are declared both in migration SQL and PO tags when GORM can express them
+- [ ] RDB repository / PO / mapper changes pass integration compile: `go test -tags=integration ./tests/integration/... -run '^$'`
+- [ ] Corresponding repository integration tests pass against testcontainers, for example `go test -tags=integration ./tests/integration -run '<AffectedRepositoryTest>' -count=1 -parallel=2`
+- [ ] `make test` passes — see `coding-testing` Strategy 5
+- [ ] If breaking: `docs/adr/0003-data-model-breaking-changes.md` and `docs/07-data-model.md` updated
+- [ ] PR commit uses scope `(config)` or `(server)` — NEVER the typo `(migarte)` (history shows it has been used 3+ times; rejected on review)
+
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---|---|
+| Add a column in docs or repository code only, forget the GORM struct field | Update the PO and the migration SQL in the same MR |
+| Add a PO field but forget migration SQL | The database will not be changed by server startup. Add `migration/mysql` and `migration/postgres` SQL and regenerate deployment SQL |
+| Omit a matching `down/vX.Y.Z/NNN.sql` file | Add real rollback SQL, or add a comment-only down file when automatic rollback is intentionally unsupported but retained schema is component-compatible |
+| Edit an existing migration SQL file, even only a comment | Add a new sequential `NNN.sql` file in the same version, or start `001.sql` in a new `vX.Y.Z/` directory |
+| Add a new dialect directory but forget the immutability guard whitelist | Update `MIGRATION_DIALECT_RE` in `scripts/check-migration-sql-immutability.sh` and add focused script fixtures |
+| Put multiple MySQL DDL statements in one non-baseline SQL file | Split to one DDL per file; MySQL DDL commits implicitly and the runner rejects multi-statement non-baseline MySQL files |
+| Leave a deleted column on the GORM struct | The application can keep reading/writing retired schema. Drop the struct field when the app no longer uses it |
+| Add a reusable in-memory repository to make application tests convenient | Use generated domain mocks or narrow same-package fakes; use package-local RDB / sqlite fixtures only for workflows that need persistence semantics |
+| Physically delete a domain entity row | Add / use `deleted_at` soft delete; physical deletion is for relationship / binding rows |
+| Add `deleted_at` to a pure binding table | Binding rows should be physically deleted on unbind; only add soft delete if the relationship has its own audited lifecycle and docs explain why |
+| Raw SQL reads a soft-delete table without a live-row predicate | Add `deleted_at = 0` for bigint soft-delete models or `deleted_at IS NULL` for nullable timestamp models |
+| Use scope `migarte` (typo) in commit message | Use `config`, `server`, or `schema`. The typo has been bounced in review repeatedly |
+| Add a NOT NULL column to a populated table | Ship as nullable or with an application-level default first. Test with non-empty fixture |
+
+
+## Cross-references
+
+- `migration/{mysql,postgres}/` — main DB migration SQL source of truth
+- `deployments/coding-engine/sql/` — generated release SQL; verify with `make check-migrate-sql`
+- `internal/adapters/outbound/persistence/rdb/po/` — GORM mapping, must match migration SQL
+- `docs/adr/0003-data-model-breaking-changes.md` — append-only ADR for schema breaking changes
+- `docs/07-data-model.md` — narrative description; keep in sync with status markers per `docs/CONVENTIONS.md`
+- `coding-testing` Strategy 5 — integration tests with testcontainers exercise persistence behavior
+- `coding-deploy-config` p2-dsn-in-go — database connection strings are still assembled in Go

package/templates/.agents/skills/coding-deploy-config/SKILL.md

@@ -0,0 +1,129 @@
+---
+name: coding-deploy-config
+description: Use when changing any deployment/runtime/config item in coding_engine — Helm values, vecompass-override, configs/engine.yaml.example, Go config struct, image repo/tag, DSN, K8s probe/service port, Secret/ConfigMap field.
+---
+
+# coding-deploy-config: Deployment & Config Sync Gate
+
+> Single-surface config edits are the **#1 source of regressions** on `main`.
+> If you are touching any of the trigger items below, you MUST reconcile every applicable surface before the task is done.
+
+## Trigger — does this skill apply?
+
+YES if your change touches any of:
+
+- A YAML key under `configs/engine.yaml.example`, `deployments/coding-engine/values.yaml`, or `deployments/coding-engine/vecompass-override.yaml`
+- A field on `internal/bootstrap/app/engine_config.go` (unified `EngineConfig`), `internal/bootstrap/worker/registry.go` (`RegistryConfig` / provider wiring), or `internal/adapters/outbound/<provider>/config.go`
+- An image (`repository`, `tag`, `name`, init image)
+- A DSN, connection string, or any `<scheme>://...` URL
+- A K8s probe path/port, Service port, or service name
+- A TOP Action IAM registration (`deployments/coding-engine/templates/server/iam-register-codingserver.yaml`)
+- A credential (`password`, `secret_key`, `access_key`, `ak`, `sk`, `token`, `apikey`, `api_key`)
+- A runtime adapter (`hermes`) config struct, or `runtime.WorkspaceSyncConfig` (wired via the worker registry; the code is `internal/application/agent/workspace_sync.go`, not an outbound adapter)
+
+If unsure, run the Trigger Grep below — if you get hits across multiple surfaces, this skill applies.
+
+```bash
+# Replace <KEY> with the field you're touching (e.g. initImageTag, storage_class, client_encoding)
+grep -rn "<KEY>" internal/bootstrap/app/engine_config.go internal/adapters/outbound/ \
+                 internal/bootstrap/worker/registry.go configs/ deployments/ docs/
+```
+
+
+## The 5 Surfaces (per service)
+
+For each backend component (`server`, `gateway`, `worker`, `daemon`), every config-shape change must touch:
+
+| # | Surface | Path | Owns |
+|---|---|---|---|
+| 1 | Go config struct + defaults + validation | `internal/bootstrap/app/engine_config.go` (unified `EngineConfig`; component dirs only hold `config_test.go` against `app.EngineConfig` / `app.NewDefaultEngineConfig()`). Adapter-local config stays in `internal/adapters/outbound/<provider>/config.go` | Type, defaults, semantic validation |
+| 2 | Local example file | `configs/engine.yaml.example` (component top-level section) | Dev-friendly defaults, comments |
+| 3 | Helm chart defaults | `deployments/coding-engine/values.yaml` (component section) | Chart-render input |
+| 4 | vecompass production override | `deployments/coding-engine/vecompass-override.yaml` (component section) | Prod values |
+| 5 | Component doc table | `docs/0N-coding-<component>.md` | Behavior contract for operators |
+
+**Runtime adapters** (`hermes`, future…) are anchored on the **worker** surfaces. Their closed loop is: adapter config struct in `internal/adapters/outbound/<provider>/config.go`, unified `EngineConfig`, worker `RegistryConfig` / provider wiring in `internal/bootstrap/worker/registry.go`, local YAML example, Helm values / vecompass override, and the worker component doc. Runtime adapter config lives under `customconfig.coding.worker.runtime.<provider>` in `deployments/coding-engine/vecompass-override.yaml`. Workspace sync is not an outbound adapter: it is `runtime.WorkspaceSyncConfig` (code in `internal/application/agent/workspace_sync.go`) wired via the worker `RegistryConfig`. See `coding-runtime-adapter` §Deployment Config Sync Projection for runtime mechanics.
+
+A change is **not done** until each applicable surface either (a) has the new key, or (b) has a written rationale for omission.
+
+## TOP Action IAM Registration
+
+Externally exposed TOP Actions must be registered in the unified server IAM ConfigMap:
+
+| IAM registration template | Owns |
+|---|---|
+| `deployments/coding-engine/templates/server/iam-register-codingserver.yaml` | All externally exposed TOP Actions, including gateway-served Actions whose `Proxy` points at the rendered gateway Service |
+
+When adding, removing, renaming, or moving an Action:
+
+1. Locate the actual route owner in `internal/bootstrap/server` or `internal/bootstrap/gateway`, not just the IDL service name.
+2. Update `deployments/coding-engine/templates/server/iam-register-codingserver.yaml`.
+3. Keep `Action`, `Version`, `Path`, `Proxy`, `ResourceName`, `_Role`, `_ModuleAction`, `IsAuth`, and `IsAudit` aligned with the implemented endpoint and resource model.
+4. If the Action is served by gateway, keep the IAM registration in the server template but point `Proxy` at the rendered gateway Service fullname and port.
+5. Update the component doc when the externally visible API contract or serving component changes.
+
+
+## Pattern Files (read when applicable)
+
+| Sub-rule | Pattern file |
+|---|---|
+| Image (`repository` + `tag` split, no `:latest`, contract validators) | `.agents/skills/coding-deploy-config/patterns/p1-image-fields.md` |
+| DSN / connection string assembly in Go | `.agents/skills/coding-deploy-config/patterns/p2-dsn-in-go.md` |
+| Credential placement: Secret vs ConfigMap | `.agents/skills/coding-deploy-config/patterns/p3-secret-vs-configmap.md` |
+| Probe / Service port alignment with `server.addr` | `.agents/skills/coding-deploy-config/patterns/p5-probe-port-align.md` |
+
+## Templates (copy and adapt)
+
+| Need | Template |
+|------|----------|
+| Verification grep across all 5 surfaces | `.agents/skills/coding-deploy-config/templates/verify-key.sh` |
+| Helm `_helpers.tpl` image-tag guard | `.agents/skills/coding-deploy-config/templates/image-tag-guard.tpl` |
+
+
+## Six Hard Rules (memorize)
+
+1. **No `:latest` tag, ever.** Image must be split into `repository` + `tag`. The Helm template MUST reject `tag: ""` and `tag: "latest"`. See `p1-image-fields.md`.
+2. **DSN is built in Go, never hand-concatenated in YAML.** Add the new param to `DSN()` on the component config struct — never paste a literal `postgres://...` into a YAML file. See `p2-dsn-in-go.md`.
+3. **Credentials live in Secret, never ConfigMap.** Anything matching `password|secret_key|access_key|ak|sk|token|apikey|api_key` MUST come from a Secret-backed config file, `envFrom`, or `valueFrom.secretKeyRef`. Rendered ConfigMaps must contain only references / placeholders. Narrow exception: existing platform-owned `platform-info` environment credentials may be read from the `platform-info` ConfigMap only for the established platform contracts recorded in ADR 0022 and ADR 0048. See `p3-secret-vs-configmap.md`.
+4. **Application config is YAML-first with narrow env exceptions.** Do not add `CODING_*` or other environment-variable overlays for application settings unless an ADR records the exception. Current exceptions are `CODING_SECRET_KEY` and ADR 0048 platform credentials; use YAML fields and Secret-backed rendered values for all other settings.
+5. **Probe / Service port = `server.addr` port.** Never edit one without the other. See `p5-probe-port-align.md`.
+6. **IAM registration is unified in the server template.** A TOP Action belongs in `iam-register-codingserver.yaml`; its `Proxy` follows the HTTP owner. Gateway-served Actions stay in the server IAM template and point at the gateway Service.
+
+
+## Done Checklist
+
+Before marking any deployment/config task done:
+
+- [ ] Trigger grep run; every applicable surface is reconciled
+- [ ] Image fields: `repository` + `tag` split, no `:latest`, contract validator updated if applicable
+- [ ] DSN/connection strings assembled in Go, not YAML
+- [ ] No credential plaintext in rendered ConfigMaps
+- [ ] TOP Action IAM registration reconciled with the actual serving component, including stale registration removal after moves/renames
+- [ ] `make test` and `make check` pass
+- [ ] If a Helm template changed: `helm template deployments/coding-engine` renders without error
+- [ ] If a behavior contract changed: corresponding component doc table updated, status marker (`[已实现]` etc.) accurate
+
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---|---|
+| Edit only `vecompass-override.yaml`, leaving Helm chart default + Go default stale | Reconcile all 5 surfaces or write an explicit rationale |
+| Paste full `postgres://user:pass@host/db?...` literal into a YAML field | Build via the component config `DSN()` helper |
+| Add a new credential field to `values.yaml` as plaintext | Move to Secret-backed config or `valueFrom.secretKeyRef`; ConfigMap only holds the reference |
+| Bump a `tag:` in `vecompass-override.yaml` but forget the chart default | Update `deployments/coding-engine/values.yaml` too — chart consumers without override will break |
+| Add image as `image: foo:bar` (single string) | Split into `image.repository` + `image.tag` |
+| Change `server.addr` from `:8080` to `:8081` without updating `service.httpPort` and probe path/port | Triple-edit; see `p5-probe-port-align.md` |
+| Add an environment-variable config path for application settings | Add a YAML field to the unified engine config instead |
+| Add a runtime adapter config field but skip the worker bootstrap mirror | Add the field to `RegistryConfig` and reconcile provider wiring in `internal/bootstrap/worker/registry.go` |
+| Rename a config key in Go but leave `*.yaml.example` showing the old name | Old name is what new contributors will copy — must reconcile |
+| Add a TOP Action handler but skip `iam-register-codingserver.yaml` | Register the Action in the unified server IAM template |
+| Move an Action from gateway to server, or server to gateway, but leave the old Proxy | Keep the Action in the server IAM template and update `Proxy` to the actual serving component |
+
+
+## Cross-references
+
+- `AGENTS.md` §Deployment Config Sync Gate — top-level rule (this skill is the deep version)
+- `coding-runtime-adapter` §Deployment Config Sync Projection — runtime-adapter projection (worker-anchored)
+- `docs/adr/0010-helm-library-chart.md` — shared chart helpers
+- `docs/adr/0007-openclaw-operator-contract.md` — example of a contract validator that gates an image field