# Master Development Protocol ## 1. Purpose This document defines the mandatory engineering process, architecture rules, verification requirements, review workflow, and quality standards for the SMPP Gateway project. It is the authoritative development protocol for all project work. Every contributor, reviewer, automation process, and AI collaborator must follow it. Where a milestone instruction is less specific than this protocol, this protocol governs. A deliberate exception requires explicit approval before implementation begins. ## 2. Project Principles All engineering decisions must follow these principles: - Correctness before optimization. - Runtime safety before feature expansion. - Protocol-first architecture for protocol concerns. - Immutable protocol models with valid construction states. - Deterministic behavior for identical inputs and state. - A side-effect-free protocol layer. - Reuse existing validators and protocol authorities. - Never duplicate protocol rules, constants, validation, or state policy. - Deliver the smallest independently reviewable milestone. - Approve architecture before implementation. - Do not perform speculative development. - Prefer explicit contracts and state transitions over implicit behavior. - Preserve stable behavior unless the approved milestone explicitly changes it. ## 3. Mandatory Development Workflow Every milestone must proceed through the following gated workflow: ```text Architecture Proposal ↓ Architecture Approval ↓ Feature Branch ↓ Implementation ↓ Verification ↓ Self Review ↓ Wait for External Review ↓ Approval ↓ Commit ↓ Push ↓ Merge ``` No milestone may skip, reorder, or silently combine these steps. Approval at one gate does not imply approval at a later gate. Implementation must not begin before architecture approval, and commit, push, and merge must not occur before the required review approval. ## 4. Milestone Scope Rules Each milestone must remain within its explicitly approved objective and architecture. - Implement only the approved milestone. - Never implement future milestones early. - Never redesign approved architecture during implementation. - Never broaden scope through inferred or convenient functionality. - Never introduce unrelated refactoring, cleanup, renaming, or dependency changes. - Never modify unrelated files. - Treat out-of-scope behavior as intentionally absent, not as an implementation gap to fill. - Stop and request architectural direction if approved requirements conflict or require material expansion. ## 5. Architecture Rules The architecture must maintain clear ownership and strong boundaries. - Every class and layer must have one coherent responsibility. - Dependencies must point through explicit, minimal contracts. - Protocol parsing, modeling, validation, classification, encoding, and protocol results belong in the protocol layer. - The protocol layer must remain pure and side-effect free. - Routing layers must remain pure and perform only approved classification-to-route mapping. - Handler boundary layers must remain pure unless a later approved milestone explicitly introduces a side-effecting boundary. - Business rules belong only in approved business or application layers. - Persistence behavior belongs only in approved persistence or infrastructure components. - Database access must never appear in protocol, pure routing, or pure handler code. - Protocol objects and protocol-derived results must remain immutable. - Cross-layer communication must use typed contracts and invariant-safe values. - Stable protocol components must be extended through boundaries rather than modified for unrelated downstream concerns. ## 6. Runtime Safety Rules Runtime behavior is a protected system boundary. - `RuntimeLoop` must not be modified unless the approved milestone explicitly targets it. - Receive-path behavior must not change unless required by the approved architecture. - Never introduce hidden retries. - Never introduce hidden reconnects. - Never introduce hidden loops or unbounded work. - Never duplicate reads, decoding, dispatching, routing, handling, encoding, writes, or acknowledgements. - Preserve established failure cleanup and state-transition policies unless an approved milestone explicitly changes them. - Keep I/O counts and ordering explicit and testable. - A failure must not be converted into success or suppressed by a downstream boundary. ## 7. Coding Standards Production code must use the strongest practical representation of its invariants. - Use `readonly` classes and properties where immutability is required. - Model protocol and workflow values as immutable value objects or typed results. - Enforce invariants at construction boundaries. - Reuse existing validators, registries, calculators, encoders, and state authorities. - Do not duplicate validation logic or protocol constants. - Use strict typing and precise return types. - Represent state transitions explicitly and reject impossible transitions. - Keep behavior deterministic and free from ambient state where possible. - Minimize dependencies and expose only the contracts required by the responsibility. - Prefer fixed, sanitized failure categories over leaking implementation details. - Do not edit vendor packages; use configuration, adapters, or wrappers. - Preserve tenant isolation and never query tenant-owned data without explicit tenant scoping. - Store monetary values as integers and never use floating-point money. - Never expose credentials, passwords, API keys, or provider secrets in logs or errors. ## 8. Testing Requirements Every milestone must add tests proportional to its behavior and risk. New functionality without corresponding tests is incomplete. Required coverage includes: - Focused tests for the new behavior. - Regression tests for stable neighboring behavior. - Invariant tests for valid and impossible construction states. - Boundary tests for lengths, ranges, truncation, encoding, and state limits where applicable. - Production-path tests using the real composition path with controlled test doubles at external boundaries. - Failure-path tests for each meaningful failure family. - Meaningful branch coverage, including ambiguity and conflict cases. - Invocation-count tests when the architecture requires exactly-once behavior. - Identity-retention tests when values or failures must pass through unchanged. - State-transition and cleanup assertions where runtime state is involved. Tests must prove externally meaningful behavior rather than merely restating implementation details. Test doubles must not bypass the production code whose behavior they are intended to verify. ## 9. Verification Requirements Every milestone must execute and record all of the following: 1. Focused PHPUnit tests for the milestone. 2. Relevant regression PHPUnit tests. 3. The complete PHPUnit suite through its final summary. 4. Laravel Pint across the full project. 5. `git diff --check`. Verification must report test counts, assertion counts, skipped tests, failures, formatter status, and diff-check status. A command that terminates without a final result is not a passing verification and must be diagnosed or rerun to completion. Protected-file comparisons, scope scans, or other milestone-specific safety checks must also be recorded when required by the architecture. ## 10. Documentation Requirements Documentation must remain synchronized with approved production behavior. When applicable, update: - `docs/architecture.md` - `docs/ROADMAP.md` - `docs/CHANGELOG.md` Documentation must describe only implemented behavior, identify explicit exclusions, and distinguish historical milestone behavior from current behavior. It must not claim future functionality, contain contradictory status statements, or retain malformed and truncated text. ## 11. Implementation Report Format Every completed milestone must report exactly these sections: 1. Files changed 2. Architecture summary 3. Production summary 4. Tests added 5. Verification summary 6. Known limitations 7. Commit status Reports must be factual, concise, and supported by completed verification. Known limitations and intentionally excluded features must not be presented as implemented behavior. ## 12. Review Rules After implementation and verification, stop. - Never commit automatically. - Never push automatically. - Wait for architecture and code review. - Respond narrowly to review findings. - Implement only approved corrections. - Rerun verification after every correction. - Repeat review and correction until approval is granted. - Do not treat passing tests as a substitute for review approval. ## 13. Commit Policy Commits are permitted only after the final review verdict is: - `APPROVE`, or - `APPROVE WITH TEST-ONLY CORRECTIONS`, after those corrections and required verification are complete. Never commit after a `REJECT` verdict. Never push an unapproved milestone. A commit authorization does not automatically authorize a push or merge; each remaining workflow gate must still be followed. ## 14. Future Architecture Evolution Future milestones must extend the system through well-defined contracts and boundaries. Stable protocol components must not be modified to absorb persistence, application routing, tenancy, business processing, or operational concerns. When new capabilities require side effects, introduce them at an explicitly approved boundary outside pure protocol, routing, and handler layers. Architecture evolution must remain incremental, typed, testable, and compatible with existing runtime safety guarantees. ## 15. AI Collaboration Policy This project uses ChatGPT as the architecture authority and independent reviewer. Codex acts as the implementation engineer. Codex must: - Follow this master development protocol. - Implement only architecture explicitly approved by ChatGPT and the project owner. - Never bypass architecture or code review. - Never expand milestone scope. - Never introduce speculative future behavior. - Always execute and report the required verification. - Preserve protected runtime and protocol boundaries. - Stop after implementation and wait for approval before committing. - Never push or merge without explicit authorization. AI-generated work is subject to the same architecture, security, testing, documentation, review, and approval requirements as human-authored work.