docs: align hwlab v02 deploy config guidance

AGENTS.md

@@ -65,7 +65,7 @@ UniDesk 是一个以主 server 为统一入口的分布式工作平台；本文
 
 ## Critical Distributed Agile Validation Rule
 
-- P0: 分布式敏捷开发通用流程以 `$dad-dev` skill 为唯一权威：P1 目标运行面探测、P2 运行面最小热补丁闭环、P3 源码 PR/CI/CD、P4 原入口复测；UniDesk 项目特有入口和判定边界见 `docs/reference/devops-hygiene.md`。
+- P0: 分布式敏捷开发通用流程以 `$dad-dev` skill 为唯一权威：P1 目标运行面探测、P2 运行面最小热补丁闭环、P3 持久化 Git/项目交付路径、P4 原入口复测；UniDesk 项目特有入口和判定边界见 `docs/reference/devops-hygiene.md`。
 - P0: 对第三方模型、API provider、硬件、跨平台 bridge、CLI/trans/tran 或高频工具链异常，禁止在未核对当前 runtime config/Secret/env/proxy 并完成目标运行面实地探测前定性为外部不可用。
 - P0: 运行面热补只能作为实验和恢复证据，不能替代正式 PR/CI/CD；若热补被正常 GitOps、rollout、CI/CD 或镜像重建覆盖，保留最小闭环证据后直接转入 `$dad-dev` 的 P3/P4。
 
@@ -103,11 +103,11 @@ UniDesk 是一个以主 server 为统一入口的分布式工作平台；本文
 ## Critical G14 HWLAB Workspace Rule
 
 - P0: `G14:HWLAB` 是当前 HWLAB DEV/PROD source workspace 和 k3s/GitOps 运行面真相；唯一长期 source workspace 是 G14 节点上的 `/root/hwlab`，固定使用 `G14` 分支和 `origin git@github.com:pikasTech/HWLAB.git`；所有 HWLAB 新开发、文档、render、polling、CI/CD/GitOps 修复默认都必须以该目录和 G14 运行面为准。
-- P0: HWLAB `v0.2` 是在 G14 上的加法扩容线，不改变、删除或重命名现有 `G14`/`G14-gitops` 分支、`hwlab-dev`/`hwlab-prod` namespace 或 17666/17667、18666/18667 入口；`v0.2` 固定使用分支 `v0.2`、开发 workspace `G14:/root/hwlab-v02`、CI/CD 专用 source repo `G14:/root/hwlab-v02-cicd.git`、namespace `hwlab-v02` 和 19666/19667 FRP 入口，长期细则见 `docs/reference/g14.md`。
+- P0: HWLAB `v0.2` 是在 G14 上的加法扩容线，不改变、删除或重命名现有 `G14`/`G14-gitops` 分支、`hwlab-dev`/`hwlab-prod` namespace 或 17666/17667、18666/18667 入口；`v0.2` 固定使用分支 `v0.2`、开发 workspace `G14:/root/hwlab-v02`、CI/CD 专用 source repo `G14:/root/hwlab-v02-cicd.git`、namespace `hwlab-v02`、19666/19667 FRP 入口和 `deploy/deploy.yaml` 单一人写配置源，长期细则见 `docs/reference/g14.md`。
 - P0: 每次开始 `G14:HWLAB` 分布式开发、切换任务、恢复中断或上下文压缩后，必须重新读取目标 workspace 的 `/root/hwlab/AGENTS.md`，并以该文件和其引用的 HWLAB repo 内规则为当前任务约束；禁止只凭压缩摘要或主 server 记忆继续改代码。
 - 操作入口必须通过 UniDesk SSH 维护桥：host/source 操作用 `trans G14 script` 或 workspace route 加 `apply-patch`，远端文本 patch 默认使用 `apply-patch` 的 v2 引擎、旧 helper 仅通过 `apply-patch-v1` 显式调用；k3s 操作用 `trans G14:k3s ...`；禁止使用 `ssh G14 k3s ...`，定位必须写在第一个 route token，后续 token 才是 operation。
 - P0: 每次开始 `G14:HWLAB` 工作前，固定仓库 `/root/hwlab` 必须先即时快进到 `origin/G14` 最新；先通过 SSH 桥执行 `cd /root/hwlab && git fetch origin G14 && git pull --ff-only origin G14 && git status --short --branch && git remote -v`。若有未提交并行变更阻碍快进，必须先判断是否能与最新 `origin/G14` 快速合并；能合并则立即合并，禁止默认 stash、丢弃或绕到落后 worktree；只有确实无法自动合并时才隔离保存并停止交给人工决策。禁止用落后的固定仓库继续预检、创建 worktree、开发、render、polling 或部署。
