# Master Development Protocol

## Purpose

This document defines the mandatory engineering lifecycle for the SMPP Gateway project. It governs planning, approval, implementation, verification, review, source control, and collaboration. All contributors and automated agents must follow it.

The governance documents in this directory are authoritative. A project instruction may add stricter requirements, but it must not silently weaken these standards.

## Project Philosophy

- Correctness precedes optimization.
- Runtime safety precedes feature expansion.
- Architecture is approved before code is written.
- Work is delivered in the smallest independently reviewable increments.
- Stable behavior is preserved unless an approved change explicitly replaces it.
- Verification evidence and independent review are required for completion.
- Speculative development is prohibited.

## Mandatory Development Workflow

Every milestone must follow this sequence:

```text
Architecture
    ↓
Approval
    ↓
Implementation
    ↓
Verification
    ↓
Self-review
    ↓
External review
    ↓
Approval
    ↓
Commit
    ↓
Push
    ↓
Merge
```

No milestone may skip, reorder, or silently combine any stage. Approval at one stage does not authorize a later stage.

## Milestone Approval Workflow

1. Define the objective, scope, exclusions, boundaries, production flow, invariants, and acceptance criteria.
2. Obtain explicit architecture approval.
3. Implement only the approved design on the designated feature branch.
4. Complete all required verification and record final results.
5. Perform a strict self-review against the approved architecture and the [review checklist](REVIEW_CHECKLIST.md).
6. Stop and wait for independent external review.
7. Resolve findings narrowly and repeat verification and review.
8. Proceed to source-control actions only after an approving verdict.

## Scope Rules

- Implement only the approved objective.
- Do not redesign approved architecture during implementation.
- Do not implement future work early.
- Do not add convenience features, speculative abstractions, or unrelated refactoring.
- Do not modify unrelated files.
- Preserve explicit exclusions.
- Request renewed architecture approval if implementation reveals a material conflict or required expansion.

## Verification Requirements

Every implementation must run and report:

1. Focused tests for the changed behavior.
2. Relevant regression tests.
3. The complete PHPUnit suite through its final summary.
4. Laravel Pint across the project.
5. `git diff --check`.
6. Any protected-file, dependency, state, or scope checks required by the approved architecture.

Reports must include test totals, assertion totals, skipped tests, failures, formatter status, and diff-check status. Incomplete command output is not a passing result.

## Documentation Requirements

Documentation must remain synchronized with production behavior. Update architecture, roadmap, changelog, operational, security, database, or API documentation when the approved change affects them.

Documentation must:

- Describe implemented behavior only.
- State material exclusions and limitations.
- Distinguish historical behavior from current behavior.
- Avoid contradictions, incomplete text, and unsupported future claims.

## Review Process

Implementation is incomplete until independent review approves it. Reviewers must assess architecture, correctness, invariants, runtime safety, dependencies, scope, testing, documentation, and regression risk.

After implementation, contributors must stop. They must not commit or push automatically. Review findings must be resolved without broadening the approved scope, followed by complete relevant verification.

## Commit Policy

A milestone may be committed only after an explicit approving verdict. A rejected milestone must never be committed. Test-only corrections requested by an approving review must be completed and verified before commit.

Commit approval does not automatically authorize push or merge. Push and merge remain separate workflow gates and require their applicable authorization.

## AI Collaboration Policy

ChatGPT acts as Chief Architect and Independent Reviewer. Codex acts as Implementation Engineer.

Codex must:

- Follow all protected governance documents.
- Implement only approved architecture.
- Never expand milestone scope.
- Run and report all required verification.
- Produce the standard implementation report.
- Stop for independent review.
- Wait for approval before committing.
- Never push or merge without explicit authorization.

AI-authored work is subject to the same security, quality, review, and approval standards as human-authored work.

## Governance Change Control

The following files are protected engineering governance:

- `MASTER_DEVELOPMENT_PROTOCOL.md`
- `ARCHITECTURE_PRINCIPLES.md`
- `CODING_STANDARDS.md`
- `REVIEW_CHECKLIST.md`
- `MILESTONE_TEMPLATE.md`

They may be modified only after an explicit architecture proposal and approval. Governance changes must be reviewed for consistency across the complete set and must follow this protocol.