# Specification Quality Checklist: SP-05 — Agent Management & Investor Logic

**Purpose**: Validate specification completeness and quality before proceeding to planning
**Created**: 2026-06-15
**Feature**: [spec.md](spec.md)

## Content Quality

- [x] No implementation details (languages, frameworks, APIs)
- [x] Focused on user value and business needs
- [x] Written for non-technical stakeholders
- [x] All mandatory sections completed

**Notes**:
- The spec mentions specific technologies (Laravel, PostgreSQL, JSONB, Eloquent, Spatie, bcmath) only as the existing system context — not as implementation directives. The "what" is separated from the "how"; the "how" is delegated to the Plan phase.
- The FR section explicitly references Service / Controller / Model patterns only to mandate their existence (per Constitution), not to prescribe their structure.
- Translation keys are referenced because they are part of the system contract (Constitution "ALWAYS" + `07_02`), not as implementation prescriptions.

## Requirement Completeness

- [x] No [NEEDS CLARIFICATION] markers remain
- [x] Requirements are testable and unambiguous
- [x] Success criteria are measurable
- [x] Success criteria are technology-agnostic (no implementation details)
- [x] All acceptance scenarios are defined
- [x] Edge cases are identified
- [x] Scope is clearly bounded
- [x] Dependencies and assumptions identified

**Notes**:
- 9 Open Questions are documented in §8 with defaults stated. These are NOT [NEEDS CLARIFICATION] markers because each has a defensible default; they are surfaced for the product owner to confirm or override.
- Every FR has a source trace (BR-XXX-N, FR-3.X, or 06_03/06_08/05_XX).
- Every AC has a source trace to BR/FR/NFR.

## Feature Readiness

- [x] All functional requirements have clear acceptance criteria
- [x] User scenarios cover primary flows
- [x] Feature meets measurable outcomes defined in Success Criteria
- [x] No implementation details leak into specification

**Notes**:
- 38 ACs cover 40 FRs (some FRs share an AC).
- 10 user stories (8 explicit + 1 deletion-is-forbidden + 1 edge-cases section) cover the entire FR-3 module in `02_01`.
- All 8 endpoints in `06_03_AGENTS_ENDPOINTS.md` have corresponding User Stories and AC coverage.
- All 7 BR-005 rules have ≥ 1 AC.
- All 4 agent/shares error scenarios in `06_08` have ≥ 1 AC (covered by AC-013 through AC-020).

## Source Coverage Matrix

### Endpoints in 06_03_AGENTS_ENDPOINTS.md

| Endpoint | User Story | FR Coverage | AC Coverage |
|----------|-----------|-------------|-------------|
| GET /api/v1/agents | §3.2 | SP-05-FR-001, -002, -003, -034, -035, -037, -039 | AC-001 |
| POST /api/v1/agents | §3.1 | SP-05-FR-004, -005, -006, -007, -008, -032, -034 | AC-002, AC-003, AC-013 |
| GET /api/v1/agents/{id} | §3.3 | SP-05-FR-009, -012, -013, -014, -015, -016, -017, -018, -019, -020, -030 | AC-004, AC-005, AC-006, AC-014 |
| PUT /api/v1/agents/{id} | §3.4 | SP-05-FR-010, -030, -031 | AC-007, AC-027 |
| DELETE /api/v1/agents/{id} | §3.9 | SP-05-FR-011, -024 | AC-020, AC-024 |
| POST /api/v1/agents/{id}/shares | §3.5 | SP-05-FR-021, -022, -032, -033, -034 | AC-008, AC-009, AC-018, AC-019, AC-021, AC-022 |
| PATCH /api/v1/agents/{id}/shares/{id} | §3.6 | SP-05-FR-023, -024, -025, -030, NFR-D-003, NFR-D-004, NFR-D-005 | AC-010, AC-015, AC-016, AC-023, AC-025 |
| DELETE /api/v1/agents/{id}/shares/{id} | §3.7 | SP-05-FR-026, -027, -028, -030, NFR-D-005 | AC-011, AC-017, AC-023, AC-025 |
| GET /api/v1/agents/{id}/shares-log | §3.8 | SP-05-FR-029, -030 | AC-012, AC-026 |

### Business Rules in BR-005 (Agent & Investor)

