Native App Decision Gate

First question: which required journey actually fails on the PWA path?

A product team says, “It is time to have a real native app.” Engineering replies, “A PWA is cheaper, so native is unnecessary.” Either statement can be wrong because both start with a solution label instead of an evidenced requirement.

This lesson reverses the sequence. Start with a concrete required_journey; bind current COM-036 evidence for install/offline/push/camera and any relevant capability; record the residual gap and fallback quality; then state the native capability delta and lifecycle burden separately. The output is neither pro-native nor pro-web. It is a PWA-vs-Native Decision Gate & Evidence Record v1 that a human reviewer can reproduce from visible evidence.

Lesson boundary

COM-037 owns the decision whether, why, and how narrowly a native/hybrid surface is justified. It does not own Service Worker, Push, Camera, or installability implementation; those evidence slices come from COM-036. It also does not define owner-exception governance; that belongs to AGN-001.

Three boundary rules:

1. API or manifest presence is not capability parity.
2. App Store availability is not proof that the product requires native.
3. A prior approval is not permanent authority; browser/OS, cost, journey, or policy changes require re-running the gate.

Mental model: Requirement → Evidence → Gap → Option → Burden → Decision

Core flow:

required journeys → current PWA evidence → residual gap/fallback → compare PWA repair | narrow hybrid | full native → distribution/privacy/security/lifecycle gate → REJECT | HOLD | HYBRID_APPROVED | NATIVE_APPROVED → review/retirement trigger

If decisive evidence is UNKNOWN, DISPUTED, or STALE, the decision remains HOLD. NATIVE_APPROVED is not a preference; it is a state with auditable preconditions.

Keep four claim types separate

FACT — Web platform. Web App Manifest, Service Workers, Push API, and Media Capture are distinct mechanisms with different lifecycle, permission, implementation, and user-agent constraints. “We have a PWA” is therefore not evidence for every journey.

FACT — Distribution. Apple Guideline 4.2 currently expects App Store submissions to provide adequate utility and an experience beyond a merely repackaged website. That is a channel constraint, not an instruction to build native.

INFERENCE. If an important requirement cannot be met through the evidenced web/PWA path with an acceptable fallback, and a specific native delta closes that gap, a native or hybrid surface becomes easier to justify. If the gap disappears, another codebase and release/support lifecycle may be cost without outcome.

DESIGN — MAKNOW. The fields, typed states, local gates, and review triggers in this lesson are MAKNOW design choices, not vendor or W3C requirements.

The 26-field decision contract

The working record has twenty-six fields:

decision_id, required_journey, capability_requirement, pwa_evidence_ref, web_support_state, fallback_quality, native_capability_delta, background_requirement, offline_requirement, hardware_integration_requirement, performance_target, distribution_channel, store_policy_dependency, release_review_dependency, privacy_permission_surface, security_boundary, team_skill_constraint, build_cost_class, ongoing_maintenance_class, release_cadence, observability_requirement, support_burden, decision_state, exception_authority, review_trigger, evidence_ref.

Gate 1 — Write the required journey before the platform

“Warehouse users must continue hardware scanning under intermittent connectivity and produce traceable sync after reconnect” is actionable. “We need a mobile app” is not.

Gate 2 — Record PWA evidence capability by capability

pwa_evidence_ref must state what was actually tested or established on the target browser/OS mix. API presence, a vendor support page, or a desktop test is not enough by itself for the target mobile fleet.

Gate 3 — Keep support state separate from fallback quality

web_support_state can be SUPPORTED, PARTIAL, UNSUPPORTED, UNKNOWN, DISPUTED, or STALE. A PARTIAL capability can still have an ACCEPTABLE fallback, making native unnecessary; or an UNACCEPTABLE fallback, making the gap material.

Gate 4 — State the native capability delta precisely

Name what native actually adds: persistent background execution, hardware integration, a latency target, deeper OS integration, or another measurable change. An ambiguous delta produces an ambiguous approval.

Gate 5 — Separate background, offline, hardware, and performance

Do not collapse these into one “mobile capability.” Offline can be strong in the PWA while one hardware journey remains weak. In that case, a narrow companion can be superior to a full native rewrite.

Gate 6 — Treat distribution and review as independent constraints

App Store distribution has store-policy and release-review dependencies. Enterprise/direct distribution has a different set. Neither proves product fit on its own.

Gate 7 — Compare privacy and security surface

Record permission scope, local storage/secrets, device identifiers, deep links, background services, and attack surface added by the new option. More capability often means more operational and security surface.

Gate 8 — Separate build cost from recurring burden

One-time implementation is not the whole cost. ongoing_maintenance_class, release_cadence, observability_requirement, and support_burden remain visible. Two codebases, store releases, and an OS/device test matrix can change the decision.

Gate 9 — Prefer the smallest option that closes the real gap

Baseline options are PWA repair/fallback improvement, a narrow hybrid/native companion, and full native. If a small companion closes one hardware/background gap, a full native client needs additional evidence.

Gate 10 — Define review and retirement triggers

