# DocWright — Development & Contribution Workflow

The discipline that keeps this project clean as work is handed over and received
between people **and** AI agents (Claude, Codex, …). Follow it scrupulously.

## 1. Golden rules

1. **`main` is always green and deployable.** Never commit directly to `main` for
   feature work — use a branch, open a PR, merge only when the checklist passes.
2. **Nothing untested ships.** Every change carries tests; CI must be green.
3. **The live deployment (`/opt/docwright`) is sacred.** You deploy to it *only*
   from a reviewed, merged `main`, via `make deploy`. Never hand-edit `/opt`.
4. **Isolation for experiments.** Feature work (human or agent) happens in a
   dedicated **git worktree/clone on its own branch**, against the **`docwright_test`
   database** and a throwaway data dir — never the live DB or data.
5. **Sovereign & FOSS.** No proprietary services; issues/bugs/tickets live in the
   repo (and the app's own tracker), not a third-party SaaS.

## 2. Branch & worktree model

```bash
# One worktree per concurrent workstream — they share history, isolate the tree.
git worktree add ../docwright-<topic> -b feature/<topic> main
# ...work, commit on the branch...
# review from the main checkout:
git -C /root/docwright log --oneline main..feature/<topic>
git -C /root/docwright diff main..feature/<topic>
# merge when the PR checklist passes:
git -C /root/docwright switch main && git -C /root/docwright merge --no-ff feature/<topic>
git worktree remove ../docwright-<topic>
```

Branch names: `feature/<topic>`, `fix/<topic>`, `docs/<topic>`, `chore/<topic>`.

## 3. Commit conventions (Conventional Commits)

```
<type>(<scope>): <imperative summary ≤72 chars>

<why + what, wrapped ~72 cols. Reference the driving ticket/issue.>

Refs: tickets/CODEX-01-office-interop.md   (or: Closes #123)
Co-Authored-By: <Agent/Author> <email>
```

- `type` ∈ `feat|fix|docs|test|refactor|perf|chore|build|ci`.
- **Atomic commits**: one logical change each; every commit **compiles, lints, and
  passes tests**. Never commit red. Never commit secrets, `vendor/`, `.env`, build
  output, or generated binaries (respect `.gitignore`; do commit lockfiles).
- Don't rewrite shared history (`main`), don't force-push, don't `git reset --hard`
  or `git clean -fdx` outside your own branch/worktree.

## 4. Testing tiers (all live in `tests/`)

| Tier | Tool | Runs |
|---|---|---|
| Fast smoke (offline, zero-dep) | `php tests/run.php` | always; no Composer needed |
| Full unit/integration/functional | `vendor/bin/phpunit` | dev + CI (needs `composer install`) |
| Python workers/realtime | `pytest tests/pytest` | dev + CI |
| Lint | `make lint` | pre-commit + CI |

DB-backed tests only run when `DOCWRIGHT_ALLOW_DB_TESTS=1` and are transaction-rolled
back; they target `docwright_test`, never live. See `tests/phpunit/Support/*`.

## 5. Definition of Done (every change)

Code complete (no stubs on shipped paths) · wired into UI/API/RBAC as applicable ·
tests added and green (`php tests/run.php` **and** `vendor/bin/phpunit`) · lint clean
· `bin/console doctor` passes · docs updated · `CHANGELOG.md` entry added ·
`CHECKLIST.md` updated honestly · PR checklist (`.github/PULL_REQUEST_TEMPLATE.md`)
satisfied.

## 6. Issue register & bug tracker

Two complementary trackers, both sovereign:
- **In-app** (end-user feedback/feature suggestions): the built-in tracker at
  `/app/suggestions` (Postgres-backed, RBAC-triaged).
- **In-repo** (engineering issues/bugs): GitHub Issues using the templates in
  `.github/ISSUE_TEMPLATE/`. Until a GitHub remote exists, log engineering issues
  as markdown files under `tickets/issues/` using the same fields.

Every bug gets a reproducer + a regression test before it's closed.

## 7. Work orders for AI agents (tickets)

Agent work is driven by a **ticket** under `tickets/` (see `tickets/README.md` and
`tickets/TEMPLATE.md`). A ticket is a self-contained work order with: scope, hard
constraints (files off-limits), a full verification protocol with real commands, an
architecture audit, and a Definition of Done. Agents run in an **isolated worktree
against `docwright_test`**, commit on a feature branch with the conventions above,
and hand back a report with **real, pasted** command output. The reviewer re-runs
the acceptance suite before merging.

## 8. Resources

This host has no CPU/RAM cap for development — **use it**: run the full test matrix
(don't skip slow LibreOffice/pandoc conversions), test with large fixtures, run
parallel lint (`xargs -P`), and run independent tickets in parallel worktrees.
Thoroughness is cheaper than a regression in production.