-- G14 HWLAB 开发必须先以 `/root/hwlab` 做固定 repo 预检，再在 `/root/hwlab/.worktree/<task>` 从最新 `origin/G14` 创建独立 worktree 修改和提交；不要把固定 repo 当作并行任务 scratch 区，细则见 `docs/reference/g14.md`。
+- G14 HWLAB service/runtime 开发必须先以固定 repo 做预检，再按目标 lane 创建独立 worktree/PR；v0.2 CaseRun、短连接 CLI、trace、docs/reference 和配置治理这类无服务任务按 `docs/reference/g14.md` 的 `direct-lightweight` 规则可在 `G14:/root/hwlab-v02` 直接提交推送，不触发 PR/CI/CD/rollout。
 - P0: G14 已有节点本地 GitHub/Google/DockerHub/npm 等 bootstrap 加速 proxy；在 G14 host、临时 pod、构建 pod 或透传 pod 里拉 GitHub/Google 资源前必须优先使用该 proxy，避免把网络直连失败当作代码阻塞。主入口：HTTP/HTTPS `http://127.0.0.1:10808`、SOCKS `socks5h://127.0.0.1:10808`，备份入口和 NO_PROXY 规则见 `docs/reference/g14.md`。
 - 禁止把 master server、D601、`/root/HWLAB`、`/home/ubuntu/hwlab`、`/workspace/hwlab` 或临时 clone 当作 `G14:HWLAB` source truth；master server 也不得运行 HWLAB check、Playwright/browser smoke、镜像构建或其他重型验证，验证必须走 G14 `/root/hwlab`、G14 k3s/Tekton 或其他获批外部执行面。
 - 长期细节见 `docs/reference/g14.md`；G14 节点本地也保留 `/root/docs/hwlab-g14-workspace.md`，两处口径必须保持一致。

docs/reference/g14.md

@@ -65,7 +65,9 @@ The fixed `v0.2` runtime namespace is `hwlab-v02`. The intended public FRP alloc
 
 Master-side FRP server maintenance for HWLAB public ports is documented in `docs/reference/hwlab.md#hwlab-frp-维护`; keep the detailed allowlist, restart boundary and verification sequence there instead of duplicating another runbook in this G14 node reference.
 
