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:

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:

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.