diff --git a/docs/reference/g14.md b/docs/reference/g14.md index 59949be8..2a727cce 100644 --- a/docs/reference/g14.md +++ b/docs/reference/g14.md @@ -92,6 +92,58 @@ 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-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 canonical sequence is: + +```bash +trans G14:/root/hwlab-v02 script -- 'git fetch origin v0.2 && git pull --ff-only origin v0.2 && git status --short --branch' +# 1. Create a task-scoped worktree from latest origin/v0.2 +trans G14:/root/hwlab-v02 script -- 'git worktree add .worktree/ -b fix/issue- origin/v0.2' +# 2. Develop, commit, and push the feature branch from inside the worktree +trans G14:/root/hwlab-v02/.worktree/ script -- 'git push -u origin fix/issue-' +# 3. Open a PR through UniDesk CLI (no native gh, no curl) +bun scripts/cli.ts gh pr create --repo pikasTech/HWLAB \ + --head fix/issue- --base v0.2 --title "..." --body-file - +# 4. Merge through UniDesk CLI; do not bypass to native gh pr merge +bun scripts/cli.ts gh pr merge --repo pikasTech/HWLAB --squash +# 5. Pull the merged v0.2 head back into the fixed workspace +trans G14:/root/hwlab-v02 script -- 'git pull --ff-only 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-` naming so PR titles and merge commits stay scannable. + +### Recovery From a 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: + +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: + ```bash + trans G14:/root/hwlab-v02 script -- 'git show > /tmp/v0.2-recovery.patch' + ``` +3. Roll the fixed repo back to the previous merged PR head. Use `git reset --hard `; this preserves any autostash (e.g. from a parallel `git checkout` snapshot in another worktree) on the stash list and does not touch the other worktree's working tree. +4. In the pre-existing worktree (e.g. `.worktree/` on `fix/issue-`) bring the branch up to the previous PR head with `trans G14:/root/hwlab-v02/.worktree/ script -- 'git reset --hard '`, then `git cherry-pick ` to replay the direct commit on the feature branch. If the worktree branch was already a clean clone of `origin/v0.2` at the previous PR head, the reset is a no-op. +5. Push the feature branch and force-push `v0.2` back to the rolled-back head with `--force-with-lease` (refuses to clobber a concurrent push): + ```bash + trans G14:/root/hwlab-v02/.worktree/ script -- 'git push -u origin fix/issue-' + trans G14:/root/hwlab-v02 script -- 'git push --force-with-lease origin v0.2' + ``` +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. + +### v0.2 CLI Verification Gap + +`v0.2` does not yet have a layout-browser smoke equivalent to `scripts/dev-cloud-workbench-layout-smoke.mjs`, which is hard-coded to the DEV `16666/16667` endpoints and refuses to validate against `19666/19667`. Until a v0.2-specific layout smoke exists, v0.2 closeout relies on the following three CLI surfaces: + +- `trans G14:/root/hwlab-v02/.worktree/ script -- 'cd web/hwlab-cloud-web && npm run check && npm run build'` for the static `web:check` (unit/contract tests, source/static layout contracts, dist freshness) and the local `web:build` (12 dist files verified fresh). +- `bun scripts/cli.ts hwlab g14 control-plane status --lane v02` for the runtime + 19666/19667 + Argo + GitOps alignment summary. +- Bounded direct probes against the public endpoints: `curl -fsS http://74.48.78.17:19666/`, `curl -fsS http://74.48.78.17:19666/app.js`, `curl -fsS http://74.48.78.17:19666/styles.css`, `curl -fsS http://74.48.78.17:19667/health/live`, plus `grep` over the returned HTML/JS for the new selector/id/text introduced by the change. + +These three surfaces must be combined for closeout. A passing `web:check` does not prove the running browser, and a passing runtime status does not prove the new selector exists. Document the explicit `grep`/curl evidence in the issue closeout comment so the CLI gap is auditable. Adding a v0.2 layout smoke is a follow-up and must not block the current fix. + ## Node-Local VPN Proxy G14 has a node-local VPN/proxy stack for infrastructure bootstrap and recovery downloads: