pikasTech-HWLAB/docs/m5-mvp-e2e.md

M5 MVP E2E Dry-Run Orchestration

M5 is the static orchestration gate before the first real DEV MVP e2e run. It does not deploy, does not call DEV, does not run browser e2e, and does not read secrets. The source contract gate is:

node scripts/m5-mvp-e2e-dry-run.mjs

The script reads the frozen protocol contracts, the DEV acceptance checklist, fixtures/mvp/runtime.json, and fixtures/mvp/m5-e2e/dry-run-plan.json. It validates the dependency graph and checks that each step has resolvable inputs and outputs.

The L6 external acceptance CLI wraps the same report and dry-run plan:

node tools/hwlab-cli/bin/hwlab-cli.mjs test e2e --env dev --mvp

This command defaults to a JSON dry-run plan. --dry-run is accepted for backward compatibility, but it is no longer required for safety. The output must identify the M0-M5 report source, artifact and DEV health contract counts, two gateway sessions, two box resources, patch-panel status, agent and worker session IDs, evidence records, open blockers, and the statement that no DEV/PROD changes were made.

Dry-Run Flow

Order	Step	Purpose	Required Inputs	Required Outputs
1	DEV health	Confirm the frozen DEV endpoint and recorded edge/frp/D601/cloud health contracts.	DEV endpoint, ingress, edge route, frp, router, cloud API/web health records	Route, tunnel, namespace, cloud service identities
2	Gateway/box status	Confirm gateway, simulator, resources, and capabilities are present.	Gateway sessions, box resources, capabilities	Gateway session, resource IDs, capability IDs
3	Wiring	Confirm the active wiring config is patch-panel owned.	Wiring config, patch-panel status	Wiring config ID, patch-panel status ID
4	Direct hardware call	Validate the direct JSON-RPC hardware operation envelope and field flow.	RPC request/response, resource, capability, patch-panel status	Operation ID, trace ID
5	Audit	Confirm mutating setup and direct operation audit records exist.	Project, gateway, wiring, operation audit records	Direct operation audit ID
6	Agent session	Confirm agent manager, worker, and skills contracts are linked.	Agent/worker sessions, agent health records	Agent session ID, worker session ID
7	Agent hardware call	Validate the agent worker JSON-RPC hardware operation envelope and field flow.	RPC request/response, agent, worker, resource, capability, patch-panel status	Operation ID, trace ID
8	Evidence	Confirm both hardware operations emit trace and evidence records.	Trace events, evidence records	Evidence IDs
9	Cleanup	Confirm worker and gateway transient cleanup are recorded.	Cleanup records, cleanup audit	Cleanup IDs

M0-M4 Dependency Graph

M5 closes over the earlier MVP contracts as contract-only prerequisites:

Source	Provides	Consumed By M5
M0 contract audit	Frozen service IDs, protocol schemas, MVP e2e sequence contract	DEV health, hardware operation envelopes, evidence contract
M1 local smoke	Static parse boundary and dry-run safety posture	DEV health and cleanup safety checks
M2 cloud core	Project record, JSON-RPC envelope, audit surface	Audit, direct hardware call, agent hardware call
M3 hardware loop	Gateway session, box resources/capabilities, wiring config, patch-panel status	Gateway/box status, wiring, direct hardware call, agent hardware call
M4 agent runtime	Agent session, worker session, trace events, evidence, cleanup	Agent session, agent hardware call, evidence, cleanup

The graph must remain acyclic. Each M5 step may only depend on earlier steps except the agent hardware call, which also depends on the already-established wiring step.

Blocker Classes

M5 keeps the blocker classes from the DEV acceptance matrix:

Class	Meaning
contract_blocker	Static contract, schema, checklist, or documentation cannot be parsed or contradicts frozen names.
environment_blocker	DEV endpoint, environment, namespace, or PROD boundary is wrong.
network_blocker	Master edge, frp, D601 route, or public DEV ingress cannot be observed or routes incorrectly.
runtime_blocker	HWLAB cloud, router, gateway, simulator, box simulator, or patch-panel runtime contract fails.
agent_blocker	Agent manager, worker, skills, trace, audit, or cleanup contract fails.
observability_blocker	Artifact identity, commit, image/tag/digest, build source, deploy env, or health timestamp is missing.
safety_blocker	Any prohibited action was attempted: real deployment, PROD target, browser/heavyweight e2e, secret read, force push, or UniDesk runtime substitution.

Real DEV E2E Gate

Do not switch to the real command until all of these are true:

1. node scripts/m5-mvp-e2e-dry-run.mjs passes on origin/main.
2. docs/dev-acceptance-checklist.json and docs/dev-acceptance-matrix.md still freeze DEV at http://74.48.78.17:16667.
3. Every accepted artifact has serviceId, commitId, image, tag, digest or not_applicable reason, buildSource, deployEnv, and healthTimestamp.
4. DEV ingress, master edge proxy, frp, and D601 hwlab-dev/hwlab-router have current route observations.
5. Cloud API/web, gateway, gateway simulator, box simulator, patch panel, agent manager, worker, and skills are all observed in DEV with HWLAB service identities.
6. Gateway and box control remain patch-panel owned; no direct box bypass path is accepted.
7. Agent worker scope, trace, audit, evidence, and cleanup are observable and tied to one DEV project.
8. No blocker class is open and a human has explicitly approved a real DEV smoke.

Only after those gates are satisfied should the runner switch from dry-run to the explicit live DEV command:

hwlab-cli test e2e --env dev --mvp --live --confirm-dev --confirmed-non-production

That command is intentionally not executed by M5. While reports/dev-gate/dev-mvp-gate-report.json contains open blockers, the CLI must return code: "BLOCKED" with blocker evidence instead of substituting fixture output as live DEV evidence.