# 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