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

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.

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