# Phase 5 — Validation & Refinement

> **Deliverable:** consistency, completeness, and usability checks for the whole `CLAUDE.md` system.
> **Index:** [../README.md](../README.md)

## 1. Consistency check
- ✅ Every internal link resolves after the phase reorganization (root `CLAUDE.md` → `docs/phases/…`;
  component docs → `../phase-3-shared/MASTER_*.md`, `../../../CLAUDE.md`, and same-folder siblings).
- ✅ No contradictions between the root orchestrator and component docs — shared rules live once in
  `MASTER_RULES.md`; components reference, not restate, them.
- ✅ The "no copy/backup files" rule appears in `MASTER_RULES.md` and every component doc that has
  legacy duplicates (web core, shop POS, desktop sync).

## 2. Completeness check
- ✅ Every identified boundary has a Phase 2 doc: erp-web-core (+accounting module), shop-pos-api,
  desktop-sync-api.
- ✅ Every integration point is documented in `MASTER_INTEGRATION.md`: ledger events, desktop
  pull/push protocol, shop POS ↔ inventory/ledger, shared models.
- ✅ Commands, tools, principles, and rules each have a dedicated `MASTER_*` file.
- ⚠️ **Open items** (need product/team input, not derivable from code): team size and CI/CD pipeline
  (none detected in-repo) — placeholders noted in Phase 1 and the root file.

## 3. Usability test — simulated scenarios
| Scenario | Path through the docs | Supported? |
|----------|----------------------|:----------:|
| New dev onboards | root `CLAUDE.md` → phase README → component doc | ✅ |
| Feature spanning web core + ledger + desktop sync | `MASTER_INTEGRATION.md` → the 3 affected docs | ✅ |
| Debug a stock mismatch across POS and central inventory | Shop POS doc §8 + web core §7 (stock integrity) | ✅ |
| Refactor shared costing / `StockLedger` | web core §7–8 + `MASTER_INTEGRATION.md §4` | ✅ |
| Add a new module | web core §9 canonical path | ✅ |
| Add a new synced entity | desktop sync doc "Contract" + `MASTER_INTEGRATION.md §2` | ✅ |

## 4. Optimization notes
- Shared rules are centralized (DRY) in `MASTER_*`; components link rather than duplicate.
- Decision aids present: routing table (root), auth-regime table (shop POS), stock-table disambiguation
  ("shop stock ≠ central inventory").
- Each component doc opens with a **Code location** line, so phase-folder placement doesn't obscure
  which code it governs.

## 5. Known risks to watch
- **Link drift** if files are moved again — re-run a link check (grep for `](` targets).
- **Legacy duplicates** remain in the codebase; the docs warn, but a cleanup PR is still advisable.
- **Backward compatibility** for deployed desktop clients — enforce additive-only sync changes.