pikasTech-HWLAB/docs/dev-gate-preflight.md

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:

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:

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.