docs: clarify development constraints and error contracts

CONTRIBUTING.md

@@ -164,6 +164,8 @@ For complex or cross-module work, outline the plan in an issue, design note, or
 
 ### Sync local `main` from the correct source
 
+Do this before creating a task branch. Repeat the same freshness check before the final commit and before any push: if local `main` has fallen behind the main repository, update `main` first, then rebase the task branch onto the latest local `main`. Keep task branches linear; do not merge `main` into a task branch unless a maintainer explicitly asks for it.
+
 With the dual-remote setup (`origin` + `myfork`), **example commands** (update local `main` from the main repository):
 
 ```bash
@@ -252,6 +254,8 @@ Agents may help by listing pages to open, roles to use, operations to perform, c
 
 Documentation changes require manual reading by the developer before commit or push. Do not submit AI-generated docs that have not been read and judged by a developer; generated docs often miss important context, steps, or operational details. The developer should revise the docs directly or ask the Agent to adjust them before submission.
 
+Before the final commit and before any push, confirm again that the task branch is based on the latest intended base. If `main` changed while the task was in progress, update local `main`, rebase the task branch, rerun the relevant checks, and re-review any conflict resolution.
+
 ## Commit And Push
 
 If the PR has only one commit, we recommend making the commit message consistent with the branch name: replace `/` with `:` and `-` with spaces. For example, branch `docs/contributing-command-hints` becomes `docs:contributing command hints`; branch `feature/portal-add-job-form` becomes `feature:portal add job form`.
@@ -315,7 +319,7 @@ Push task branches only to your fork remote (`myfork` with the dual-remote setup
 
 ## Open And Iterate On A Pull Request
 
-AI assistance is welcome, but the developer remains responsible for understanding and controlling the change. Before a PR is created or updated, the developer must review the final diff, verification results, and PR description.
+AI assistance is welcome, but the developer remains responsible for understanding and controlling the change. Before a PR is created or updated, the developer must review the branch name, changed-file list, final diff, verification results, and PR description. If an Agent created the commit, it should show the actual branch name and committed file list before preparing or creating the PR.
 
 The PR description must be **bilingual Markdown** and cover:
 
@@ -330,6 +334,8 @@ Keep the description short when the change is simple. Agent-specific PR descript
 
 After pushing a branch, an Agent may create the PR directly when tooling such as `gh` is available, or output the PR description in a code block for the developer to use. In either case, the Agent must show the PR description to the developer and get confirmation before using it to create or update a PR.
 
+Before opening or updating a PR, run the relevant local review path for the changed area when one exists, such as `skills/crater-devel-review/SKILL.md` for repository-wide Agent review or `cli/docs/REVIEW.md` for CLI changes. Treat review as an iteration step: answer valid findings with fixes and document any accepted residual risk instead of treating the first diff as final.
+
 After creating the PR, check workflow status. The PR may need multiple rounds of iteration with Copilot review or human review. An Agent may fetch the PR link itself or ask the developer for it, inspect review comments, judge whether each suggestion is correct and worth changing, then propose a modification plan. Do not apply review-driven code changes until the developer has discussed and approved the plan.
 
 ## Cross-Module Rules

backend/CONTRIBUTING.md

@@ -99,10 +99,15 @@ When changing job creation configuration fields, request/response schema, or tem
 
 ## Errors And Security
 
-- Use RESTful-compliant HTTP status codes; do not use `Error()` everywhere. Pick the response helper that matches the semantics.
-- For new code, return `bizerr` errors and send them with `resputil.HandleError`; keep `backend/internal/resputil/code.go` only for legacy compatibility.
-- Define new business error codes in `backend/internal/bizerr/groups.go` as needed.
-- Error messages returned to the frontend must be clear, accurate English.
+Backend errors are part of the user-facing API contract. They must give the frontend and CLI enough structured facts to tell users what failed and enough stable facts for administrators to troubleshoot.
+
+- Treat the implementation definitions as the live reference for the error contract: `backend/internal/bizerr/groups.go` defines business error groups and codes; `backend/internal/resputil/handle.go` maps those groups to HTTP status codes; `backend/internal/resputil/response.go` defines the `code` / `data` / `msg` response envelope. The generated frontend constants come from `frontend/src/services/generator.py` and `frontend/src/services/error_code.ts`. Do not copy long error-code tables into documentation; mention concrete codes only as examples.
+- Use RESTful HTTP status codes that match the failure semantics in `resputil.HandleError`. Do not collapse all failures into `500` or the legacy `Error()` helper. Examples: invalid caller input belongs in the `400xx` group, state or dependency conflicts belong in `409xx`, and platform or dependency failures belong in `5xx`. These are examples; check the definition files above before choosing or adding a code.
+- For new code, return `bizerr` errors and send them with `resputil.HandleError`; keep `backend/internal/resputil/code.go` only for legacy compatibility. Pick an existing `bizerr` group before adding a new one.
+- Define new business error codes in `backend/internal/bizerr/groups.go` only when the frontend, CLI, or an external caller needs a stable machine-readable reason. The group must stay aligned with the HTTP status selected by `resputil.HandleError`.
+- Error messages returned to clients must be clear, accurate English. Prefer actionable messages that name the invalid field, missing resource, conflicting state, required permission, or unavailable dependency. Do not return generic messages such as `failed`, `invalid`, or raw Go errors when the caller can act on a more specific explanation.
+- Keep user-facing messages safe: do not include secrets, tokens, internal IPs, kubeconfigs, SQL fragments, stack traces, or private infrastructure details. Wrap lower-level errors with `bizerr.*.Wrap` so server logs keep the cause while the API response stays safe.
+- When adding or changing an API error path, verify how the frontend and CLI will present it. The response envelope remains `code`, `data`, and `msg`; clients may show `msg` directly and expose `http_status` / business `code` for support. If a page needs special behavior, document which business code it handles and why.
 - Never concatenate SQL strings in `backend/internal/storage/` or the DAO layer; use parameterized queries.
 - Never hardcode secrets, tokens, passwords, internal IPs, kubeconfigs, or production credentials.
 
@@ -145,7 +150,7 @@ The repo root `.vscode/launch.json` provides a "Backend Debug Server" configurat
 ## Before Submitting Backend Changes
 
 - Run the relevant `make` target, usually `make pre-commit-check` for final checks.
-- If API behavior changed, confirm `swag` annotations and frontend usage are aligned.
+- If API behavior changed, confirm `swag` annotations, frontend usage, CLI behavior, and error presentation are aligned.
 - If job template payloads changed, confirm the versioning / compatibility decision.
 - If database schema changed, include migration and generated code.
 - Record exact checks and any developer manual verification for the PR description.

backend/CONTRIBUTING.zh-CN.md

@@ -99,10 +99,15 @@ make run
 
 ## 错误处理与安全
 
-- 使用符合 RESTful 语义的 HTTP 状态码；不要到处使用 `Error()`，应选择语义匹配的响应 helper。
-- 新代码应返回 `bizerr` 错误并通过 `resputil.HandleError` 输出；`backend/internal/resputil/code.go` 仅保留为旧代码兼容入口。
-- 需要新增业务错误码时，在 `backend/internal/bizerr/groups.go` 中定义。
-- 返回给前端的错误信息必须是清晰、准确的英文。
+后端错误是面向用户的 API 契约的一部分。错误响应必须给前端和 CLI 足够的结构化事实，让用户知道哪里出了问题，也要给管理员留下稳定的排查依据。
+
+- 将实现定义文件作为错误契约的实时参考：`backend/internal/bizerr/groups.go` 定义业务错误 group 和业务码；`backend/internal/resputil/handle.go` 定义这些 group 到 HTTP 状态码的映射；`backend/internal/resputil/response.go` 定义 `code` / `data` / `msg` 响应信封。前端生成常量来自 `frontend/src/services/generator.py` 和 `frontend/src/services/error_code.ts`。不要在文档中复制长错误码表；具体 code 只作为示例出现。
+- 使用符合 `resputil.HandleError` 语义的 RESTful HTTP 状态码，不要把所有失败都压成 `500` 或旧的 `Error()` helper。示例：调用方输入非法属于 `400xx` group，状态或依赖冲突属于 `409xx`，平台或依赖故障属于 `5xx`。这些只是示例；选择或新增 code 前先查上面的定义文件。
+- 新代码应返回 `bizerr` 错误并通过 `resputil.HandleError` 输出；`backend/internal/resputil/code.go` 仅保留为旧代码兼容入口。新增错误前先优先选择已有 `bizerr` group。
+- 只有当前端、CLI 或外部调用方确实需要稳定的机器可读原因时，才在 `backend/internal/bizerr/groups.go` 中新增业务错误码。业务码所属 group 必须和 `resputil.HandleError` 选择的 HTTP 状态保持一致。
+- 返回给客户端的错误信息必须是清晰、准确的英文。优先给出可行动的信息，说明具体非法字段、缺失资源、冲突状态、所需权限或不可用依赖。调用方可以据此修正时，不要返回 `failed`、`invalid` 这类泛化描述，也不要直接返回 Go 原始错误。
+- 用户可见信息必须安全：不得包含密钥、Token、内网 IP、kubeconfig、SQL 片段、堆栈或私有基础设施细节。底层错误用 `bizerr.*.Wrap` 包装，让服务端日志保留 cause，同时保证 API 响应安全。
+- 新增或修改 API 错误路径时，必须确认前端和 CLI 将如何展示。响应信封保持 `code`、`data`、`msg`；客户端可以直接展示 `msg`，并暴露 `http_status` / 业务 `code` 作为支持排查事实。如果页面需要特殊交互，说明处理哪个业务码以及原因。
 - 严禁在 `backend/internal/storage/` 或 DAO 层拼接 SQL 字符串，必须使用参数化查询。
 - 严禁硬编码密钥、Token、密码、内网 IP、kubeconfig 或生产凭据。
 
@@ -145,7 +150,7 @@ make build-storage
 ## 提交 Backend 改动前
 
 - 运行相关 `make` target，最终检查通常使用 `make pre-commit-check`。
-- 如果 API 行为变化，确认 `swag` 注释和前端调用已对齐。
+- 如果 API 行为变化，确认 `swag` 注释、前端调用、CLI 行为和错误展示已对齐。
 - 如果作业模板 payload 变化，确认版本和兼容性决策。
 - 如果数据库结构变化，包含迁移和生成代码。
 - 记录实际检查和开发者人工验证，供 PR 描述使用。

cli/CONTRIBUTING.md

@@ -23,18 +23,18 @@ Before running CLI build or test targets, run `go version` and make sure it matc
 
 Keep changes scoped to the command domain or shared module you are touching.
 
-- Command behavior belongs in `cmd/`, but shared output, error, API, state, credential, i18n, and completion behavior should use the existing internal packages.
-- Do not add one-off JSON rendering, HTTP clients, Keyring access, or state-file reads in command code.
-- If Agent Skills change, keep `SKILL.md` concise and put detailed workflows in `references/`.
+Use [docs/SPEC.md](docs/SPEC.md) for cross-command rules and shared implementation constraints, [docs/COMMANDS.md](docs/COMMANDS.md) for user-visible command contracts, and [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for package boundaries and request flow. If Agent Skills change, follow the Skills rules in `docs/SPEC.md`.
 
-When you need to manually try the CLI, run:
+When you need to manually try the CLI, build the local binary first:
 
 ```bash
 make build
 ```
 
 This runs `go mod tidy` and builds the local `./crater` binary.
 
+For user-visible CLI behavior, ask the developer to manually run the key command paths described by `docs/COMMANDS.md` and `docs/SPEC.md`. Agent-run tests can narrow risk, but they do not replace developer verification of the platform contract.
+
 ## 3. Test The Change
 
 Choose tests based on what changed.
@@ -57,7 +57,7 @@ If the command contract intentionally changes, regenerate snapshots:
 make snapshot-update
 ```
 
