Merge branch 'develop' into feature/issue-60-adr-user-approval

Author: martinyde

.env

@@ -34,3 +34,7 @@ BRAND_NAME="AI Bibliotek"
 BRAND_TAGLINE="del & hjemtag assistenter"
 BRAND_INITIALS="AI"
 ###< brand identity ###
+
+###> doctrine/doctrine-bundle ###
+DATABASE_URL="mysql://db:db@mariadb:3306/db?serverVersion=10.11.16-MariaDB&charset=utf8mb4"
+###< doctrine/doctrine-bundle ###

.env.test

@@ -1,3 +1,5 @@
 # define your env variables for the test env here
 KERNEL_CLASS='App\Kernel'
 APP_SECRET='$ecretf0rt3st'
+
+DATABASE_URL="mysql://root:password@mariadb:3306/db_test?serverVersion=10.11.16-MariaDB&charset=utf8mb4"

.github/ISSUE_TEMPLATE/issue.md

@@ -0,0 +1,36 @@
+---
+name: Issue
+about: General issue template with a human summary and a detailed AI brief.
+title: ""
+labels: []
+assignees: []
+---
+# Resume
+
+## Description
+
+<!-- 1–3 sentences: what this issue is about and why it matters. -->
+
+## Tasks
+
+<!-- Concise checklist. One unit of work or acceptance criterion per item. -->
+
+- [ ]
+- [ ]
+- [ ]
+
+---
+
+# Details - AI specificities
+
+<!--
+Include anything that helps the agent act correctly:
+
+- Goal and motivation (the "why").
+- Scope and explicit non-goals.
+- Relevant files, services, routes, or domain terms (link or path them).
+- Constraints: coding standards, ADRs, security/compliance requirements.
+- Inputs/outputs, data shapes, edge cases.
+- Acceptance criteria and how to verify (commands, URLs, fixtures).
+- Links to related issues, PRs, ADRs, or external docs.
+-->

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,42 @@
+#### Links to issues
+
+Please add links to github issues that this PR addresses.
+
+#### Description
+
+Please include a short description of the suggested change and the reasoning behind the approach you have chosen.
+
+#### Screenshot of the result
+
+If your change affects the user interface you should include a screenshot of the result with the pull request.
+
+#### Checklist
+
+- [ ] My code is covered by test cases.
+- [ ] My code passes our test (all our tests).
+- [ ] My code passes our static analysis suite.
+- [ ] My code passes our continuous integration process.
+
+If your code does not pass all the requirements on the checklist you have to add a comment explaining why this change
+should be exempt from the list.
+
+#### Additional comments or questions
+
+If you have any further comments or questions for the reviewer please add them here.
+
+---
+
+# Details - AI specificities
+
+<!--
+Detailed brief for AI assistants reviewing or following up on this PR.
+Include anything that isn't obvious from the diff:
+
+- Goal and motivation (the "why").
+- Scope and explicit non-goals.
+- Architectural decisions, ADRs referenced, or conventions applied.
+- Trade-offs considered and why this approach was chosen.
+- Areas needing extra scrutiny (security, performance, migrations).
+- Follow-up work intentionally left out of this PR.
+- Links to related issues, PRs, ADRs, or external docs.
+-->

.github/workflows/tests.yaml

@@ -22,8 +22,11 @@ jobs:
             - name: Build Tailwind CSS
               run: docker compose run --rm phpfpm bin/console tailwind:build
 
+            - name: Create the test database
+              run: docker compose run --rm phpfpm bin/console --env=test doctrine:database:create --if-not-exists --no-interaction
+
             - name: Run PHPUnit with coverage
-              run: docker compose run -e XDEBUG_MODE=coverage --rm phpfpm vendor/bin/phpunit --coverage-clover=coverage/clover.xml
+              run: docker compose run -e XDEBUG_MODE=coverage --rm phpfpm vendor/bin/phpunit --bootstrap=tests/bootstrap_integration.php --coverage-clover=coverage/clover.xml
 
             - name: Enforce coverage threshold (100%)
               run: docker compose run --rm phpfpm vendor/bin/coverage-check coverage/clover.xml 100

.php-cs-fixer.dist.php

@@ -13,8 +13,4 @@
 $config = new PhpCsFixer\Config();
 $config->setFinder($finder);
 
-$config->setRules([
-  '@Symfony' => true,
-]);
-
 return $config;

CHANGELOG.md

