chore: add dev gate preflight

2026-05-21 16:49:11 +00:00
parent eddfe3ba70
commit 245a236ed0
5 changed files with 1109 additions and 0 deletions
@@ -0,0 +1,62 @@
+# HWLAB DEV Gate Preflight
+
+This preflight is the read-only gate before a real DEV deploy or DEV smoke on
+D601. It decides whether the current `origin/main` can enter the real
+`hwlab-dev` runtime path, or whether it is blocked by missing contract,
+artifact, cluster, registry, edge, or safety evidence.
+
+It does not authorize PROD, restart runtime services, read secrets or tokens,
+substitute UniDesk services for HWLAB runtime, or run heavyweight/browser e2e.
+
+## Command
+
+Run from the repository root:
+
+```sh
+node --check scripts/dev-gate-preflight.mjs
+node --check scripts/src/dev-gate-preflight.mjs
+node scripts/dev-gate-preflight.mjs
+```
+
+The command writes `reports/dev-gate/dev-preflight-report.json` and prints a
+short JSON summary. A `blocked` conclusion means the preflight ran correctly but
+found blockers; the command exits zero by default so the report can be committed
+as evidence. Use `--fail-on-blocked` only in CI jobs that should fail on an open
+gate.
+
+Useful options:
+
+```sh
+node scripts/dev-gate-preflight.mjs --target-ref origin/main
+node scripts/dev-gate-preflight.mjs --report reports/dev-gate/dev-preflight-report.json
+node scripts/dev-gate-preflight.mjs --timeout-ms 5000
+node scripts/dev-gate-preflight.mjs --no-write
+```
+
+## Read-Only Scope
+
+The preflight checks:
+
+- `deploy/deploy.json` and `deploy/artifact-catalog.dev.json` are internally
+  consistent and DEV-only.
+- The deploy manifest and catalog target the selected `origin/main` commit.
+- The artifact catalog has real publish and registry digest evidence.
+- `reports/dev-gate/dev-artifacts.json`, when present, proves all frozen DEV
+  service artifacts were published for the selected `origin/main` commit.
+- `deploy/k8s/base` and `deploy/k8s/dev` parse and remain scoped to
+  `hwlab-dev`.
+- `deploy/frp` and `deploy/master-edge` describe the D601-to-master DEV route
+  on port `6667`.
+- The runner can perform read-only `kubectl` probes against `hwlab-dev`.
+- `http://74.48.78.17:6667/health/live` responds.
+- GHCR manifests are visible without reading credentials.
+- Deploy images do not point at UniDesk, provider-gateway, or microservice-proxy
+  substitutes.
+
+## Verdict Rules
+
+`ready` requires all checks to pass and no open blocker.
+
+`blocked` is expected until the real DEV runtime path can be proven. Each
+blocker includes a `type`, `scope`, `summary`, and `nextTask` so the next task is
+the smallest repair needed before rerunning the preflight.