-Then review the `cli/testdata/snapshots/` diff manually. Golden files must be generated this way, not edited by hand.
+Then review the `cli/testdata/snapshots/` diff manually according to `docs/SPEC.md` and `docs/REVIEW.md`. Golden files must be generated this way, not edited by hand.
 
 Before opening or updating a pull request, run the full CLI test target unless the change is documentation-only and does not affect generated files or code. This target runs both unit tests and snapshot checks:
 
@@ -79,4 +79,4 @@ Check that:
 - Tests cover the risk introduced by the change.
 - Golden files, if updated, were generated by `make snapshot-update` and reviewed manually.
 - README files remain user-facing and do not contain internal development guidance.
-- Agent Skills, if changed, describe how to use existing CLI contracts rather than defining new command behavior.
+- Agent Skills, if changed, follow `docs/SPEC.md` and describe how to use existing CLI contracts rather than defining new command behavior.

cli/CONTRIBUTING.zh-CN.md

@@ -23,18 +23,18 @@ Crater CLI 采用文档驱动开发。修改代码前，请先确认你触及的
 
 改动应尽量限制在对应命令域或共享模块内。
 
-- 命令编排放在 `cmd/`，但共享输出、错误、API、状态、凭据、i18n 和补全行为应使用已有 internal 包。
-- 不要在命令代码里临时实现 JSON 渲染、HTTP client、Keyring 访问或状态文件读取。
-- 如果修改 Agent Skills，保持 `SKILL.md` 精炼，将详细流程放入 `references/`。
+跨命令规则和共享实现约束见 [docs/SPEC.md](docs/SPEC.md)，用户可见命令契约见 [docs/COMMANDS.md](docs/COMMANDS.md)，包边界和请求流程见 [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)。如果修改 Agent Skills，遵守 `docs/SPEC.md` 中的 Skills 规则。
 
