Wiki/.claude/workflows/build-story.md

Workflow : BUILD STORY

Workflow pour livrer une story Phase 2 du plan Fast-App (cf _byan-output/fast-app/formation-hub/cdcf-stories.json et plan.json).

Equivalent BYAN-natif : Sprint Planning + FD (Feature Development) restreints a une story.

Trigger

• Story selectionnee depuis cdcf-stories.json (S-01 a S-10 + futures)
• Corentin invoque ce workflow avec : WF BUILD pour story S-XX

Acteurs

• Corentin (decisionnaire)
• bridge-dev (code metier)
• bridge-tester (tests + validation)
• acadenice-devops (deploy si push staging requis)
• (optionnel) docmost-fork-dev si la story implique frontend Docmost

Sequence

[1] Pre-flight (Corentin)
    - Lire la story (Connextra + Gherkin AC) dans cdcf-stories.json
    - Identifier les UC + entites concernees (cf doc 11 + doc 06/07)
    - Choisir branche : feat/<story-slug> depuis main
    - Output : story comprise + branche creee

[2] Code (bridge-dev)
    - Read brief + doc 19 + relevant Merise docs
    - Implement la story (adapters, domain, routes selon besoins)
    - Self-test local : npm test && npx biome ci . && npx tsc --noEmit
    - Commit progressif : type(scope): description
    - Output : code commit sur branche feat/

[3] Tests (bridge-tester)
    - Lit les Gherkin AC de la story
    - Ecrit unit tests Vitest (coverage >= 80% domain)
    - Ecrit integration tests testcontainers si adapter modifie
    - Run : npm run test:coverage
    - Si gap coverage > 10% sous cible : alerte bridge-dev
    - Output : tests verts + coverage report

[4] Gate user — Review (Corentin)
    - Verifier que le diff implemente bien la story
    - Tester manuellement si pertinent (curl bridge endpoint nouveau)
    - 3 decisions :
      * APPROVED : aller en [5]
      * NEEDS_REWORK : retour [2] avec feedback precis
      * BLOCKED : story retirage du sprint
    - Output : decision documentee dans PR description

[5] Push selfhost + GitHub (Corentin OU bridge-dev avec admin override)
    - git push selfhost feat/<branch>
    - Open PR sur Forgejo
    - Open same PR sur GitHub mirror si configure
    - Output : PR ouverte, CI auto-trigger

[6] CI verification (acadenice-devops via CI/CD)
    - Workflow ci.yml execute :
      * Lint Biome
      * Type-check tsc
      * Tests unit + integration
      * Security (TruffleHog + Semgrep + npm audit)
      * Docker build healthcheck
    - Si vert : continue [7]
    - Si rouge : retour [2] avec logs d'echec
    - Output : CI status

[7] Gate user — Merge (Corentin)
    - Verifier review ok (1+ approval) + CI vert
    - Squash merge vers main
    - Auto-delete branch
    - Output : commit sur main

[8] Deploy staging (acadenice-devops via deploy-staging.yml)
    - Phase 0/1 : workflow_dispatch only (pas auto)
    - Quand staging pret : auto sur push main
    - Smoke test post-deploy
    - Output : staging URL fonctionnelle

[9] Validation metier (Corentin + Yan + utilisateurs cibles)
    - Tester le flow utilisateur en staging
    - Si OK : passer a [10]
    - Si KO : retour [2] avec issue ou hotfix branch
    - Output : metier signe-off

[10] Mise a jour artefacts (bridge-dev OU Corentin)
    - Update build-state.json (story S-XX completed)
    - Update CHANGELOG.md (section Unreleased)
    - Output : artefacts a jour

Gates humains bloquants

Gate	Decision possible	Owner
Gate review (4)	APPROVED / NEEDS_REWORK / BLOCKED	Corentin
Gate merge (7)	APPROVED / WAIT_FIX_CI / BLOCKED	Corentin
Gate validation metier (9)	APPROVED / NEEDS_REWORK	Corentin + utilisateurs

Rollback

Echec	Action
Etape [2] code casse local :	bridge-dev fix, retry
Etape [3] tests echouent :	bridge-tester explique + bridge-dev fix
Etape [6] CI rouge :	acadenice-devops ou bridge-dev fix selon job (lint/test/security)
Etape [8] staging deploy fail :	acadenice-devops investigue (logs SSH + healthcheck)
Etape [9] metier rejette :	Corentin decide : fix mineur (loop [2]) ou re-PRUNE story

Outputs

• Branch feat/<story-slug> mergee sur main (squash)
• Tests + coverage reports
• CHANGELOG.md a jour
• build-state.json a jour (story marked completed)
• Si applicable : staging URL fonctionnelle

Exemple invocation (manuel)

Corentin : "Lance WF BUILD pour S-02 (Setup Baserow tables)"

Moi (Claude main) :
[1] Lis S-02 dans cdcf-stories.json. Verifies prereqs (compte admin Baserow OK).
[2] Invoque bridge-dev :
    "Implemente S-02 : table PERSONNE Baserow avec 16 fields + formulas
     heures_restantes selon doc 15 MPD. Branche feat/personne-table.
     Commit + push selfhost en branche feature."
[3] Invoque bridge-tester :
    "Ecris tests pour S-02. Verifie creation table + types fields + formulas.
     Coverage minimum 80% sur le code touche."
[4] Reporter a Corentin pour review.
... etc

Notes

• Pour Phase 2 entiere : ce workflow tourne par story (10+ stories au total dans cdcf-stories.json)
• Estimation : 1-3 jours par story selon complexite (cf expected_loops dans plan.json)
• Le user peut choisir d'enchainer plusieurs stories sans gates intermediaires si confiance haute