# mail-app-pocketbase — Rules (the 9 things per FVW §11.9)

**Module:** `mail-app-pocketbase`

---

## 1. Capability declaration

This module is a **clean-room PHP reimplementation**. It does not depend on any AGPL-licensed code. It is MIT-licensed. The interface signatures follow FvW v8 conventions (PSR-4 autoload under `FreshCloud\Mail\<Namespace>\`).

## 2. Do-not-proceed rule

If the operator requests a feature that requires AGPL code, REFUSE. If the operator requests a feature that violates the per-module scope, ask before proceeding.

## 3. Contract primacy

The `module.json` + `composer.json` + `module-meta.json` define the contract. The PHP code conforms to the contract. The tests prove the contract. If the code needs to change in a way that breaks the contract, update the JSON files FIRST, then the code, then the tests.

## 4. Anti-drift enforcement

Every commit to this module must:
- Not modify files outside `modules/mail-app-pocketbase/` without explicit operator permission
- Keep `module.json.version` and `module-meta.json.version` in sync
- Keep `composer.json.autoload.psr-4` map in sync with the actual `src/` directory
- Pass `vendor/bin/phpunit tests/` for the module

## 5. User-simulator requirement

Before committing a change, run a smoke test:
- `php -r "require 'vendor/autoload.php'; $x = new FreshCloud\\Mail\\<Namespace>\\PrimaryClass(); echo 'OK'; echo PHP_EOL;"`
- If the class loads cleanly, the autoload + PSR-4 map is correct.

## 6. Plan-as-law doctrine

Per FvW v8 §38, any non-trivial change to this module needs a plan-as-seed. Plans are saved as Pact Idea nodes (type=plan). The plan is a contract, not a prison; it can be amended during execution, but amendments are explicit.

## 7. Workflow pipeline

The pipeline for new work in this module:
1. formation-recipe (intent, in `recipe.md`)
2. plan-as-seed (3-7 steps, in PB)
3. build (PHP code, in `src/`)
4. test (PHPUnit, in `tests/`)
5. finalize (update `module-meta.json.changelog`)
6. archive (mark `lifecycle_phase: archived` in `recipes.json`)

## 8. User removal

If the operator decides this module is no longer needed:
1. Remove from `oscar-platform/bundles/freshcloud-mail/bundle-manifest.json`
2. Remove from `oscar-platform/composer.json` autoload
3. Remove the `modules/mail-app-pocketbase/` directory
4. Update `oscar-platform/bundles/freshcloud-mail/bundle-features.md` to drop the affected features
5. Commit + push + verify no broken imports

## 9. Coverage matrix

Every public method in this module has at least 1 PHPUnit test. Coverage is reported in `oscar-platform/coverage/mail-app-pocketbase/` after each test run. Below 80% coverage is a smell — investigate.

---

## See also

- `recipe.md` — formation-recipe
- `codex.md` — surfaces, behaviours, contracts
- `../module.json`, `../module-meta.json`, `../composer.json`
- FvW v8 §11.9 — the 9 things