From acb77a821cc5fc69c4ff68e2d8af90083e0f04c8 Mon Sep 17 00:00:00 2001
From: seekee421 <yangyang421421@gmail.com>
Date: Tue, 10 Mar 2026 08:16:35 +0800
Subject: [PATCH] docs(skill): solidify routing, ws validation, pm2 port
 migration and slot rebind rules

---
 skills/gitea-issue-devops-agent/SKILL.md | 13 +++++++++++++
 1 file changed, 13 insertions(+)

diff --git a/skills/gitea-issue-devops-agent/SKILL.md b/skills/gitea-issue-devops-agent/SKILL.md
index d7a347e..d1c3c71 100644
--- a/skills/gitea-issue-devops-agent/SKILL.md
+++ b/skills/gitea-issue-devops-agent/SKILL.md
@@ -25,6 +25,8 @@ Run this interaction before any coding or issue action:
      - optional shared QA URL
      - preview slot pool (for issue branches), e.g. `preview-a,preview-b`
      - preview URL template, e.g. `https://{slot}.qa.example.com`
+     - public routing mode: `port-based` or `virtual-host`
+     - websocket public entry: explicit WS URL (`wss://...`) or same-origin path (`/ws`)
    - deployment environment + health endpoint
    - minimum issue quality score (default `70`)
 5. Validate connectivity by running:
@@ -93,6 +95,14 @@ Always avoid `main` and issue branches overwriting each other.
 
 Never deploy different branches to the same fixed URL unless user explicitly approves override.
 
+### Routing Strategy (Recommended)
+
+- Prefer `virtual-host` over raw ports for multi-branch testing:
+  - `main.example.com`, `preview-a.example.com`, `preview-b.example.com`
+  - Keep internal process ports private; expose only 80/443.
+- Use same-origin WS path for frontend (`VITE_WS_URL=/ws`) and route `/ws/*` to the slot server.
+- If `port-based` is used, every active env must have unique client/server ports; never reuse one public URL for two branches.
+
 ## Issue -> Branch -> Environment Binding
 
 - Binding key: `<repo>#<issue>#<branch>`
@@ -171,6 +181,7 @@ Hard rule:
 - Submit testing on the issue branch (CI pipeline + branch preview env).
 - Allocate/reuse branch slot before submission.
 - Apply resource-aware deployment decision from change scope.
+- Verify websocket handshake is healthy on the published preview URL/path before asking QA to test.
 - Post evidence in issue comment:
   - commit SHA
   - test run URL and result
@@ -232,3 +243,5 @@ Close issue only when all are true:
 - Never bypass engineer merge confirmation.
 - Never allow branch previews to overwrite main stable env.
 - Never start dedicated branch server when scope indicates client-only changes.
+- When changing public service ports under PM2, do not rely on `pm2 restart --update-env` alone; delete and recreate the process so CLI args (for example `--port`) actually change.
+- If a branch must be rebound to a specific preview slot (for example `preview-a`), release the existing issue allocation first, then redeploy; reuse logic otherwise keeps the previous slot by design.