HWLAB Code Queue
108 lines
4.2 KiB
Markdown
108 lines
4.2 KiB
Markdown
# 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.
|