Meridian Field Services: instructional example, not project evidence
The shape is a decision against this architecture: never a default ratio, never ASCII art. The size contract makes the layers enforceable in CI.
| Layer | Target share | Rationale | Tooling |
|---|---|---|---|
| API unit | ~70% | Monolith logic density | pytest |
| API integration | ~25% | Queue + DB seams | pytest + local services |
| Board static + types | heavy | Trophy base | tsc · eslint |
| Board component-integration | dominant | Where board bugs live | vitest + testing-library |
| End-to-end | thin | Critical path only | playwright |
Size contract: small (no network, under 60 s) · medium (local services only) · large (unrestricted, staging only). CI fails a mislabeled test. Manual on purpose: exploratory dispatch-floor sessions with M. Chen's team before cutover, the judgment calls a script cannot encode.
| Effort concentrates on | Risk entry | Suites |
|---|---|---|
| Assignment integrity | double-assignment risk[2] | Race + idempotency suites |
| Feed-loss degradation | telematics vendor risk[2] | Failure-injection suite |
| Propose-only rework containment | union clarification[2] | Recommendation-module tests isolated behind its seam |
Deliberately light: read-only reporting views, low blast radius, no contested logic; accepted by A. Reyes and E. Sandoval. Said explicitly, never implied.
API: 85% line floor, measured by the Python coverage tool. Board: 75%, measured by the frontend runner. Excluded, listed: migrations, generated code.
| Environment | Topology parity | Data | Integrations | Gates it may run |
|---|---|---|---|---|
| dev | Services only | Synthetic | Stubbed | Unit & integration |
| pilot | Production topology, Toronto scale | Synthetic + live telematics feed | Real | End-to-end & acceptance |
| production | Full (deployment view[1]) | Real | Real | Release verification only |
| Data class | Mechanism | Privacy posture |
|---|---|---|
| Technicians & jobs | Generated; edge-length names included (longest, empty, accented) | none |
| Positions | Generated tracks; live feed in pilot only | Location = personal-restricted (classification[3]); never leaves production |
| Reason codes | The real governed list | Public/internal |
| Baseline comparisons | Production aggregates only (shadow window[4]) | No row-level copies |
Quality metrics, reported monthly to the steering tier: defect escape rate (found-after-release / total) · critical-path suite duration · flaky quarantine count · mean time to fix a blocking gate.
| Check | Layer | Blocking? | Owner | Fix timeline |
|---|---|---|---|---|
| Unit + types + lint + static security scan | static/unit | blocking on merge | feature team | pre-merge |
| Integration suite | integration | blocking | feature team | pre-merge |
| End-to-end critical path | e2e | informational daily → blocking at release | K. Yamada | 2 business days |
| Dependency scan | supply chain | criticals block release (security gates[3]) | eng lead | per severity SLA |
| Quarantined flaky tests | any | informational only | test author | 30-day clock |
Flaky policy: quarantine keeps the test running outside the required set, owner paged, thirty-day clock to fix or remove; never silent disablement. Regression: selective per change map; full suite nightly and pre-release. Release gate: automated for low-blast-radius; a human gate only for schema migrations, permission changes, and provider-gateway policy edits.
Command palette: defined once; stories reference it (US-3 agent handoff cites these[5]):
Deterministic layer: every AI-authored change passes the palette's lint, type, static-analysis, and unit gates before any review opinion counts. Human checkpoint: required regardless of green gates for the named high-blast-radius classes (schema, permissions, gateway policy, the same classes as the release gate); the reviewer verifies boundary adherence (the story's always-ask-never list) and test meaningfulness, not style. Story contract: agent-flagged stories cite palette commands; the agent's checks and QA's checks are the same checks (user stories[5]).
| Phase | Entry criteria | Exit criteria |
|---|---|---|
| Unit & integration | Branch compiles, feature open | Coverage floors met · zero failing required checks |
| End-to-end on staging | Main green | Critical-path suite green · zero open criticals |
| Acceptance | 48 stable staging hours | Per the story sign-off discipline (Acceptance & Sign-off[5]) |
| Severity ↓ / Priority → | High priority | Low priority |
|---|---|---|
| Critical severity | Fix same day | Fix before next release |
| Minor severity | Fix this sprint | Backlog: no timeline pretended |
Severity set by K. Yamada (technical impact); priority set jointly with A. Reyes (business urgency): two axes, two owners; conflating them is the classic triage failure.
Nothing acceptance-shaped is written here; this section indexes where acceptance content lives, and that is its whole job.
Outlines: the FRDs[6] (the only Given/When/Then anywhere). Concrete rows with test-case ids: the stories[5]. Executable definitions: the test-case register[7]; its exported view is the test-cases artifact. Example mapping gates Ready (readiness gates[5]).
| Question | Owner | Answer by | Blocks |
|---|---|---|---|
| Does hub-six scale require a dedicated load test before rollout, engaging the performance-scenarios deliverable? | E. Sandoval | Aug 15, 2026 | The release-gate posture for the rollout slice only |
Omission note (how §6 renders on an all-human codebase): "§6 AI-Generated-Code Verification omitted: no agent-flagged stories, no AI-authored production code. Rationale recorded in adaptation event #1."