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.

## 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`.
- Active reports must not present `:6666` or `:6667` as a current public DEV
  endpoint in endpoint, route, health, ingress, API, frontend, or browser
  evidence. Internal k3s service/listen ports may still be `6667` when the
  surrounding field names them as cluster-local service ports rather than
  public endpoints.
- 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.
- `scripts/report-lifecycle.mjs`: lightweight lifecycle helper for validating
  one report or marking a replaced report historical/deprecated after endpoint
  changes.

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

## Invalidate/Rebuild Workflow

When the public DEV endpoint mapping changes, do not rewrite historical
evidence strings. Preserve the old facts and mark any report that can no longer
represent the active gate as historical:

```sh
node --check scripts/report-lifecycle.mjs
node scripts/report-lifecycle.mjs invalidate reports/dev-gate/<old-report>.json \
  --deprecated-endpoint http://74.48.78.17:6667 \
  --reason "Public DEV endpoint moved to frontend :16666 and API/edge :16667" \
  --out reports/dev-gate/historical/<old-report>-legacy-6667.json
node scripts/validate-dev-gate-report.mjs reports/dev-gate/historical/<old-report>-legacy-6667.json
```

Then regenerate the active report through its owning script so the active file
uses `http://74.48.78.17:16666` for browser/frontend evidence and
`http://74.48.78.17:16667` for API/edge/live evidence. Keep PR notes explicit:
which legacy reports were moved or marked historical, which active reports were
regenerated, and which current reports still need real DEV reruns.