Every approval needs a trigger: browser capability change, OS policy change, support burden threshold, weak adoption, permission failure rate, store policy change, or a native delta that is no longer material.

Worked examples

1. Narrow residual gap → HYBRID_APPROVED

Checkout, catalog, and account management work well as a PWA. One warehouse journey needs background scanning plus hardware integration and the manual fallback creates operational error. A native companion closes only that journey; build and maintenance are medium and the success metric is explicit. HYBRID_APPROVED is defensible; full native is not.

2. Gap closes → REJECT

A later target-browser release closes the original constraint and the fallback becomes acceptable. Reusing the historical decision would keep native forever; re-running the gate shows no remaining native justification and moves toward REJECT/retirement.

3. Missing decisive evidence → HOLD

The team says push “does not work on customer devices,” but the target OS mix and permission evidence are missing. The correct decision is HOLD, not guessed NATIVE_APPROVED.

4. Full native only for multiple persistent hard requirements

Several critical journeys need background execution, tight latency, and hardware integration; fallbacks are unacceptable; native closes the documented gaps; privacy/security review is complete; recurring burden remains inside tolerance. NATIVE_APPROVED is defensible until a review trigger invalidates its assumptions.

Common failure modes

• Preference-first architecture: “I prefer native” or “web is always better” before evidence.
• API-presence parity: an API name is treated as proof of target support.
• Single-gap overreach: one narrow gap causes a full native rewrite.
• Store mystique: App Store presence is treated as automatic product justification.
• Fallback blindness: partial support is evaluated without fallback quality.
• One-time-cost bias: build cost is counted while releases, support, and observability disappear.
• Privacy/security omission: new capability is added without permission/security surface.
• Weighted-score theater: arbitrary points hide a hard constraint.
• Permanent approval: last year’s decision survives changed evidence.
• Forced success: incomplete evidence is coerced into an approval state.

Alternatives and trade-offs

PWA repair keeps one delivery surface and can ship quickly, but cannot close a target-platform gap that truly remains unsupported.

Narrow hybrid/native companion can deliver the best outcome-to-burden ratio for one device or background capability. It adds integration boundaries and cross-surface support complexity.

Full native can offer deeper device/OS integration but expands codebase, release process, store review, test matrix, and support burden. It is strongest when several persistent required journeys need that capability—not because “serious products are native.”

Do not collapse these trade-offs into one vague score. Some evidence is blocking, some decisive, and some merely advisory.

Experienced bridge: review questions

1. Which required journey fails or degrades today?
2. What is the exact target browser/OS evidence?
3. Is the fallback acceptable, and by what metric?
4. What measurable native capability delta closes the gap?
5. Could a narrow companion close it instead?
6. What distribution/review dependency is introduced?
7. How does privacy/security surface change?
8. What are build, maintenance, release, and support burdens?
9. What success metric proves the new surface works?
10. What trigger causes review, narrowing, or retirement?

If questions 1 or 4 have no precise answer, the team does not yet have an architecture decision; it has a preference.

Guided and independent practice

Run the offline lab:

python -B lab/COM-037-LAB1/learner/run_checks.py

Start with the baseline. Then mutate the evidence: remove the capability gap; double maintenance/support burden; add an OS-level requirement; make store review materially relevant; and mark decisive evidence UNKNOWN.

For transfer, assume a later browser release closes the previous gap while the native client becomes more expensive to support. Do not copy the baseline approval. Rebuild from required_journey and current evidence.

Verification evidence

The evaluator must catch at least:

• NATIVE_APPROVED or HYBRID_APPROVED with no real residual gap;
• approval when decisive evidence is UNKNOWN/DISPUTED/STALE;
• approval without a clear native capability delta;
• full native when a narrow companion closes the gap with lower burden;
• an App Store label used as justification without utility/distribution evidence;
• a large maintenance/support increase without recomputation;
• transfer that treats the prior approval as an oracle.

The oracle is the visible fixture and deterministic rules, not hidden model reasoning, a live store, or production telemetry.

Assessment and transfer

The summative task requires four moves: explain the COM-037 boundary; build the complete baseline artifact; diagnose the mutation that removes the only native-justifying capability gap; and rebuild the changed-context decision from current evidence.

A strong answer does not merely name the final state. It shows which field was decisive, which evidence was blocking, which evidence was advisory, and what review trigger comes next.

References and freshness

• W3C-APPMANIFEST — Web Application Manifest; rechecked 2026-09-14.
• W3C-SERVICE-WORKERS — Service Workers; rechecked 2026-09-14.
• W3C-PUSH — Push API; rechecked 2026-09-14.
• W3C-MEDIA-CAPTURE — Media Capture and Streams; rechecked 2026-09-14.
• APPLE-APP-REVIEW — App Review Guidelines, especially 4.2; rechecked 2026-09-14.
• LOCAL_DESIGN_AUTHORITY — frozen COM-037 Bible for fields and states.

Recheck Apple policy by 2026-11-02 and W3C/platform assumptions by 2026-12-31, or earlier after a material semantic change. No vendor document becomes MAKNOW decision authority.