-The `v0.2` CI/CD integration must be additive: add a manual UniDesk trigger, dedicated CI/CD source repo, `devops-infra` git mirror/relay, GitOps desired-state lane, Argo CD Application, namespace resources, artifact catalog, and `deploy.json` environment only when they target `v0.2`/`hwlab-v02` explicitly. Do not add a `v0.2` branch poller or retarget the existing `G14` poller, DEV/PROD Argo Applications, DEV/PROD runtime paths, or existing namespace resources to bootstrap `v0.2`.
+The `v0.2` CI/CD integration must be additive: add a manual UniDesk trigger, dedicated CI/CD source repo, `devops-infra` git mirror/relay, GitOps desired-state lane, Argo CD Application, namespace resources, artifact catalog, and a `deploy/deploy.yaml` lane config only when they target `v0.2`/`hwlab-v02` explicitly. Do not add a `v0.2` branch poller or retarget the existing `G14` poller, DEV/PROD Argo Applications, DEV/PROD runtime paths, or existing namespace resources to bootstrap `v0.2`.
+
+For current G14/v0.2, `deploy/deploy.yaml` is the single human-authored deploy/runtime config source. `deploy/deploy.json` is not a v0.2 compatibility source and must not be recreated for this lane. YAML and JSON parsing are centralized in the HWLAB repo's format-agnostic config layer: `scripts/src/structured-config.mjs` handles file format parsing/writing, while `scripts/src/deploy-config.mjs` owns deploy-config defaults and shape. Renderers, planners, smoke scripts and CLIs should consume that layer through `readStructuredFile` / `writeStructuredFile` / `readDeployConfig` or equivalent helpers; do not scatter direct YAML parser imports or ad hoc `readFile` + `YAML.parse` calls. Legacy D601 HWLAB CD still has its own `deploy/deploy.json` desired-state documented in `docs/reference/hwlab.md`; that legacy path is not the G14/v0.2 authority.
 
 The `devops-infra` git mirror/relay remains manual and CLI-controlled, not CronJob-driven. The standard `v0.2` delivery trigger is `bun scripts/cli.ts hwlab g14 monitor-prs --lane v02`: it watches base=`v0.2` PRs, waits for GitHub preflight/CI readiness, auto-merges only ready and non-conflicting PRs, then drives the same controlled CD path and comments pending/blocked/succeeded/failed/timeout state back to the PR. The lower-level `bun scripts/cli.ts hwlab g14 control-plane trigger-current --lane v02 --confirm` remains the manual recovery or diagnosis entry; it must fetch `/root/hwlab-v02-cicd.git`, resolve the current `origin/v0.2` source commit, check the mirror's `localV02` ref before creating the PipelineRun, run one bounded manual `git-mirror sync` Job when the mirror is stale, and only continue after the mirror ref matches the current source commit. Use `hwlab g14 git-mirror sync --confirm` directly only for explicit mirror maintenance or diagnosis.
 
@@ -102,20 +104,30 @@ For HWLAB v0.2 Code Agent context-loss or multi-turn continuity issues, the mini
 
 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.
 
-## v0.2 Worktree + PR Workflow
+## v0.2 Source Workflow
 
-`v0.2` source-of-truth changes must enter through a task-scoped worktree on a feature branch and then merge through a PR, not by direct commits to `v0.2`. The generic P2/P3/P4 flow is owned by `$dad-dev`; this section only fixes the G14/v0.2-specific source route, branch and lane:
+The generic P2/P3/P4 flow is owned by `$dad-dev`; this section fixes the G14/v0.2 source route, branch and lane. `v0.2` now has two source workflows:
+
+- `direct-lightweight`: CaseRun, case registry aggregation, trace rendering, short-connection CLI/helper, docs/reference, schema-free config reader/writer, and deploy-config cleanup that does not change cloud-api, web, gateway, GitOps, k3s runtime or other long-running services. Use the fixed workspace directly, run the relevant CLI/render/test validation on G14, commit to `v0.2`, and push `origin v0.2`. Do not open a PR, trigger CI/CD, rollout, or reintroduce legacy gates for this class.
+- `pr-rollout` / service workflow: cloud-api, Cloud Web UI, gateway, AgentRun dispatch integration, device-pod runtime, GitOps/Tekton/Argo, k3s manifests, Secrets/RBAC, public endpoint behavior, or any change that must reach live runtime. Use a task-scoped worktree on a feature branch, merge through a PR, then use the controlled v0.2 CD/status path.
+
+Direct-lightweight precheck:
 
 ```bash
 trans G14:/root/hwlab-v02 script -- 'git fetch origin v0.2 && git pull --ff-only origin v0.2 && git status --short --branch'
+```
+
+Service workflow setup:
+
+```bash
 trans G14:/root/hwlab-v02 script -- 'git worktree add .worktree/<task> -b fix/issue<N>-<short-name> origin/v0.2'
 ```
 
