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.

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.