-需要手动试用 CLI 时，运行：
+需要手动试用 CLI 时，先构建本地二进制：
 
 ```bash
 make build
 ```
 
 该命令会执行 `go mod tidy` 并构建本地 `./crater` 二进制。
 
+涉及用户可见 CLI 行为时，要求开发者按 `docs/COMMANDS.md` 和 `docs/SPEC.md` 手动执行关键命令路径。Agent 运行的测试可以降低风险，但不能替代开发者对平台契约的人工验证。
+
 ## 3. 测试改动
 
 根据改动内容选择测试。
@@ -57,7 +57,7 @@ make snapshot-check
 make snapshot-update
 ```
 
-然后人工审查 `cli/testdata/snapshots/` 的 diff。Golden 文件必须通过这种方式生成，不要手工编辑。
+然后按 `docs/SPEC.md` 和 `docs/REVIEW.md` 人工审查 `cli/testdata/snapshots/` 的 diff。Golden 文件必须通过这种方式生成，不要手工编辑。
 
 除纯文档改动且不影响生成文件或代码外，创建或更新 PR 前应运行完整 CLI 测试目标。该目标会同时运行单元测试与快照校验：
 
@@ -79,4 +79,4 @@ make pre-commit-check
 - 测试覆盖了本次变更引入的风险。
 - 如果更新了 golden 文件，它们由 `make snapshot-update` 生成，并且已经人工审查。
 - README 面向普通用户，不包含内部开发指引。
-- 如果修改了 Agent Skills，它们只说明如何使用已有 CLI 契约，不单独定义新的命令行为。
+- 如果修改了 Agent Skills，它们遵守 `docs/SPEC.md`，只说明如何使用已有 CLI 契约，不单独定义新的命令行为。