-The fixed repo at `/root/hwlab-v02` is not a scratch area and must not carry parallel worktree state on the `v0.2` branch itself. All worktree branches should follow the `fix/issue<N>-<short-name>` naming so PR titles and merge commits stay scannable. GitHub PR writes, merge, rollout trigger and final original-entry validation follow `$dad-dev` plus the UniDesk CLI control rules in `AGENTS.md`.
+The fixed repo at `/root/hwlab-v02` is not a scratch area for service/runtime work, but it is the direct-lightweight source workspace. When a direct-lightweight task sees parallel dirty state in the fixed repo, inspect and include or separate it according to the current user instruction and project Git rules; never discard it silently. Worktree branches for service workflow should follow the `fix/issue<N>-<short-name>` naming so PR titles and merge commits stay scannable. GitHub PR writes, merge, rollout trigger and final original-entry validation follow `$dad-dev` plus the UniDesk CLI control rules in `AGENTS.md`.
 
-### Recovery From a Direct Commit To v0.2
+### Recovery From an Unapproved Direct Commit To v0.2
 
-A direct commit on `v0.2` (work that landed with `git commit` on the fixed repo or a checkout that bypassed the worktree) must be moved onto a feature branch and re-merged through a PR before the next `trigger-current` reads it. The recovery is bounded and audit-friendly, but it is also a `git push --force-with-lease` against the protected branch, so it is only acceptable when the direct commit is the only new content on `v0.2` since the last merged PR:
+Direct-lightweight commits are allowed and do not need recovery. A direct commit on `v0.2` only needs recovery when it changed service/runtime/GitOps/CI/CD/public behavior that should have used the PR/rollout workflow. The recovery is bounded and audit-friendly, but it is also a `git push --force-with-lease` against the protected branch, so it is only acceptable when the unapproved direct commit is the only new content on `v0.2` since the last merged PR:
 
 1. Confirm no parallel worktree was in flight and the commit is the only delta. `trans G14:/root/hwlab-v02 script -- 'git log origin/v0.2..HEAD'` and `git log HEAD..origin/v0.2` must show the direct commit as a single fast-forward candidate.
 2. Capture the commit identity and patch for the recovery record:
