# 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, and
  Secret reference names plus 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.

## Validation

Run:

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