# 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:

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