From 30089a120df918daf31cc61144fc6f7da114ec04 Mon Sep 17 00:00:00 2001
From: Codex <codex@noreply.local>
Date: Tue, 2 Jun 2026 04:54:46 +0000
Subject: [PATCH] docs: require CLI validation before HWLAB issue closure

---
 AGENTS.md             | 5 +++++
 docs/reference/g14.md | 4 ++++
 2 files changed, 9 insertions(+)

diff --git a/AGENTS.md b/AGENTS.md
index a9bc403d..ec1f4035 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -55,6 +55,11 @@ UniDesk 是一个以主 server 为统一入口的分布式工作平台；本文
 - P0: 如果运行面热补被正常 GitOps、rollout、CI/CD 或镜像重建覆盖，或热补载体与正式发布路径冲突，不要反复拉扯热补；保留已获得的最小闭环证据，直接转入 PR/CI/CD 正式流程，并以正式 rollout 后的原入口复测作为最终结论。
 - 外部 API 或模型行为可能变化时，先查官方/一手文档和成熟实践，再在目标运行面做实验验证；不要凭旧记忆反复推 CI/CD 试错。
 
+## Critical HWLAB Issue Closure CLI Validation Rule
+
+- P0: HWLAB/G14/v0.2 的用户反馈、CLI、Cloud Web、AgentRun、device-pod、公开 API 或运行面工作流 issue，关闭前必须完成用户入口或原入口的真实验证；仅有 targeted test、unit/contract test、构建检查、PR 合并或源码层证据不得关闭 issue。
+- P0: CLI 相关 issue 未完成目标 runtime 上的真实 CLI 验证时必须保持打开或重新打开；关闭评论必须写明实际 CLI/入口命令、目标 lane/URL/namespace、trace/session/thread/PipelineRun 等证据和结果，细则见 `docs/reference/g14.md`。
+
 ## Critical CI/CD CLI Control Rule
 
 - P0: CI/CD、GitOps、rollout、artifact 发布、PR 合并后 DEV/PROD 滚动、PipelineRun 重跑/清理、Argo refresh 和运行面 retention 这类控制动作必须走 UniDesk CLI 的受控子命令；禁止把原生 `kubectl`、`argo`、`tkn`、`gh`、`curl` 或临时 shell 当作正式控制入口。
diff --git a/docs/reference/g14.md b/docs/reference/g14.md
index b5384939..5252652e 100644
--- a/docs/reference/g14.md
+++ b/docs/reference/g14.md
@@ -80,6 +80,10 @@ bun scripts/cli.ts hwlab g14 control-plane status --lane v02 --source-commit <fu
 
 Targeted status must expose `statusTarget.mode` and `targetValidation`. `targetValidation.state=passed` means the requested PipelineRun/source commit reached a succeeded PipelineRun, Argo `Synced/Healthy`, public web/API probes, flushed Git mirror, and matching `hwlab-cloud-api` / `hwlab-cloud-web` runtime source commits. `targetValidation.state=superseded` means the requested PipelineRun succeeded and was later replaced in runtime by a newer succeeded `v0.2` PipelineRun; this is valid closure evidence for the requested run when the newer commit is on the same branch lineage. In both states, `commitAlignment.staleReasons` may still mention later `origin/v0.2` or CI/CD source head movement; that is parallel-head context, not a failure of the requested run. `falseGreenGuard` is a current-runtime guard and should report not-applicable/superseded for such historical targets instead of turning later runtime movement into a false failure. Default status without a target remains strict for the latest source head.
 
+For HWLAB user-feedback, CLI, Cloud Web, AgentRun, device-pod, public API, or runtime workflow issues, source-level validation is not enough to close the issue. Unit tests, contract tests, `git diff --check`, targeted build checks, PR merge metadata, and source commit rollout evidence are supporting evidence only. The issue may be closed only after the affected user entry or original entry has been exercised against the target runtime. For CLI issues, that means running the relevant `hwlab-cli` or UniDesk-controlled CLI command from the G14 `v0.2` workspace or approved execution plane against the intended lane/URL/namespace and proving the observed behavior, not just proving the helper code compiles. For Cloud Web or public API issues, use the public endpoint or a bounded browser/API smoke that reaches the deployed runtime. For AgentRun or device-pod issues, capture the trace/session/thread/run/job/device evidence that proves the specific continuation or hardware workflow reached the live backend.
+
+The closing comment for these issues must include the actual command or entry path, target lane or endpoint, relevant trace/session/thread/PipelineRun/run/device ids, and the pass/fail result. If the original entry cannot be verified because rollout has not happened, credentials are unavailable, the target runtime is down, or the required CLI capability is missing, keep the issue open and record the blocker. Do not close the issue on the strength of PR merge, targeted tests, or "will be verified after rollout" wording. If an issue was closed before this real CLI/user-entry validation, reopen it and add a correction comment before continuing.
+
 `/health/live` revision is owned by `hwlab-cloud-api`; it can legitimately differ from the source commit for a Cloud Web-only change. Do not call that difference a failed Cloud Web rollout when `webAssets.checks.htmlOk`, `webAssets.checks.appJsOk`, CSS probes, Argo health, and `hwlab-cloud-web` Deployment readiness have passed. For Cloud Web behavior changes, the public JS asset probe or a bounded browser/DOM check is stronger evidence than cloud-api `apiRevision`.
 
 Do not turn `v0.2` expansion governance into a stack of broad compatibility gates. The stable control points are branch, dedicated CI/CD source repo, git mirror/relay refs, GitOps branch, namespace, runtime path, Argo Application, FRP ports and generated-output ownership. Legacy DEV/D601/main preflights that block the `v0.2` lane should be removed from that lane, not patched with fallback or legacy modes. Naming, RBAC scope, cleanup policy, resource quota and rollback order are design decisions or runbook entries unless they protect a concrete high-value risk that cannot be enforced by the fixed boundaries above.