# HWLAB DEV Gate Report Contract This document defines the canonical DEV gate report format for `pikasTech/HWLAB#31` and the DEV deploy apply report extension for `pikasTech/HWLAB#33`. It is the handoff surface for the parallel workstreams behind `#7/#9/#12/#17/#20/#21/#22/#23/#24/#25/#26`, so source-contract evidence, local smoke, dry-run notes, real DEV prerequisites, and remaining blockers stay in one place. This contract is report-only. It does not authorize a real DEV or PROD deployment. ## Report Lifecycle Each committed DEV gate report must carry `reportLifecycle`: - `state: "active"` means the report belongs to the current DEV gate surface. Its `activeEndpoint` must be `http://74.48.78.17:16667`, its `activeBrowserEndpoint` must be `http://74.48.78.17:16666`, and `deprecatedEndpoint` must be `null`. - `state: "historical"` means the report is retained only for evidence provenance. It may name a deprecated endpoint such as `http://74.48.78.17:6667`, but it must stay blocked/non-green and cannot be consumed as active acceptance evidence. - Active reports may preserve a legacy public endpoint only inside an explicit `runtimeSmoke.legacyPublicEndpoint` object with `status: "deprecated"` and `activeGreenEligible: false`. - Active reports must not present `:6666` or `:6667` as a current public DEV endpoint in endpoint, route, health, ingress, API, frontend, or browser evidence. Internal k3s service/listen ports may still be `6667` when the surrounding field names them as cluster-local service ports rather than public endpoints. - M3 DEV-LIVE remains narrower than report freshness: it requires `res_boxsimu_1:DO1 -> hwlab-patch-panel -> res_boxsimu_2:DI1` in real DEV plus operation, audit, and evidence identifiers. SOURCE, LOCAL, DRY-RUN, fixture, and historical report evidence are support/diagnostics only. - M5 DEV-LIVE cannot be inferred from public entrypoint reachability. Reports must keep EDGE/ROUTE live, DB live/degraded, M3 hardware trusted loop, M4 agent loop, and artifact/desired-state source status as separate layers. If the only read-only evidence is `16666/16667` reachability, M5 must remain blocked/non-green. - Gate/report aggregators must cross-check DB, M3, M4, and M5 acceptance against the corresponding source reports before showing `DEV-LIVE` or green status. Frontend/browser revision facts, public route reachability, source manifests, local smoke, dry-run output, and fixtures are non-promoting support evidence for those layers. ## Files - `/tmp/hwlab-dev-gate/dev-gate-report.example.json`: machine-readable example. - `/tmp/hwlab-dev-gate/dev-deploy-report.json`: DEV deploy apply/preflight result. - `scripts/validate-dev-gate-report.mjs`: local validator for the report shape. - `scripts/report-lifecycle.mjs`: lightweight lifecycle helper for validating one report or marking a replaced report historical/deprecated after endpoint changes. ## Required Fields Every report must include: - `$schema` - `$id` - `reportVersion` - `issue` - `taskId` - `commitId` - `acceptanceLevel` - `devOnly` - `prodDisabled` - `reportLifecycle` - `sourceContract` - `validationCommands` - `localSmoke` - `dryRun` - `devPreconditions` - `blockers` ## Field Rules - `issue` is fixed to `pikasTech/HWLAB#31`. - `devOnly` must be `true`. - `prodDisabled` must be `true`. - `commitId` must be a git SHA string. - `taskId` and `acceptanceLevel` must be stable slugs, not free-form prose. - `validationCommands` must record the exact commands used to validate the report contract. - `sourceContract.documents` should point at the frozen docs that define the gate contract. - `localSmoke`, `dryRun`, and `devPreconditions` should each summarize their own state with a status, command list, evidence list, and short summary. - `blockers` should list the remaining open blockers as machine-readable objects. - DB gate extensions may add redacted `db`, `cloudApiDb`, or check evidence objects. These must include only env names, presence/missing status, Secret reference names, and redacted readiness layers such as `configReady`, `envInjected`, `connectionAttempted`, `connectionResult`, and `liveConnected`. They must not include connection strings, passwords, tokens, DB hostnames from the secret URL, or fixture output presented as live DB evidence. - DEV deploy apply reports must include `devDeployApply.templateJobReplacementPolicy` and `devDeployApply.templateJobReplacements`. These fields document the DEV-only suspended template Job replacement allowlist, plus each planned or executed replacement with namespace, Job name, old image, new image, and result. The allowlist is limited to `hwlab-agent-worker-template` and `hwlab-cli-template` in `hwlab-dev`; it must not generalize to ordinary Jobs or non-Job resources. ## Validation Run: ```sh node --check scripts/validate-dev-gate-report.mjs node scripts/validate-dev-gate-report.mjs ``` The validator scans `/tmp/hwlab-dev-gate/*.json` by default. It only checks the contract shape and the frozen report metadata; it does not run any DEV or PROD deployment. For M5 aggregator reports, the validator also verifies non-promotion boundaries by reading the declared source report paths. DB acceptance must come from redacted live DB readiness (`ready=true`, `connected=true`, and `liveDbEvidence=true`); M3 must come from a real live operation with operation, trace, audit, and evidence identifiers; M4 must come from the live preflight; and M5 must remain blocked until DB, M3, M4, and the M5 live source report each pass their own source checks. Frontend route, source, dry-run, and fixture evidence may remain in the report, but it cannot promote those layers to DEV-LIVE acceptance. ## Invalidate/Rebuild Workflow When the public DEV endpoint mapping changes, do not rewrite historical evidence strings. Preserve the old facts and mark any report that can no longer represent the active gate as historical: ```sh node --check scripts/report-lifecycle.mjs node scripts/report-lifecycle.mjs invalidate /tmp/hwlab-dev-gate/.json \ --deprecated-endpoint http://74.48.78.17:6667 \ --reason "Public DEV endpoint moved to frontend :16666 and API/edge :16667" \ --out /tmp/hwlab-dev-gate/historical/-legacy-6667.json node scripts/validate-dev-gate-report.mjs /tmp/hwlab-dev-gate/historical/-legacy-6667.json ``` Then regenerate the active report through its owning script so the active file uses `http://74.48.78.17:16666` for browser/frontend evidence and `http://74.48.78.17:16667` for API/edge/live evidence. Keep PR notes explicit: which legacy reports were moved or marked historical, which active reports were regenerated, and which current reports still need real DEV reruns.