# Contributing to MeshVault

## Setup and checks

Use PHP 8.3+ and Composer 2. Run from the repository root:

```sh
composer install --no-interaction
composer validate --strict
composer lint
composer test
```

Commit `composer.lock` for reproducible development tooling. PHP_CodeSniffer is a
development dependency, not an application framework. Composer scripts use PHP and
local vendor binaries so they work in PowerShell as well as Unix shells.

`composer lint` enforces PSR-12 on PHP in `src`, `public`, `db/migrations` and
`tests`. `composer test` currently checks only repository foundations. Add behavior
and regression tests with each implementation; the HTTP/database test framework
will be selected with the application skeleton (#7), not assumed here.
Docker, database migrations, Node/Tailwind builds and CI are not implemented yet.
Do not use undocumented application commands or mistake foundation checks for
integration coverage.

## Conventions

- PHP: PSR-12, four spaces, LF, UTF-8 without BOM, final newline, no closing PHP tag
  in PHP-only files. Use strict types in new PHP source files.
- Use `MeshVault` as the future application namespace; PascalCase classes and file
  names, camelCase methods/variables, UPPER_SNAKE_CASE constants. PSR-4 wiring is M1.
- Database: plural snake_case tables, snake_case columns, `id` primary keys and
  singular `_id` foreign keys. Use UTC for stored application timestamps; distinguish
  `added_at` from file `mtime`. Parameterize SQL and version schema changes.
- Keep domain/services, persistence and HTTP rendering separate. Validate at
  boundaries, escape rendered values and protect state-changing requests against CSRF.
- Never infer file deletion from catalog removal. Restrict physical operations to
  configured managed roots; preserve source files, and test rollback/recovery paths.
- Do not introduce a framework, runtime dependency or storage behavior without
  documenting its choice in the relevant issue.

## Workflow

1. Choose an issue and check its dependencies; milestones group outcomes, not a
   strict schedule. In particular, repository service #28 precedes worker #25.
2. Use branches such as `feature/20-import-scan`, `fix/47-missing-file` or
   `docs/5-contributing`.
3. Keep changes focused and include tests and documentation. Test failure paths
   for filesystem operations as well as the successful path.
4. Use `type: concise imperative description` commits, such as
   `docs: document managed-storage semantics` or `test: cover hash mismatch`.
   Types include `feat`, `fix`, `docs`, `test`, `refactor`, `build` and `chore`.
   Existing history used emoji-prefixed messages; new commits need no emoji.
5. Include issue references, commands/results, limitations and migration/storage
   effects in the review description. Do not close implementation issues before
   their acceptance criteria are verified and the work is committed/reviewable.

Never commit credentials, dependencies, generated assets, library contents or
PostgreSQL data. `notes/` and `.superpowers/` are local-only planning storage.
Contributions are under AGPL-3.0-only, the project license.