| Rule | AC Coverage |
|------|-------------|
| BR-005-1 Permanent Investor Status | AC-022, AC-002 |
| BR-005-2 Share Value (USD 200) | OUT OF SCOPE — not surfaced in any API per `06_03`; will be documented in implementation constants. Not a spec concern. |
| BR-005-3 Investor Profit Calculation | AC-004, AC-006 (verified), plus `computed_profit` formula is in §4.1 SP-05-FR-013 |
| BR-005-4 Shares Balance Calculation | AC-005 |
| BR-005-5 Shares Lock Period | AC-015, AC-016, AC-017 |
| BR-005-6 Logical Modification | AC-010, AC-023, AC-025 |
| BR-005-7 Logical Deletion | AC-011, AC-023, AC-025 |

### BR-001 (Client Entity) cross-references

| Rule | AC Coverage |
|------|-------------|
| BR-001-1 Hard Immutability | AC-020, AC-024 |
| BR-001-2 Shared Data Structure | Implicit — covered by SP-04 already |
| BR-001-3 Role Inference via Flags | Implicit — covered by SP-03/SP-04 already |
| BR-001-4 Customer Flag Timing | Out of SP-05 scope (customer creation) |
| BR-001-5 Agent Flag Timing | AC-002, AC-003 (verified via `isAgent()`) |
| BR-001-6 Investor Flag Permanence | AC-002, AC-022 |
| BR-001-7 Reference Number Format | Implicit — covered by SP-03 trait; not a SP-05 spec concern |

### Error Scenarios in 06_08 (Agent & Shares)

| Scenario | AC Coverage |
|----------|-------------|
| `agent.phone_unique` (422) | AC-013 |
| `agent.not_found` (404) | AC-014 |
| `shares.not_latest` (403) | AC-015, AC-017 |
| `shares.lock_period_expired` (403) | AC-016, AC-017 |

### Acceptance Criteria from 02_03

| AC | Coverage in SP-05 |
|----|-------------------|
| AC-004 Client Immutability | AC-020, AC-024 |
| AC-010 Client Type Flags Transaction Safety | AC-002, AC-003, AC-008, AC-021, AC-022 |
| AC-011 Share Log Logical Operations | AC-010, AC-011, AC-023, AC-025 |
| AC-019 Localization Compliance | AC-028, AC-029 |

## Cross-Constitution Compliance

- [x] **§I Clean Architecture** — SP-05-FR-035..040 enforce layer separation
- [x] **§II Domain Separation** — SP-05-FR-035 mandates Agent domain structure
- [x] **§III Test-First** — AC-036, AC-037, AC-038 enforce coverage targets
- [x] **§IV Spec-Driven** — this spec exists; ready for /speckit.plan
- [x] **§V Immutability Principle** — SP-05-FR-011, AC-020, AC-024
- [x] **§VI Installment Due Date** — N/A to this spec (no installment date generation)

### ALWAYS/ASK/NEVER verification

- [x] **ALWAYS**: `__()` translation keys (SP-05-FR-039, AC-028)
- [x] **ALWAYS**: Unified Response format (SP-05-FR-037)
- [x] **ALWAYS**: FormRequest validation (SP-05-FR-036)
- [x] **ALWAYS**: bcmath for financial math (SP-05-FR-014)
- [x] **ALWAYS**: Explicit `$fillable` (SP-05-NFR-S-009, AC-034)
- [x] **ALWAYS**: Factory `fake('ar_SA')` — covered by SP-04 inheritance; spec does not introduce new factories
- [x] **ALWAYS**: No raw SQL (no SQL mentioned in spec body)
- [x] **NEVER**: Delete any client/agent (SP-05-FR-011, AC-024)
- [x] **NEVER**: Return `client_type_flags` (SP-05-FR-030, AC-026)
- [x] **NEVER**: `saveQuietly()` for flag updates (SP-05-NFR-D-002, AC-002 indirectly)
- [x] **NEVER**: Hardcoded language strings (SP-05-FR-039, AC-028)
- [x] **NEVER**: Float/double in financial calculations (SP-05-FR-014)

## Notes

- Items marked incomplete require spec updates before `/speckit.clarify` or `/speckit.plan`
- This checklist is for validation only. The spec is ready for the Plan phase.
- The 9 Open Questions (OQ-1..9) have defensible defaults stated. The product owner may address them in a clarification round, but the spec does not block on them.
- BR-005-2 (USD 200 per share) is not surfaced in any API in `06_03`; it is a domain constant handled in the Plan/Implementation phase.