fix(gitops): tighten controller staging and intake docs

.github/workflows/deploy-controller-v2.yml

@@ -133,13 +133,40 @@ jobs:
         shell: bash
         run: |
           set -euo pipefail
-          if git diff --quiet; then
-            echo "No deploy overlay changes"
+          CHANGED_OVERLAYS="$(python3 - <<'PY'
+          import json
+          from pathlib import Path
+
+          payload = json.loads(Path("/tmp/deploy-results.json").read_text(encoding="utf-8"))
+          changed_paths = set()
+          for item in payload.get("results", []):
+              for fact in item.get("facts", []):
+                  if not isinstance(fact, dict) or fact.get("type") != "overlay":
+                      continue
+                  value = fact.get("value", {})
+                  if not isinstance(value, dict) or value.get("changed") is not True:
+                      continue
+                  path = str(value.get("path", "")).strip()
+                  if path:
+                      changed_paths.add(path)
+          for path in sorted(changed_paths):
+              print(path)
+          PY
+          )"
+          if [[ -z "${CHANGED_OVERLAYS}" ]]; then
+            echo "No deploy overlay changes recorded in deploy-results payload"
             exit 0
           fi
           git config user.name "deploy-controller-v2[bot]"
           git config user.email "deploy-controller-v2[bot]@users.noreply.github.com"
-          git add apps argocd-apps cluster cluster-prod release
+          while IFS= read -r overlay_path; do
+            [[ -n "${overlay_path}" ]] || continue
+            git add -- "${overlay_path}"
+          done <<< "${CHANGED_OVERLAYS}"
+          if git diff --cached --quiet; then
+            echo "No staged deploy overlay changes"
+            exit 0
+          fi
           git commit -m "chore(deploy): apply release-state resolutions [skip ci]"
           git pull --rebase origin "${GITHUB_REF_NAME}"
           git push origin "HEAD:${GITHUB_REF_NAME}"

docs/START-HERE-GITOPS-ONBOARDING.md

@@ -35,6 +35,17 @@
 bash scripts/ops/scan-gitops-context.sh --repo "$PWD"
 ```
 
+如果要先盘点 `/root/codes` 下当前有哪些仓已经接入、哪些还缺 v2 workflow / service contract / deploy 注册，先跑：
+
+```bash
+uvx --with pyyaml python scripts/ops/audit_workspace_gitops.py \
+  --workspace-root /root/codes \
+  --deploy-root /root/codes/ljwx-deploy \
+  --workflow-templates-root /root/codes/ljwx-workflow-templates \
+  --out-json /tmp/gitops-workspace-audit.json \
+  --out-md /tmp/gitops-workspace-audit.md
+```
+
 ## 3. 新项目快速接入（推荐）
 
 ## Step A: 在 deploy repo 注册服务映射
@@ -123,6 +134,7 @@ bash /root/codes/ljwx-workflow-templates/scripts/quick-onboard.sh \
 
 - 调用 `ljwx-workflow-templates/.github/workflows/gitops-onboarding-gate.yml`
 - 未接入完成时阻断 PR 合并
+- 标准生成物已经是 v2-only；push / `workflow_dispatch` 运行前必须在服务仓配置 `RELEASE_STATE_REPO_TOKEN`
 
 ## Step C: 验证