fix(arch-008,arch-009): canonical 2-segment permission schema enforced; fix dead role wildcard patterns

docs/permissions.md

@@ -39,6 +39,27 @@ When checking access to an entity, the system resolves in this order (highest wi
 | `delete` | 4 | Admin + transfer ownership |
 | `owner` | 5 | Full control (automatic for owner) |
 
+### Permission Name Schema (canonical)
+
+All module-level permission strings follow the strict **2-segment schema**
+`module:action`, with `*` wildcards allowed in either segment:
+
+| Pattern | Meaning |
+|---------|---------|
+| `contacts:read` | Exact: read contacts |
+| `contacts:*` | All actions on contacts |
+| `*:read` | Read on all modules |
+| `*:*` | Everything (superadmin) |
+
+The runtime matcher (`app/core/permissions.py::_matches_permission`) compares
+segment counts strictly — a 3-segment grant like `core:contacts:read` can never
+match any 2-segment requirement and is therefore **invalid**. The plugin manifest
+validator (`app/plugins/manifest.py`) rejects such patterns at load time.
+
+Historical note (ARCH-008/009): migration 0019 seeded default roles with dead
+3-segment patterns (`core:*:read` etc.); migration 0141 converts existing role
+data to the canonical form.
+
 ---
 
 ## 2. Data Model