@@ -9,21 +9,48 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- Catalogue listing page with filters
+  ([#15](https://github.com/itk-dev/ai-lib/issues/15)).
+- Initial Symfony 8 application scaffold on the ITK Dev Docker
+  `symfony-8` template (phpfpm 8.4, nginx, MariaDB, Mailpit, Traefik),
+  including dev dependencies for coding standards (`php-cs-fixer`,
+  `twig-cs-fixer`) and composer normalization
+  ([#1](https://github.com/itk-dev/ai-lib/issues/1)).
+- Architecture Decision Records under `docs/adr/` with index and the
+  first ADR `001-tech-stack-docker-symfony`
+  ([#11](https://github.com/itk-dev/ai-lib/issues/11)).
 - `CLAUDE.md` with project-level operating instructions for AI agents
-  (stack, structure, execution policy, branching, commits, CHANGELOG,
-  ADRs, domain glossary).
-- Initial Symfony 8 application scaffold.
-- PHPUnit test harness with 100% coverage gate enforced in CI via
+  — stack, structure, execution policy, branching, commits, CHANGELOG,
+  ADR conventions, translations, brand env vars, Tailwind rebuild
+  notes, and the domain glossary
+  ([#5](https://github.com/itk-dev/ai-lib/issues/5)).
+- Human-facing `README.md` rewritten around the AI Bibliotek catalog
+  — project description, status banner, feature list, tech stack,
+  Task-based local development workflow, contributing pointers, and
+  prototype references
+  ([#28](https://github.com/itk-dev/ai-lib/issues/28)).
+- `CONTRIBUTING.md` documenting branching, Conventional Commits,
+  coding standards, changelog expectations, and the pull-request
+  workflow
+  ([#9](https://github.com/itk-dev/ai-lib/issues/9)).
+- Project license declared as **MPL-2.0** — full `LICENSE` text at
+  the repo root, `composer.json` `license` field updated from
+  `proprietary` to `MPL-2.0`, and ADR `004-project-license-mpl-2`
+  recording the rationale
+  ([#32](https://github.com/itk-dev/ai-lib/issues/32)).
+- `Taskfile.yml` exposing common developer commands via `task --list`
+  (compose helpers, composer, console, coding-standards family) with
+  README updates documenting `task` as a host requirement
+  ([#29](https://github.com/itk-dev/ai-lib/issues/29)).
+- Frontend tooling: Tailwind CSS via `symfonycasts/tailwind-bundle`,
+  Symfony AssetMapper, and Stimulus via `symfony/stimulus-bundle`,
+  with base Twig layout (`templates/base.html.twig`), asset
+  entrypoints (`assets/app.js`, `assets/styles/app.css`), Tailwind v4
+  design tokens (`@theme`), and ADR `002-frontend-tooling`
+  ([#38](https://github.com/itk-dev/ai-lib/issues/38)).
+- PHPUnit test harness with a 100 % coverage gate enforced in CI via
   `rregeer/phpunit-coverage-check`
   ([#31](https://github.com/itk-dev/ai-lib/issues/31)).
-- ADR 006 (Draft) — user registration, approval, and account-state
-  model: a `status` enum (`pending | approved | blocked`) on `User`,
-  an env-var allow-list of e-mail domains for self-signup, and a
-  `UserCheckerInterface` gating login
-  ([#60](https://github.com/itk-dev/ai-lib/issues/60)).
-
-### Changed
-
 - README refocused as human-facing project documentation: project purpose,
   tech stack, and local development bootstrap. Developer command reference
   moved to `CLAUDE.md` (and later `CONTRIBUTING.md`, tracked in #9).
@@ -34,13 +61,38 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Frontend tooling: Tailwind CSS (via `symfonycasts/tailwind-bundle`),
   Symfony AssetMapper, and Stimulus (via `symfony/stimulus-bundle`).
   Decision recorded in [ADR 002](docs/adr/002-frontend-tooling.md).
+  ([#14](https://github.com/itk-dev/ai-lib/issues/14), [#16](https://github.com/itk-dev/ai-lib/issues/16)).
 - Base Twig layout (`templates/base.html.twig`) and frontend asset
   entrypoints (`assets/app.js`, `assets/styles/app.css`).
 - Placeholder frontpage at `/` (`App\Controller\FrontpageController`)
-  that previews the AI Bibliotek design with hardcoded sample data:
-  hero, search prompt, sample-assistant rail, "Sådan virker det"
-  steps, and "Kommer snart" chips. Follows the prototype mock at
-  `itk-dev/research-projects/docs/public/projects/ai-bibliotek/mocks`.
+  previewing the AI Bibliotek design with hardcoded sample data
+  (hero, search box, sample-assistant rail, "Sådan virker det" steps),
+  site chrome (header with brand + nav, footer), the Stimulus
+  `nav_toggle_controller` driving the mobile menu, and a
+  `block-on-label` GitHub Action providing a per-PR merge gate
+  ([#40](https://github.com/itk-dev/ai-lib/issues/40)).
+- User authentication: `User` Doctrine entity (email, hashed password,
+  roles), `UserRepository` (with `PasswordUpgraderInterface`), the
+  `UserManager` service that hides persistence + hashing, form-login
+  firewall + `/login` + `/logout`, fixtures for two baseline users
+  (`alice@example.test`, `bob@example.test` — password `password`),
+  console commands `app:user:create` and `app:user:change-password`,
+  and end-to-end functional + unit tests
+  ([#2](https://github.com/itk-dev/ai-lib/issues/2)).
+- PHPUnit suite split into `unit` (no database) and `integration` (full
+  kernel) testsuites under `tests/Unit/` and `tests/Integration/`, with
+  transactional database isolation per integration test via
+  `dama/doctrine-test-bundle`. The integration suite uses a dedicated
+  `tests/bootstrap_integration.php` that builds the schema from ORM
+  metadata and loads baseline `UserFixtures` once before any test;
+  DAMA's per-test transaction rolls back mutations so the baseline
+  persists. The default `tests/bootstrap.php` is minimal and is used
+  by `task test-unit`. `task test-unit` and `task test-integration`
+  expose the suites individually.
+- Reusable Twig form components under `templates/components/Form/`:
+  `Form/Label`, `Form/Input`, and `Form/Button` (with `variant` and
+  `size` props for future styling variants). The `/login` template
+  consumes them instead of inlining the input/label/button markup.
 - Site chrome (header with brand + nav, footer) in
   `templates/base.html.twig`, with the Fraunces/Geist font stack
   preloaded from Google Fonts.
@@ -53,13 +105,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   per-PR merge gate for dependencies (e.g. another PR that must land
   first).
 - `LICENSE` file at repo root containing the full Mozilla Public License 2.0 text.
-- ADR `docs/adr/002-project-license-mpl-2.md` recording the MPL-2.0 license
-  decision and its rationale.
-- License section in `README.md` referencing the new `LICENSE` file and ADR.
 - Project license declared as **MPL-2.0** (Mozilla Public License 2.0); the
   `license` field in `composer.json` updated from the Symfony skeleton
   default `proprietary` to the SPDX identifier `MPL-2.0`.
-- Added develop branch
 - `Taskfile.yml` exposing common developer commands via `task --list`
   (compose helpers, composer, console, coding-standards family).
 - README documents [Task](https://taskfile.dev) as a host requirement and
@@ -68,6 +116,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   documenting the choice of Symfony 8 on the ITK Dev Docker `symfony-8` template.
 - `CONTRIBUTING.md` documenting branching, Conventional Commits, coding
   standards, changelog expectations and the pull-request workflow.
-- Rewrite the project README around the AI Bibliotek catalog: adds project
-  description, status banner, feature list, tech stack, Task-based local
-  development workflow, contributing pointers, and prototype references.
+- GitHub issue template `.github/ISSUE_TEMPLATE/issue.md` and pull-request
+  template `.github/PULL_REQUEST_TEMPLATE.md`, each with a human-facing
+  "Resume" / checklist section followed by an "AI specificities" detail
+  block so other agents can continue work from a structured brief
+  ([#69](https://github.com/itk-dev/ai-lib/issues/69)).

CLAUDE.md

@@ -105,19 +105,87 @@ These come from the `symfony-8` template — don't edit them without a reason.
 If a project-specific override is needed, override via the template's
 documented mechanism (e.g. `.php-cs-fixer.php` next to `.php-cs-fixer.dist.php`).
 
+### Tests are not modified without approval
+
+Do **not** edit, rename, delete, or skip files under `tests/` (or any other
+test files) without explicit user approval — even when a failure looks like
+a stale assertion. If a change you're making appears to require test
+updates, stop and describe to the user, briefly:
+
+- Which test files / test methods need to change.
+- What the change is (assertion update, fixture change, new case, removal).
+- Why it's needed (production behavior changed, contract widened, etc.).
+
+Wait for the user to approve before touching the files. The 100% coverage
+gate (see "Common commands") means test edits have real consequences;
+the user decides whether the production change or the test is wrong.
+
+## Coding practices
+
+Style conventions code in this project follows, on top of the linter
+rules in "Coding standards" above.
+
+### Defer to symfony.com/doc when implementing Symfony features
+
+When you add or change functionality that lives on top of a Symfony
+component — controllers, routing, security, forms, validation,
+Doctrine integration, console commands, messenger, mailer,
+translation, asset mapping, Twig extensions, etc. — open the
+relevant chapter on <https://symfony.com/doc> first and base the
+implementation on the approach the docs show. The docs name the
+component, demonstrate the idiom, and link the configuration
+references; following them keeps the code in step with the
+framework instead of drifting into bespoke shapes that look
+reasonable but miss built-in conventions.
+
+When the docs offer more than one path (e.g. PHP attributes vs.
+YAML config, MapEntity vs. ParamConverter), pick the one that
+matches what's already in this codebase. If nothing comparable
+exists yet, prefer the most recent idiom shown in the docs — the
+attribute-driven, autoconfigured, autowired style.
+
+Cite the relevant doc URL in the PR description for any change
+that introduces a Symfony-component idiom for the first time, so
+reviewers can compare the implementation against the source.
+
 ### Controllers stay thin
 
 Controllers handle routes and template/response rendering only — no business
 logic. Push logic into a service class. A controller action looks like:
 inject service → call service method → return `render()` / `Response` /
 `RedirectResponse`.
 
+**Do not add PHPDoc to controllers.** The class name, route attribute,
+action name, parameter types, and return type already describe what an
+action does; class- and method-level docblocks duplicate that. Push the
+explanatory prose into the (fully documented) service the controller
+delegates to. If a controller is so unusual that it needs a docblock to
+explain itself, that's the signal it's doing too much.
+
 ### Service classes are fully documented
 
 Every service class method (public, protected, private) carries a PHPDoc block
 with a one-line summary, a description of intent, `@param` per parameter,
 `@return`, and `@throws` for every exception that can be raised.
 
+### Test methods carry a one-line intent comment
+
+Each `public function test…` opens with a single-line comment that
+names what the test asserts, starting with `// Tests …`,
+`// Ensures …`, or `// Verifies …`. Pick whichever verb reads
+naturally for the assertion in question.
+
+- One line, terse — not a docblock, not a paragraph.
+- Placed immediately above the method declaration.
+- If a block-level docblock already exists on the method (e.g. to
+  explain *why* the test matters in context), keep it and put the
+  one-liner beneath it. The docblock serves the *why*; the one-liner
+  names the *what*.
+
+The comment is for a reader scanning the file's table of contents
+without reading method bodies. Matches the convention applied across
+every test file on the project.
+
 ## Workflows
 
 The `.github/workflows/*.yaml` files are mirrored from
@@ -138,6 +206,10 @@ open a PR upstream rather than patching locally.
   - Pass all required CI checks before merging.
   - Carry a `CHANGELOG.md` update under `## [Unreleased]` for any user-visible
     change.
+- If a PR carries the `do-not-merge` label, the PR description must spell
+  out **what blocks the merge and why** (e.g. waiting on upstream change,
+  dependent PR, unresolved decision). Keep this up to date — remove or
+  rewrite the block reason as blockers resolve.
 
 ## Commits
 
@@ -158,6 +230,18 @@ Keep subject lines under ~70 characters. Use the body for the *why*.
 Add an entry to `## [Unreleased]` under the right section (`Added`, `Changed`,
 `Fixed`, `Removed`, `Deprecated`, `Security`) for every meaningful change.
 
+**Pre-release rule:** while the project has no tagged releases yet,
+*everything* is `Added` — there is no prior released version for a
+change to be `Changed`, `Fixed`, `Removed`, `Deprecated`, or `Security`
+relative to. Keep those sections empty (or omit them) and fold the
+entry into `Added`, even when the work edits or replaces material that
+already exists in `[Unreleased]`. Before adding to any non-`Added`
+section, check `git tag` (or the GitHub releases page) and confirm at
+least one release exists; if none does, use `Added`. Once the first
+release is cut, the standard Keep a Changelog sections apply normally
+from the next `[Unreleased]` onward. See PR #57 for the prior
+consolidation that established this convention.
+
 ## GitHub issue types and labels
 
 Every issue **must** have its native **issue type** set to one of:
@@ -176,6 +260,13 @@ fall back to the REST API (`PATCH /repos/{owner}/{repo}/issues/{n}` with
 `type=<Name>`) when available, otherwise ask the user to set it in the
 UI. Labels can always be set with `gh issue create --label`.
 
+When creating an issue, use the repository's issue template at
+`.github/ISSUE_TEMPLATE/issue.md`. Preserve its structure — every heading
+and HTML comment marker stays in its original order — and fill each
+section from the available context. Pass it via `gh issue create
+--body-file` (or `--body` with the rendered content) rather than hand-
+rolling a description.
+
 ## Pushing
 
 SSH keys aren't available to the Claude session. Push one-off via HTTPS: