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.
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.

Files

reports/dev-gate/dev-gate-report.example.json: machine-readable example.
reports/dev-gate/dev-deploy-report.json: DEV deploy apply/preflight result.
scripts/validate-dev-gate-report.mjs: local validator for the report shape.

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:

node --check scripts/validate-dev-gate-report.mjs
node scripts/validate-dev-gate-report.mjs

The validator scans reports/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.

4.2 KiB Raw Blame History