# RULEFOLDER — how this project is governed

Everything a developer or an AI agent needs to work on this project like a member of one team:
what exists, why it is built the way it is, what the rules are, and how every change is recorded.

Ported from the sibling `YoutubeManager` project (same tools, same workflow) and adapted to this
codebase. The application itself was born under these rules: the initial application and this
governance port are the first two change fragments in `changes/`.

## Read in this order

| # | File | What it gives you | When |
|---|------|-------------------|------|
| 1 | `README.md` (this) | The map | First day |
| 2 | `ARCHITECTURE.md` | System overview, modules, data flows, pattern catalog, layering | First day |
| 3 | `FEATURE-REGISTRY.md` | Every feature → GUI route, API endpoint, service, doc section, status | Before touching any feature |
| 4 | `CODING-CONVENTIONS.md` | How code is written | Before writing code |
| 5 | `SECURITY.md` | What code must never do, and the open findings | Before writing code |
| 6 | `API-PARITY.md` | The GUI↔API rule and how it is checked | When adding/changing a feature |
| 7 | `CONTRIBUTING.md` | The step-by-step workflow, definition of done, review, release | Every change |
| 8 | `CHANGELOG.md` | Generated history of all changes (read `changes/` for the source) | To learn what happened |
| 9 | `decisions/ADR-*.md` | Why the big decisions were made | When you want to change one |
| 10 | `TEAM.md` | Developer codes used in change IDs | Once |

## The pieces and how they fit

```
changes/CHG-*.md  ──build_changelog.py──▶  CHANGELOG.md   (generated, committed, never hand-edited)
       │
       └── front matter: type, scope, files, gui_routes, api_endpoints, security_impact, tests
                                      │
FEATURE-REGISTRY.md ◀── updated in the same commit as any route change
       │
       └── check_rules.py --parity   compares registry ↔ app/routes/*.py ↔ DOC/API.md
       
.githooks/pre-commit  ──▶  check_rules.py --staged   (code staged ⇒ fragment staged; fragments valid; changelog fresh)
.githooks/commit-msg  ──▶  first line must be  CHG-YYYYMMDD-DEV-NN: title
```

## Commands

```bash
# once per clone
git config core.hooksPath .githooks

# start a change (creates changes/CHG-YYYYMMDD-DEV-NN-<slug>.md from the template)
python RULEFOLDER/tools/new_change.py "Short title" --type feature --scope api web-ui

# after editing fragments
python RULEFOLDER/tools/build_changelog.py

# before committing (the hook runs it too)
python RULEFOLDER/tools/check_rules.py

# flat export for a manager who wants a spreadsheet
python RULEFOLDER/tools/build_changelog.py --csv changes.csv
```

## Non-negotiables (the short list)

1. No code change without a change fragment in the same commit.
2. No business logic in routes; GUI and API call the same service function.
3. Every GUI capability has an API twin, registered and documented, or a reasoned exception.
4. Every change answers the security checklist; findings in `SECURITY.md` §4 are closed by
   `security` changes, not silently.
5. Design patterns are named only where deliberately applied and explained in `## How`.
6. Tests accompany every service function and every API endpoint.
7. `CHANGELOG.md` is generated; `FEATURE-REGISTRY.md` and `DOC/API.md` are kept in sync by hand
   and verified by script.
8. The database engine is chosen in `.env` (`DB_ENGINE=sqlite` or `postgres`, PostgreSQL 17+ as a
   container in the same compose file), never in code; every schema change is a migration that
   runs on both engines (ADR-004).