# 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 --check scripts/refresh-artifact-catalog.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, artifact catalog, catalog service commits, and image tags
  target the selected `origin/main` source commit.
- The artifact catalog clearly separates source commit, artifact commit,
  `ciPublished`, `registryVerified`, and per-service digest state.
- The artifact catalog has real publish and registry digest evidence, or stays
  blocked with `not_published` digests.
- `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`.
- `hwlab-cloud-api` declares the DEV DB env contract:
  `HWLAB_CLOUD_DB_URL` from Secret reference
  `hwlab-cloud-api-dev-db/database-url` and
  `HWLAB_CLOUD_DB_SSL_MODE=require`.
- The local cloud-api health payload reports DB env presence/missing status with
  redacted values only. This is a readiness gate, not live DB evidence.
- `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`.
- `reports/dev-gate/dev-edge-health.json`, when present, records read-only
  public edge, frps, tunnel-health, and k3s observability evidence.
- `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.

The DB gate has two common blocked scopes:

- `cloud-api-db-env-contract`: manifest/Kubernetes placeholders are incomplete.
- `cloud-api-db-health-gate`: runtime env presence is missing. The next task is
  to configure the DEV Secret/env names, not to print or commit any secret
  value.

For catalog commit mismatch, the preflight emits an
`artifactIdentity.refreshCommands.blocked` command. Use it when the source
commit changed but publish is still blocked:

```sh
node scripts/refresh-artifact-catalog.mjs --target-ref origin/main --blocked
```

Only use the published refresh path after `reports/dev-gate/dev-artifacts.json`
proves every frozen service has a registry digest for that same source commit:

```sh
node scripts/refresh-artifact-catalog.mjs --target-ref origin/main --publish-report reports/dev-gate/dev-artifacts.json
```