chore: initialize project foundation

[Fluory]

Warum

Fixes #1

Arbeitsstand

• Ziel: Projektfundament nach fluory-system 2.1 für ein P1-Projekt mit den freigegebenen Add-ons – bevor der erste Produktcode entsteht.
• Nicht-Ziele: Produktcode, Dependencies, Cloud-Ressourcen (Neon, R2, Vertex, Vercel).
• Erledigt: Karten, Profil, Wächter-Hooks, Rules, Kern-Skills, Doku- und PR-Wächter, CI, Templates, aufgefächerte Doku inkl. ADR-0001; Labels; Issues epic: vertical slice – one request end to end #2–epic: public showcase #19.
• Offen: Merge durch den Orchestrator; GitHub-Project-Board (Token ohne project-Scope). Erledigt: frischer Review (8 Befunde, alle aufgelöst, chore: initialize project foundation #20 (comment)), Branch Protection inkl. enforce_admins.
• Annahmen: Referenzprojekt mit ausschließlich synthetischen Daten → öffentliches Repo ist zulässig (PROJECT-START §3).
• Nächster kleinster Schritt: Merge durch den Orchestrator; Issue chore(app): TS app skeleton, docker compose and verify commands #3 (App-Gerüst) läuft bereits gestapelt auf diesem Branch.

Was ist passiert (Klartext)

RequestFlow bekommt sein Fundament, bevor die erste Zeile Produktcode entsteht. Im Repo liegen jetzt die Spielregeln, und sie werden technisch erzwungen: Ein Push direkt auf main wird blockiert, Secrets sind für Agents nicht lesbar, und jede PR-Beschreibung sowie der Doku-Stand werden automatisch geprüft. Außerdem liegt hier alles, was in der Discovery entschieden wurde: die Kundenanfrage, der Vorschlag an den Kunden, der Projektsteckbrief, die Meilensteine und die Architekturentscheidung ADR-0001 mit allen elf Einzelentscheidungen. Der erste Arbeitsschritt ist als Issue #3 vorbereitet. Beim Einrichten sind Lücken in den Vorlagen aufgefallen: Die CI-Vorlage nutzt veraltete Action-Versionen, und eine Action ließ sich nicht auflösen, was die CI anfangs rot machte. Die Befunde stehen gesammelt in Fluory/Entwicklungsplan#27. Eine eigene Fehlannahme wurde dabei korrigiert: Windows-Zeilenenden brechen die Hooks unter Git Bash nicht (getestet). Die LF-Normalisierung ist nur eine Vorsorge für Linux-Shells.

Plan-Pflicht (SYSTEM.md §4)

• Kein Auslöser – keine Modulgrenze, öffentliche API, Migration, Auth/Rechte, kein Zahlungs-/Daten-/Infrapfad, höchstens zwei Module, keine Architekturvarianten, umkehrbar
• Auslöser zutreffend – Impact Manifest ausgefüllt (Plan vor Code)

Impact Manifest

• Betroffene Module: noch keine gebauten Module; die Modulkarte ist in docs/technical/architecture.md festgelegt (13 TS-Module + AI-Service + Contracts, alle Status planned).
• Schnittstellen / Datenänderungen: keine im Code. Festgelegt sind die künftigen Verträge contracts/ai-service.openapi.yaml und contracts/erp-export.openapi.yaml (ADR-0001 D8, D9).
• Akzeptanzkriterien: die Kriterien aus Issue chore: initialize project foundation #1 – Karten + Profil, .claude/ komplett, Wächter-Skripte grün, CI mit Fundament-Phase, aufgefächerte Doku, Branch Protection.
• Testplan: bash scripts/doku-check.sh lokal und in der CI; scripts/pr-check.sh in der CI; Smoke-Test der Hooks (Push auf main → exit 2, .env lesen → exit 2, Session-Karte rendert).
• Verifizierte Fakten: alle Anbieter- und Bibliotheksaussagen in ADR-0001 wurden am 2026-09-22 gegen offizielle Quellen geprüft (Quellenliste im ADR); die Action-Majors wurden per GitHub-API geprüft (checkout v7, setup-node v7, pnpm/action-setup v6, setup-uv v10).
• Offene Annahmen: die Punkte unter „Open points → To verify during implementation“ in ADR-0001 (pg-boss-Wartung serverless, docling EML/MSG, Vertex-eu-SDK-Konfiguration, R2 EU auf Free, Showcase-Host des AI-Service).
• Nicht-Ziele: Produktcode, Dependencies, Cloud-Ressourcen.
• Risiken und Rollback: Das Risiko ist gering, weil es nur Doku und Konfiguration betrifft. Rollback: Revert-PR. Hooks, die sich falsch verhalten, werden per Issue im Kontrollzentrum gemeldet, nie deaktiviert.

Geändert

• AGENTS.md, CLAUDE.md, project-profile.yml, CHANGELOG.md, README.md: Projektkarte (89 Zeilen), Profil P1 mit Add-ons und Budget, öffentliches README
• .claude/: Settings mit Read-Sperren, 7 Hooks (LF, ausführbar), 7 Rules mit an src/features/, services/ai/ und contracts/ angepassten paths:, 4 Kern-Skills
• scripts/: doku-check.sh, pr-check.sh, quiet-run.sh (unverändert, LF, ausführbar)
• .github/: CI (pnpm, Node 24, pfadgezielter uv-Job, aktuelle Action-Majors; setup-uv auf v10.2.0 gepinnt, weil der Tag v10 nicht existiert), PR- und Issue-Vorlagen
• docs/: input/ (Kundenanfrage), product/ (Brief, Roadmap, Pilot-Vorschlag), technical/architecture.md (Karte + Ausnahmen-Register), decisions/ (ADR-0001 + Index)
• PROJECT-START.md: Discovery, Freigabe vom 2026-09-22, echte Issue-Nummern
• .gitattributes: LF-Normalisierung (bereits im Initial-Commit)

Nachweis (SYSTEM.md §11)

• verify:changed: nicht anwendbar – Fundament-Phase ohne Produktcode
• verify: grün – Fundament-Phase: bash scripts/doku-check.sh → „Docs guard: green (0 WARN)“; pr-check.sh lokal grün
• verify:full / E2E-Spec: nicht betroffen
• Manueller Prüfnachweis: Hooks per Smoke-Test → guard-git.sh mit git push origin main → exit 2 (blockiert); guard-read.sh mit .env → exit 2; session-start.sh rendert die Karte mit Profil P1/2.1
• Frischer Review (P1 vor Ready-for-review; Architektur/API/DB immer): chore: initialize project foundation #20 (comment) – REQUEST CHANGES ohne Blocker, alle 8 Befunde in Commit 3ff2717 aufgelöst
• CI: check grün (Run 35779566855 vor den Review-Fixes; der Lauf zum aktuellen Commit ist an diesem PR sichtbar)
• Branch Protection: {"checks":["check"],"strict":true,"pr_required":true,"enforce_admins":true,"force_push":false,"deletions":false}

Doku-Entscheidung (genau eine)

• Keine langlebige Doku betroffen – Begründung: –
• Doku betroffen und im selben PR aktualisiert:
  • Produktdoku (P0: README): README.md, docs/product/
  • Technische Doku: docs/technical/architecture.md
  • Architekturkarte: docs/technical/architecture.md
  • ADR: docs/decisions/ADR-0001-pilot-architecture.md
  • CHANGELOG [Unreleased] (sichtbares Feature oder Verhalten – im selben PR, nie „später")

Entferntes oder Umbenanntes: docs/ + README gegrept, Treffer bereinigt: ja – KUNDENANFRAGE.md → docs/input/2026-09-22-kundenanfrage.md, alle Verweise angepasst

Dateigrößen und neue Bausteine (SYSTEM.md §7)

Dateien über 500 Zeilen im Diff (Ausnahmen: generierter Code, Lockfiles, Fixtures, Migrationen, Schemas, Ressourcen, Doku, Konfiguration):

• keine
• bewusst belassen – Begründung: –
• im selben PR nach fachlicher Verantwortung geteilt
• Folge-Issue –

Über 800 Zeilen mit neuer Fachlogik oder über 1000 Zeilen (P1/P2): nicht betroffen

Neue Shared-Komponente, Utility-Datei, Adapter oder fachlicher Service:

• nein
• ja – gesucht nach: –

Subagent-Einsätze

• 2× general-purpose (Recherche, read-only): Faktencheck für ADR-0001 zu Infra (pg-boss, Vercel-Limits, Neon, MinIO-Status, R2, Vercel Blob, Hetzner) und zu Auth/KI/Parsing (Better Auth inkl. Advisories, Clerk/WorkOS-Residenz, Gemini-Nutzungsbedingungen, Vertex-EU-Modelle, AI SDK v7, Parser-Bibliotheken, docling). Die Ergebnisse stehen mit Quellen im ADR.

Risiken / offene Punkte

• Lizenz fehlt (Entscheidung Orchestrator): Ein öffentliches Repo ohne LICENSE bedeutet „alle Rechte vorbehalten“. Das ist bewusst offen gelassen.
• GitHub-Project-Board fehlt: Der gh-Token hat keinen project-Scope → einmal gh auth refresh -s project ausführen, danach wird das Board angelegt.
• Befunde für das Kontrollzentrum: Die sieben Punkte stehen gesammelt in Fluory/Entwicklungsplan#27, darunter veraltete Action-Majors, ein fehlender schwebender Tag bei setup-uv und die Reihenfolge Initial-Commit ↔ Push-Wächter. Der Eintrag in PROJEKTE.md kommt als separater PR im Entwicklungsplan.
• Korrektur einer eigenen Aussage: Der erste Commit begründet die LF-Umstellung mit „bash bricht bei CRLF ab“. Das stimmt für Git Bash nicht (getestet: der CRLF-Hook blockiert korrekt). Für Linux-Shells ist es ungetestet, weil Docker lokal nicht lief. Die Commit-Historie bleibt unverändert (kein Force-Push); AGENTS.md und .gitattributes sind korrigiert.
• Cross-Account-Review: Laut Framework bevorzugt über den Zweit-Account.

---

🤖 Generated with Claude Code

[Fluory]

Frischer Review (Reviewer-Rolle, unabhängige Session) – 2026-09-22

Urteil: REQUEST CHANGES – kein Blocker. Alle sechs Akzeptanzkriterien von #1 sind erfüllt und selbst nachgeprüft: Dateien byte-identisch zu den Vorlagen 2.1, LF, Modus 100755; Wächter-Skripte grün; Hook-Smoke-Test; CI-Lauf grün; Branch Protection; Labels; keine Secrets; Stack, Stufe, Add-ons, Budget und 13,25 Tage konsistent.

#	Befund	Schwere	Auflösung (Commit 3ff2717)
1	on: pull_request ohne types: → PR-Wächter läuft nicht bei „Ready for review“ / Beschreibungs-Edit	should-fix	types: [opened, synchronize, reopened, ready_for_review, edited]; Vorlagen-Befund ergänzt in Fluory/Entwicklungsplan#27
2	Widerspruch zwischen den verify-Stufen (Integrationstests, Eval-Gate) in AGENTS.md, ADR und Vorschlag	should-fix	Integrationstests gegen Postgres + S3 laufen in verify (RLS- und Idempotenz-Beweise blockieren jeden PR); das Eval-Gate läuft pfadgezielt bei services/ai/; verify:full = Playwright-Smoke + voller Eval-Lauf
3	enforce_admins: false → der arbeitende Account kann an PR und CI vorbei	should-fix	enforce_admins: true (Nachweis unten)
4	Security-Rule deckt Upload und Dokument-Parsing nicht ab	should-fix	src/features/intake/** und services/ai/src/**/parsing/** ergänzt
5	Platzhalter und toter Verweis in PROJECT-START; Preisfeld im Vorschlag	should-fix	PROJECT-START: Skizze → ADR-Overview, Entscheidungsbedarf → „keiner offen“, Verweis → Vorschlag §9. Preisfeld bleibt bewusst: kaufmännische Entscheidung des Orchestrators
6	recht: false trotz geplantem öffentlichen Showcase	nit	Kommentar: wird mit dem Showcase aktiviert
7	.gitattributes würde .eml-Fixtures auf LF umschreiben → andere SHA-256-Fingerprints	nit	*.eml -text
8	ADR verweist auf nicht existierende ARCHITEKTUR.md; eine Quelle fehlt	nit	Verweise → docs/technical/architecture.md (Exceptions register); Better-Auth-Quellen ergänzt

Für den Orchestrator zu bestätigen: Der einzige echte Personenname im öffentlichen Repo ist der Vorname des Autors (Signatur im Vorschlag, Anrede in der Kundenanfrage). Außerdem fehlt noch das GitHub-Project-Board, weil dem Token der project-Scope fehlt.

Branch Protection nach dem Fix (gh api repos/Fluory/RequestFlow/branches/main/protection):
{"checks":["check"],"strict":true,"pr_required":true,"enforce_admins":true,"force_push":false,"deletions":false}