@@ -132,7 +144,7 @@ A direct commit on `v0.2` (work that landed with `git commit` on the fixed repo
 6. Open the PR through UniDesk CLI, squash-merge, then `git pull --ff-only origin v0.2` to bring the fixed repo back in sync. The previous PR's merge commit will not be in the new PR's history; the new PR's diff equals the original direct commit's diff, so the PR trail still contains the exact same bytes.
 7. `bun scripts/cli.ts hwlab g14 control-plane status --lane v02` will read the new merge commit; the previously-staged PipelineRun for the direct commit was created on the v0.2 head and `trigger-current` will delete + recreate it for the post-merge head, so no manual PipelineRun cleanup is required.
 
-The recovery is auditable: the original `git show` patch and the `cherry-pick` SHA both land in the PR diff, so the issue/PR trail still contains the exact same bytes that were first committed directly. This is a one-time corrective action; recurring direct commits on `v0.2` are a workflow regression and must be called out in the relevant issue or PR.
+The recovery is auditable: the original `git show` patch and the `cherry-pick` SHA both land in the PR diff, so the issue/PR trail still contains the exact same bytes that were first committed directly. Recurring unapproved service/runtime direct commits on `v0.2` are a workflow regression and must be called out in the relevant issue or PR; direct-lightweight commits are not a regression.
 
 ### v0.2 Cloud Web Runtime Layout Validation
 
@@ -250,7 +262,7 @@ A live `workspace.evidence` / `debug.evidence` / `download evidence` selector th
 
 ### v0.2 device-pod closeout checks
 
-Device-pod fixes still follow `$dad-dev` and the `## v0.2 Worktree + PR Workflow` route above. The device-pod-specific closeout is the three-layer runtime matrix below; keep these checks because they prove the cloud-api -> executor -> D601 host chain, while generic PR/CI/CD and worktree mechanics stay in `$dad-dev`.
+Device-pod fixes still follow `$dad-dev` and the service/runtime side of the `## v0.2 Source Workflow` route above. The device-pod-specific closeout is the three-layer runtime matrix below; keep these checks because they prove the cloud-api -> executor -> D601 host chain, while generic PR/CI/CD and worktree mechanics stay in `$dad-dev`.
 
 ```bash
 trans G14:/root/hwlab-v02/.worktree/<task> script -- 'cd tools && bun test device-pod-cli.test.ts'

docs/reference/hwlab.md

@@ -126,6 +126,8 @@ profile 配置后的最小真实验收是通过同一 HWLAB v0.2 Cloud API/Web d
 
 以下 UniDesk wrapper 是旧 D601 DEV CD 指挥入口，只用于显式 legacy 诊断和迁移对照。当前 G14 DEV/PROD 发布、GitOps 和运行面收敛必须优先按 G14 `/root/hwlab` 与 HWLAB repo-owned 规则执行；不要把下面的 D601 wrapper 当作当前 HWLAB release truth。
 
+本节里的 `deploy/deploy.json` 只属于 D601 legacy DEV CD wrapper。当前 G14/v0.2 的单一人写部署配置源是 `deploy/deploy.yaml`，并由 HWLAB repo 的 format-agnostic config layer 读取；权威规则在 `docs/reference/g14.md#hwlab-v02-expansion-line`。
+
 UniDesk 指挥侧固定入口：
 
 ```sh
@@ -166,7 +168,7 @@ node scripts/dev-cd-apply.mjs --apply --confirm-dev --confirmed-non-production -
 - 证据只记录对象名、状态、revision、健康结果和已脱敏差异；不得把 Secret 值、token、可复用凭证命令或完整敏感 env 输出写入 issue、PR、日志或文档。
 - live Secret、env、ConfigMap、Deployment patch 或 rollout 结果只能作为临时恢复证据，不能成为长期部署真相。
 - HWLAB runtime truth 必须回写到 HWLAB 仓库自己的 issue、`AGENTS.md`、`docs/reference/`、部署配置或 secret 管理入口；UniDesk 只保留指挥侧边界和交叉引用。
-- 热修后必须说明 durable source fix 如何进入 HWLAB 的 CLI、manifest、`deploy/deploy.json` 或等价发布路径；如果尚未完成，要保留 HWLAB issue 追踪。
+- 热修后必须说明 durable source fix 如何进入 HWLAB 的 CLI、manifest、当前 G14/v0.2 `deploy/deploy.yaml`、显式 D601 legacy `deploy/deploy.json` 或等价发布路径；如果尚未完成，要保留 HWLAB issue 追踪。
 
 ## D601 Legacy Cloud Web 手动 DEV 发布路径
 
@@ -218,5 +220,5 @@ curl -fsS http://74.48.78.17:16666/styles.css | rg 'overflow: hidden|100dvh'
 - `SOURCE`、`LOCAL`、`DRY-RUN`、fixture 或只读报告不能被当作 `DEV-LIVE`。真正的 M3 DEV-LIVE 需要证明 `res_boxsimu_1:DO1 -> hwlab-patch-panel -> res_boxsimu_2:DI1` 并带有 operation、audit、evidence 链。
 - 前端体验、Cloud Workbench polish、Gate 页面、诊断页和发布路径修复都是支撑任务，不等同于 M3 PASS。
 - 指挥官可以手动处理 PR 冲突和最终合并判断；runner 不应承担复杂冲突合并。
-- 任何临时手动上线或绕行都要回写 HWLAB issue 与 HWLAB 长期参考文档，并标明后续如何收敛到 CLI 和 `deploy/deploy.json`。
+- 任何临时手动上线或绕行都要回写 HWLAB issue 与 HWLAB 长期参考文档，并标明后续如何收敛到 CLI、当前 G14/v0.2 `deploy/deploy.yaml`、显式 D601 legacy `deploy/deploy.json` 或等价发布路径。
 - HWLAB Secret/env/rollout 热修按本文“HWLAB 热修边界”和 `docs/reference/devops-hygiene.md` 执行；UniDesk 侧只沉淀边界，HWLAB 侧沉淀运行真相。