docs: align hwlab v02 deploy config guidance

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'