devflow-cli 2.2.0__tar.gz → 2.3.0__tar.gz

{devflow_cli-2.2.0 → devflow_cli-2.3.0}/.gitignore

@@ -11,3 +11,4 @@ venv/
 *.swp
 .DS_Store
 .coverage
+.devflow/

devflow_cli-2.3.0/.specify/specs/021-review-iterations/checklists/requirements.md

@@ -0,0 +1,35 @@
+# Specification Quality Checklist: Review Iterations Tracking
+
+**Purpose**: Validate specification completeness and quality before proceeding to planning
+**Created**: 2026-03-21
+**Feature**: [spec.md](../spec.md)
+
+## Content Quality
+
+- [x] No implementation details (languages, frameworks, APIs)
+- [x] Focused on user value and business needs
+- [x] Written for non-technical stakeholders
+- [x] All mandatory sections completed
+
+## Requirement Completeness
+
+- [x] No [NEEDS CLARIFICATION] markers remain
+- [x] Requirements are testable and unambiguous
+- [x] Success criteria are measurable
+- [x] Success criteria are technology-agnostic (no implementation details)
+- [x] All acceptance scenarios are defined
+- [x] Edge cases are identified
+- [x] Scope is clearly bounded
+- [x] Dependencies and assumptions identified
+
+## Feature Readiness
+
+- [x] All functional requirements have clear acceptance criteria
+- [x] User scenarios cover primary flows
+- [x] Feature meets measurable outcomes defined in Success Criteria
+- [x] No implementation details leak into specification
+
+## Notes
+
+- Spec references specific code locations (state.py, __init__.py) in "Comportement existant" section — this is acceptable for brownfield specs documenting current behavior, not implementation prescription.
+- No [NEEDS CLARIFICATION] markers — the feature scope is narrow and well-defined.

devflow_cli-2.3.0/.specify/specs/021-review-iterations/plan.md

@@ -0,0 +1,112 @@
+# Implementation Plan: Review Iterations Tracking
+
+**Branch**: `021-review-iterations` | **Date**: 2026-03-21 | **Spec**: [spec.md](./spec.md)
+**Input**: Feature specification from `/specs/021-review-iterations/spec.md`
+
+## Summary
+
+Activer le champ `reviewIterations` dans `FeatureState` en incrementant automatiquement le compteur dans `advance_step()` lorsque l'etape completee est une gate de review. Ajout d'une constante `REVIEW_GATES` pour centraliser l'identification des gates.
+
+## Technical Context
+
+**Language/Version**: Python 3.11+
+**Primary Dependencies**: typer (>=0.12), rich (>=13) — aucune nouvelle dependance
+**Storage**: Fichiers locaux (state.json)
+**Testing**: pytest (>=8) avec fixtures temporaires
+**Target Platform**: CLI multi-OS (macOS, Linux, Windows)
+**Project Type**: CLI
+**Performance Goals**: N/A — modification d'un compteur en memoire
+**Constraints**: Retrocompatibilite totale avec les state.json existants
+**Scale/Scope**: 3 fichiers modifies, ~15 lignes de code, ~30 lignes de tests
+
+## Constitution Check
+
+*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*
+
+| Principe | Verdict | Justification |
+|----------|---------|---------------|
+| I. Spec-Driven Development | PASS | Spec redigee et validee avant tout code |
+| II. Pipeline Sequentiel | PASS | Le champ `reviewIterations` est deja dans le pipeline — on corrige son non-fonctionnement |
+| III. Gates de Review | PASS | Cette feature IMPLEMENTE le tracking exige par ce principe ("Le nombre d'iterations de review DOIT etre trace dans reviewIterations") |
+| IV. Retrocompatibilite | PASS | Les state.json existants avec `reviewIterations: {}` ou absent restent valides (FR-005) |
+| V. Simplicite (YAGNI) | PASS | Modification minimale : 1 constante + 2 lignes dans `advance_step()`. Pas d'abstraction nouvelle |
+| VI. Testabilite | PASS | Tests unitaires ajoutes pour chaque FR |
+| VII. Integration Linear | PASS | Aucun impact sur le mapping Linear |
+
+## Project Structure
+
+### Documentation (this feature)
+
+```text
+specs/021-review-iterations/
+├── spec.md
+├── plan.md              # This file
+├── research.md          # Phase 0 output
+├── checklists/
+│   └── requirements.md
+└── tasks.md             # Phase 2 output (via /speckit.tasks)
+```
+
+### Source Code (repository root)
+
+```text
+src/devflow_cli/
+├── __init__.py          # + REVIEW_GATES constant (FR-002)
+└── core/
+    └── state.py         # advance_step() modification (FR-001, FR-003)
+
+tests/
+└── test_state.py        # + tests incrementation review iterations
+```
+
+**Structure Decision**: Modification in-place de fichiers existants. Aucun nouveau fichier source. Structure identique au projet actuel.
+
+## Complexity Tracking
+
+Aucune violation de constitution. Pas de complexite ajoutee a justifier.
+
+## Design
+
+### Approche
+
+L'incrementation se fait dans `advance_step()` (state.py), juste apres l'enregistrement du timestamp (ligne 206), car c'est le point unique ou une etape est marquee comme completee. C'est coherent avec le pattern existant : `advance_step()` gere deja `completedSteps` et `stepTimestamps`.
+
+### Constante REVIEW_GATES
+
+```python
+# Dans __init__.py, apres OPTIONAL_STEPS
+REVIEW_GATES = {"review-spec", "review-tasks", "review-impl"}
+```
+
+Type `set` (comme `OPTIONAL_STEPS`) car l'ordre n'importe pas — on teste uniquement l'appartenance.
+
+### Modification advance_step()
+
+Apres la ligne 206 (mise a jour du timestamp), ajouter :
+
+```python
+# Incrementer reviewIterations pour les gates de review
+if completed_step in REVIEW_GATES:
+    state.reviewIterations[completed_step] = state.reviewIterations.get(completed_step, 0) + 1
+```
+
+Utilisation de `.get(key, 0)` pour gerer :
+- Premier passage : cle absente → 0 + 1 = 1
+- Passages suivants (apres rollback) : valeur existante + 1
+- State.json legacy avec `reviewIterations: {}` : fonctionne identiquement
+
+### Ce qui ne change PAS
+
+- `rollback_step()` : ne touche pas `reviewIterations` (compteur cumulatif = historique)
+- `create_state()` : `reviewIterations` reste `{}` par default (premier passage l'initialisera)
+- `convert_speckit_state()` : continue d'injecter `{gate: 0}` pour les gates auto-validees
+- `_validate_state()` : pas de nettoyage de `reviewIterations` (les cles inconnues sont inoffensives)
+- Commandes Claude Code (`review-*.md`) : l'instruction "Incrementer reviewIterations" reste — le LLM ecrit dans state.json, puis `advance_step()` incremente aussi. Double source = pas de probleme car le LLM appelle `advance_step()` via la CLI pour avancer, et c'est la que l'incrementation fiable se fait.
+
+### Tests prevus
+
+1. **test_advance_step_increments_review_iterations** : Avancer `review-spec` → `reviewIterations["review-spec"]` == 1
+2. **test_advance_step_no_increment_for_non_review** : Avancer `spec` → `reviewIterations` inchange
+3. **test_advance_step_cumulative_review_iterations** : Avancer review-spec, rollback, re-avancer → compteur == 2
+4. **test_advance_step_increments_each_gate_independently** : Avancer review-spec puis review-tasks → chaque gate a son propre compteur
+5. **test_review_gates_constant** : `REVIEW_GATES` est sous-ensemble de `STEPS` et contient exactement 3 elements

devflow_cli-2.3.0/.specify/specs/021-review-iterations/research.md

@@ -0,0 +1,42 @@
+# Research: Review Iterations Tracking
+
+**Branch**: `021-review-iterations` | **Date**: 2026-03-21
+
+## Point d'insertion dans advance_step()
+
+**Decision**: Incrementer `reviewIterations` juste apres la mise a jour de `stepTimestamps` (ligne 206), avant le calcul de la prochaine etape.
+
+**Rationale**: Le pattern existant dans `advance_step()` est sequentiel :
+1. Verifier la legalite de la transition (lignes 171-195)
+2. Ajouter a `completedSteps` (ligne 198-199)
+3. Enregistrer `stepTimestamps` (lignes 202-206)
+4. **→ Nouveau : incrementer `reviewIterations`**
+5. Calculer la prochaine etape (lignes 208-220)
+
+Inserer entre 3 et 5 preserve la logique : d'abord enregistrer l'historique (timestamps + iterations), puis avancer.
+
+**Alternatives considered**:
+- `validate_and_advance()` : trop haut niveau, creerait un couplage validation ↔ compteur
+- Fonction separee `record_review_iteration()` : sur-ingenierie pour 2 lignes de code
+- Dans `write_state()` : wrong layer — `write_state()` est I/O, pas logique metier
+
+## Type de la constante REVIEW_GATES
+
+**Decision**: `set[str]` (frozenset rejete).
+
+**Rationale**: `OPTIONAL_STEPS` est deja un `set` dans `__init__.py`. Utiliser le meme type pour la coherence. `frozenset` serait plus "correct" (immutable) mais `OPTIONAL_STEPS` n'est pas frozenset, donc on suit le pattern existant (Constitution V : "Les patterns existants DOIVENT etre suivis").
+
+**Alternatives considered**:
+- `frozenset` : plus safe mais inconsistant avec `OPTIONAL_STEPS`
+- `list` : O(n) lookup vs O(1) pour set — inutilement lent
+- `tuple` : meme probleme que list
+
+## Double incrementation (CLI + LLM)
+
+**Decision**: Pas de probleme. Les commandes Claude Code (`review-*.md`) disent au LLM d'incrementer `reviewIterations` via ecriture directe dans state.json. Mais ensuite, le LLM appelle `advance_step()` (via la commande devflow) pour avancer l'etape, et c'est la que l'incrementation fiable se fait.
+
+**Rationale**: Deux scenarios :
+1. Le LLM incremente PUIS advance_step incremente → double comptage ? Non : le LLM ecrit dans state.json, mais advance_step travaille sur l'objet FeatureState en memoire (charge avant l'incrementation LLM), donc l'incrementation CLI ecrase celle du LLM via write_state. Resultat net = 1 incrementation.
+2. Le LLM n'incremente PAS (oubli, bug) → advance_step incremente quand meme. Le compteur reste fiable.
+
+Conclusion : l'incrementation dans `advance_step()` est la source de verite. L'instruction dans les commandes Claude Code est redondante mais inoffensive.

devflow_cli-2.3.0/.specify/specs/021-review-iterations/spec.md

@@ -0,0 +1,143 @@
+# Feature Specification: Review Iterations Tracking
+
+**Feature Branch**: `021-review-iterations`
+**Created**: 2026-03-21
+**Status**: Draft
+**Project Type**: Brownfield
+**Input**: reviewIterations : code mort — Le champ existe dans FeatureState, il est initialise a {}, mais jamais incremente nulle part.
+
+## Comportement existant *(mandatory for brownfield)*
+
+### Etat actuel
+
+Le champ `reviewIterations` est declare dans le dataclass `FeatureState` (`state.py:19`) avec un type `dict[str, int]` et un default `{}`. Il est :
+
+1. **Cree vide** par `create_state()` (implicitement via le default du dataclass)
+2. **Peuple avec des `0`** uniquement par `convert_speckit_state()` pour les gates auto-validees lors de la migration speckit (lignes 304-317)
+3. **Serialise/deserialise** correctement via `to_dict()` et `read_state()`
+4. **Jamais incremente** par aucune fonction Python du projet
+
+Les commandes Claude Code (`review-spec.md:29`, `review-tasks.md:32`, `review-impl.md:31`) documentent explicitement : "Incrementer `reviewIterations.review-spec` (+1 a chaque execution, PASS ou BLOQUANT)". Mais cette instruction s'adresse au LLM qui execute la commande — elle n'est jamais validee ni appliquee par le code CLI.
+
+Le resultat : un champ toujours vide `{}` dans les state.json de features creees normalement, ce qui rend `devflow metrics` incapable de reporter les iterations de review.
+
+### Flux existants
+
+1. **Creation feature** : `devflow feature KS-123` → `create_state()` → `reviewIterations: {}`
+2. **Progression pipeline** : `advance_step()` ne touche jamais `reviewIterations`
+3. **Rollback** : `rollback_step()` ne touche jamais `reviewIterations`
+4. **Migration speckit** : `convert_speckit_state()` injecte `{gate: 0}` pour les gates auto-validees
+5. **Commandes review Claude Code** : le LLM est cense incrementer le compteur via ecriture directe dans state.json — non valide par la CLI
+
+### Dependances identifiees
+
+- **`FeatureState` (state.py:14-23)** : Le dataclass porte le champ. Toute modification impacte serialisation/deserialisation.
+- **`advance_step()` (state.py:152-222)** : Point d'entree naturel pour l'incrementation — gere deja `stepTimestamps` et `completedSteps`.
+- **`validate_and_advance()` (state.py:333-366)** : Compose validation + avancement. Point d'entree alternatif.
+- **Commandes review (`commands/devflow.review-*.md`)** : Documentent l'incrementation cote LLM. Doivent rester coherentes avec le code CLI.
+- **`devflow metrics` (`commands/devflow.metrics.md:19`)** : Consomme `reviewIterations` pour le reporting. Beneficiaire direct.
+- **Constitution (Principe III, lignes 59-60)** : "Le nombre d'iterations de review DOIT etre trace dans `reviewIterations`." — obligation constitutionnelle.
+
+### Limitations connues
+
+- Le champ est toujours `{}` pour les features normales (non-migrees depuis speckit)
+- `devflow metrics` ne peut pas reporter le nombre d'iterations de review
+- Aucune validation que le LLM a reellement incremente le compteur
+- Pas de distinction entre PASS et BLOQUANT dans le compteur (juste un entier)
+
+## Impact sur l'existant *(mandatory for brownfield)*
+
+### Composants affectes
+
+- **`state.py` — `advance_step()`** : Modifie pour incrementer `reviewIterations` quand l'etape completee est une gate de review
+- **`state.py` — `rollback_step()`** : Inchange — les iterations de review sont un historique, pas un etat reversible
+- **`__init__.py`** : Ajout d'une constante `REVIEW_GATES` pour identifier les etapes de review (eviter le hardcoding)
+- **Tests (`test_state.py`)** : Ajout de tests pour l'incrementation
+
+### Risques de regression
+
+- **Serialisation state.json** : Aucun risque — le champ existe deja, seul son contenu change (de `{}` a `{"review-spec": 1}` etc.)
+- **Migration speckit** : Aucun risque — `convert_speckit_state()` ecrit deja des valeurs dans `reviewIterations`
+- **Retrocompatibilite** : Les state.json existants avec `reviewIterations: {}` restent valides — le compteur demarre simplement a 0 implicitement
+
+### Strategie de migration
+
+Aucune migration necessaire. Les state.json existants restent valides. Les features deja en cours continueront normalement — leurs compteurs demarreront a 0 implicitement (absence de cle = 0 iterations passees). Retrocompatibilite totale.
+
+## User Scenarios & Testing *(mandatory)*
+
+### User Story 1 - Tracking automatique des iterations de review (Priority: P1)
+
+Quand une gate de review est completee (PASS), le systeme incremente automatiquement le compteur d'iterations correspondant dans state.json. L'utilisateur n'a rien a faire — c'est transparent.
+
+**Changement vs existant** : Aujourd'hui, `advance_step("review-spec")` met a jour `completedSteps` et `stepTimestamps` mais ignore `reviewIterations`. Demain, il incremente aussi le compteur.
+
+**Why this priority** : C'est le coeur de la feature. Sans ca, le champ reste mort.
+
+**Independent Test** : Creer un state a l'etape `review-spec`, appeler `advance_step("review-spec")`, verifier que `reviewIterations["review-spec"]` vaut 1.
+
+**Acceptance Scenarios**:
+
+1. **Given** un state avec `currentStep: "review-spec"` et `reviewIterations: {}`, **When** `advance_step(state, "review-spec")` est appele, **Then** `state.reviewIterations["review-spec"]` vaut 1 et `currentStep` avance a l'etape suivante.
+2. **Given** un state avec `currentStep: "review-tasks"` et `reviewIterations: {"review-spec": 2}`, **When** `advance_step(state, "review-tasks")` est appele, **Then** `state.reviewIterations` contient `{"review-spec": 2, "review-tasks": 1}`.
+3. **Given** un state avec `currentStep: "spec"` (pas une gate), **When** `advance_step(state, "spec")` est appele, **Then** `reviewIterations` est inchange.
+
+---
+
+### User Story 2 - Compteur persistant apres rollback + re-review (Priority: P1)
+
+Quand un utilisateur fait un rollback depuis une etape post-review, puis repasse la review, le compteur s'incremente a nouveau (compteur cumulatif, pas remis a zero).
+
+**Why this priority** : C'est le scenario typique d'une review BLOQUANT → correction → re-review. Le compteur doit refleter le nombre reel de passages.
+
+**Independent Test** : Avancer review-spec (iterations=1), rollback vers review-spec, re-avancer (iterations=2).
+
+**Acceptance Scenarios**:
+
+1. **Given** un state ou `review-spec` a ete avance une fois (`reviewIterations: {"review-spec": 1}`), puis rollback a ete effectue (currentStep revient a "review-spec"), **When** `advance_step(state, "review-spec")` est appele a nouveau, **Then** `reviewIterations["review-spec"]` vaut 2.
+
+---
+
+### User Story 3 - Constante REVIEW_GATES centralisee (Priority: P2)
+
+Les gates de review sont identifiees par une constante `REVIEW_GATES` dans `__init__.py`, pas par du hardcoding dans `advance_step()`.
+
+**Why this priority** : Evite la duplication et le risque d'oublier une gate si le pipeline evolue.
+
+**Independent Test** : Verifier que `REVIEW_GATES` est un sous-ensemble de `STEPS` et contient exactement les etapes `review-*`.
+
+**Acceptance Scenarios**:
+
+1. **Given** la constante `REVIEW_GATES`, **When** on verifie son contenu, **Then** elle contient exactement `{"review-spec", "review-tasks", "review-impl"}` et chaque element est dans `STEPS`.
+
+---
+
+### Edge Cases
+
+- Que se passe-t-il si `reviewIterations` contient une cle qui n'est pas dans `REVIEW_GATES` (ex: cle residuelle d'une migration) ? Le systeme l'ignore — seules les cles correspondant a des gates connues sont incrementees.
+- Que se passe-t-il pour un state.json legacy sans `reviewIterations` ? Le default `{}` s'applique via le dataclass — premiere incrementation cree la cle a 1. Retrocompatibilite preservee.
+- Que se passe-t-il si `advance_step()` est appele sur une etape non-review ? `reviewIterations` n'est pas touche.
+
+## Requirements *(mandatory)*
+
+### Functional Requirements
+
+- **FR-001** : Le systeme DOIT incrementer `reviewIterations[step]` de 1 chaque fois que `advance_step()` complete une etape qui est une gate de review.
+- **FR-002** : Le systeme DOIT fournir une constante `REVIEW_GATES` dans `__init__.py` listant les etapes de review (`review-spec`, `review-tasks`, `review-impl`).
+- **FR-003** : Le systeme NE DOIT PAS modifier `reviewIterations` lors de l'avancement d'une etape non-review.
+- **FR-004** : Le systeme DOIT preserver les valeurs existantes de `reviewIterations` lors d'un rollback (pas de remise a zero).
+- **FR-005** : Le systeme DOIT rester retrocompatible avec les state.json existants ou `reviewIterations` est `{}` ou absent.
+
+### Key Entities
+
+- **REVIEW_GATES** : Ensemble des etapes de review dans le pipeline. Utilise par `advance_step()` pour determiner si l'incrementation est necessaire.
+- **reviewIterations** : Dictionnaire `{gate_name: count}` dans `FeatureState`. Compteur cumulatif (jamais remis a zero) du nombre de fois qu'une gate de review a ete traversee.
+
+## Success Criteria *(mandatory)*
+
+### Measurable Outcomes
+
+- **SC-001** : Apres chaque passage d'une gate de review, le compteur correspondant dans state.json est incremente de 1.
+- **SC-002** : Une feature qui passe 3 fois par review-spec (2 BLOQUANT + 1 PASS) affiche `reviewIterations: {"review-spec": 3}` dans son state.json.
+- **SC-003** : No regression — les state.json existants (avec `reviewIterations: {}` ou sans le champ) restent lisibles et valides. Les 244 tests existants continuent de passer.
+- **SC-004** : `devflow metrics` peut reporter le nombre d'iterations de review pour chaque feature a partir des donnees dans state.json.

devflow_cli-2.3.0/.specify/specs/021-review-iterations/tasks.md

@@ -0,0 +1,140 @@
+# Tasks: Review Iterations Tracking
+
+**Input**: Design documents from `/specs/021-review-iterations/`
+**Prerequisites**: plan.md (required), spec.md (required), research.md
+
+**Tests**: Tests inclus — la constitution exige que tout nouveau comportement CLI soit accompagne d'un test (Principe VI).
+
+**Organization**: Tasks groupees par user story. US1 et US2 sont P1, US3 est P2.
+
+## Format: `[ID] [P?] [Story] Description`
+
+- **[P]**: Can run in parallel (different files, no dependencies)
+- **[Story]**: Which user story this task belongs to (e.g., US1, US2, US3)
+- Include exact file paths in descriptions
+
+## Phase 1: Setup
+
+**Purpose**: Ajout de la constante REVIEW_GATES
+
+- [x] [T-001] [P] Add REVIEW_GATES constant in src/devflow_cli/__init__.py — set {"review-spec", "review-tasks", "review-impl"} after OPTIONAL_STEPS (line 21) — Ref: FR-002
+
+**Checkpoint**: La constante est importable. Verifier avec `from devflow_cli import REVIEW_GATES`.
+
+---
+
+## Phase 2: User Story 1 - Tracking automatique des iterations de review (Priority: P1)
+
+**Goal**: `advance_step()` incremente automatiquement `reviewIterations[step]` quand l'etape completee est une gate de review.
+
+**Independent Test**: Creer un state a l'etape `review-spec`, appeler `advance_step("review-spec")`, verifier que `reviewIterations["review-spec"]` vaut 1.
+
+### Tests for User Story 1
+
+- [x] [T-002] [P] [P1] [US1] Add test_advance_step_increments_review_iterations in tests/test_state.py — Given state at review-spec with reviewIterations {}, When advance_step(state, "review-spec"), Then reviewIterations["review-spec"] == 1 — Ref: FR-001
+- [x] [T-003] [P] [P1] [US1] Add test_advance_step_no_increment_for_non_review in tests/test_state.py — Given state at spec, When advance_step(state, "spec"), Then reviewIterations unchanged (still {}) — Ref: FR-003
+- [x] [T-004] [P] [P1] [US1] Add test_advance_step_increments_each_gate_independently in tests/test_state.py — Advance review-spec then advance to review-tasks, verify each gate has its own counter {"review-spec": 1, "review-tasks": 1} — Ref: FR-001
+
+### Implementation for User Story 1
+
+- [x] [T-005] [P1] [US1] Import REVIEW_GATES in src/devflow_cli/core/state.py (add to existing import from devflow_cli line 10) and add review iteration increment in advance_step() after stepTimestamps update (after line 206): `if completed_step in REVIEW_GATES: state.reviewIterations[completed_step] = state.reviewIterations.get(completed_step, 0) + 1` — Ref: FR-001, FR-003
+
+**Checkpoint**: Les 3 tests passent. `advance_step()` incremente pour les gates, ignore pour les autres etapes.
+
+---
+
+## Phase 3: User Story 2 - Compteur persistant apres rollback + re-review (Priority: P1)
+
+**Goal**: Le compteur est cumulatif — apres rollback et re-review, il s'incremente a nouveau sans remise a zero.
+
+**Independent Test**: Avancer review-spec (iterations=1), rollback, re-avancer (iterations=2).
+
+### Tests for User Story 2
+
+- [x] [T-006] [P1] [US2] Add test_advance_step_cumulative_review_iterations in tests/test_state.py — advance review-spec (count=1), rollback_step to review-spec, advance review-spec again (count=2). Verify reviewIterations["review-spec"] == 2 — Ref: FR-004
+
+### Implementation for User Story 2
+
+Aucune implementation supplementaire — le comportement cumulatif decoule naturellement de l'implementation US1 (`.get(key, 0) + 1` incremente la valeur existante) et du fait que `rollback_step()` ne touche pas `reviewIterations`. Le test T006 valide ce comportement.
+
+**Checkpoint**: T006 passe. Le compteur survit au rollback.
+
+---
+
+## Phase 4: User Story 3 - Constante REVIEW_GATES centralisee (Priority: P2)
+
+**Goal**: Les gates de review sont identifiees par une constante, pas du hardcoding.
+
+**Independent Test**: Verifier que REVIEW_GATES est un sous-ensemble de STEPS et contient exactement 3 elements.
+
+### Tests for User Story 3
+
+- [x] [T-007] [P] [P2] [US3] Add test_review_gates_subset_of_steps in tests/test_state.py — assert REVIEW_GATES is subset of set(STEPS), assert len(REVIEW_GATES) == 3, assert all elements start with "review-" — Ref: FR-002
+
+### Implementation for User Story 3
+
+Deja implementee par T001. Le test T007 valide la constante.
+
+**Checkpoint**: T007 passe. La constante est coherente avec STEPS.
+
+---
+
+## Phase 5: Polish & Cross-Cutting Concerns
+
+**Purpose**: Validation retrocompatibilite et tests existants
+
+- [x] [T-008] [P] Add test_advance_step_review_iterations_legacy_state in tests/test_state.py — Given state loaded from JSON without reviewIterations key (simulating legacy), When advance_step on review-spec, Then reviewIterations["review-spec"] == 1 — Ref: FR-005
+- [x] [T-009] Run full test suite (pytest tests/ -v) — verify all 244+ existing tests still pass, no regression — Ref: SC-003
+
+**Checkpoint**: Suite de tests complete. Zero regression.
+
+---
+
+## Dependencies & Execution Order
+
+### Phase Dependencies
+
+- **Phase 1 (Setup)**: Aucune dependance — constante standalone
+- **Phase 2 (US1)**: Depend de Phase 1 ([T-005] importe REVIEW_GATES cree par [T-001])
+- **Phase 3 (US2)**: Depend de Phase 2 ([T-006] utilise advance_step modifie par [T-005])
+- **Phase 4 (US3)**: Depend de Phase 1 seulement ([T-007] teste la constante [T-001])
+- **Phase 5 (Polish)**: Depend de Phase 2 (tests de retrocompatibilite)
+
+### User Story Dependencies
+
+- **US1 (P1)**: Depend de [T-001] (constante). Coeur de la feature.
+- **US2 (P1)**: Depend de US1 (comportement). Aucun code supplementaire.
+- **US3 (P2)**: Depend de [T-001] seulement. Peut etre teste en parallele avec US1.
+
+### Parallel Opportunities
+
+- [T-001] et [T-007] peuvent etre implementes en parallele (fichiers differents, pas de dependance)
+- [T-002], [T-003], [T-004] peuvent etre **ecrits** en parallele, mais ne passeront qu'apres [T-005] (ils testent le code de T-005)
+- [T-008] peut demarrer des que [T-005] est complete
+
+---
+
+## Implementation Strategy
+
+### MVP First (US1 Only)
+
+1. [T-001]: Constante REVIEW_GATES
+2. [T-005]: Modification advance_step()
+3. [T-002]+[T-003]+[T-004]: Tests US1
+4. **STOP and VALIDATE**: `pytest tests/test_state.py -v -k "review_iterations"`
+
+### Incremental Delivery
+
+1. [T-001] → [T-005] → [T-002]/[T-003]/[T-004] → US1 fonctionnel
+2. [T-006] → US2 valide (zero code supplementaire)
+3. [T-007] → US3 valide (zero code supplementaire)
+4. [T-008] → [T-009] → Retrocompatibilite confirmee
+
+---
+
+## Notes
+
+- 9 taches au total, dont 1 seule tache d'implementation reelle ([T-005])
+- La feature est minimaliste par design : 2 lignes de code + 1 constante
+- US2 et US3 ne necessitent pas de code supplementaire — juste des tests validant le comportement emergent
+- Commit recommande apres [T-005] (implementation) puis apres [T-009] (validation complete)

devflow_cli-2.3.0/.specify/specs/022-fix-regen-command/checklists/requirements.md

@@ -0,0 +1,35 @@
+# Specification Quality Checklist: Fix Regen Command
+
+**Purpose**: Validate specification completeness and quality before proceeding to planning
+**Created**: 2026-03-21
+**Feature**: [spec.md](../spec.md)
+
+## Content Quality
+
+- [x] No implementation details (languages, frameworks, APIs)
+- [x] Focused on user value and business needs
+- [x] Written for non-technical stakeholders
+- [x] All mandatory sections completed
+
+## Requirement Completeness
+
+- [x] No [NEEDS CLARIFICATION] markers remain
+- [x] Requirements are testable and unambiguous
+- [x] Success criteria are measurable
+- [x] Success criteria are technology-agnostic (no implementation details)
+- [x] All acceptance scenarios are defined
+- [x] Edge cases are identified
+- [x] Scope is clearly bounded
+- [x] Dependencies and assumptions identified
+
+## Feature Readiness
+
+- [x] All functional requirements have clear acceptance criteria
+- [x] User scenarios cover primary flows
+- [x] Feature meets measurable outcomes defined in Success Criteria
+- [x] No implementation details leak into specification
+
+## Notes
+
+- Spec references file paths in "Comportement existant" — acceptable for brownfield documentation.
+- No NEEDS CLARIFICATION — scope is narrow (rename + update references).

devflow_cli-2.3.0/.specify/specs/022-fix-regen-command/plan.md

@@ -0,0 +1,100 @@
+# Implementation Plan: Fix Regen Command
+
+**Branch**: `022-fix-regen-command` | **Date**: 2026-03-21 | **Spec**: [spec.md](./spec.md)
+**Input**: Feature specification from `/specs/022-fix-regen-command/spec.md`
+
+## Summary
+
+Renommer la commande CLI `devflow regen` en `devflow stale` pour aligner le nom avec le comportement reel (detection de desynchronisation, pas de regeneration). Mettre a jour toutes les references : commande Claude Code, tests, documentation.
+
+## Technical Context
+
+**Language/Version**: Python 3.11+
+**Primary Dependencies**: typer (>=0.12), rich (>=13) — aucune nouvelle dependance
+**Storage**: N/A — renommage pur
+**Testing**: pytest (>=8)
+**Target Platform**: CLI multi-OS
+**Project Type**: CLI
+**Performance Goals**: N/A
+**Constraints**: Pas d'alias de retrocompatibilite
+**Scale/Scope**: 6 fichiers renommes/modifies, 0 nouvelles lignes de logique
+
+## Constitution Check
+
+*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*
+
+| Principe | Verdict | Justification |
+|----------|---------|---------------|
+| I. Spec-Driven Development | PASS | Spec redigee avant code |
+| II. Pipeline Sequentiel | PASS | Aucun impact sur le pipeline |
+| III. Gates de Review | PASS | Aucun impact |
+| IV. Retrocompatibilite | PASS | Pas d'alias — le nom `regen` n'a jamais fait ce qu'il promettait, pas de contrat a preserver |
+| V. Simplicite (YAGNI) | PASS | Renommage pur, zero complexite ajoutee |
+| VI. Testabilite | PASS | Tests renommes et mis a jour |
+| VII. Integration Linear | PASS | Aucun impact |
+
+## Project Structure
+
+### Documentation (this feature)
+
+```text
+specs/022-fix-regen-command/
+├── spec.md
+├── plan.md              # This file
+├── research.md          # Phase 0 output
+└── checklists/
+    └── requirements.md
+```
+
+### Source Code (repository root)
+
+```text
+src/devflow_cli/
+├── cli.py               # Renommage enregistrement regen → stale
+└── commands/
+    ├── regen.py          # SUPPRIME
+    └── stale.py          # CREE (contenu identique, messages reformules)
+
+commands/
+└── devflow.regen.md     # Modifie (appel devflow stale --json)
+
+tests/
+├── test_cmd_regen.py    # SUPPRIME
+└── test_cmd_stale.py    # CREE (contenu identique, references mises a jour)
+
+docs/
+├── cli-reference.md     # Section renommee
+└── commands-reference.md # Reference mise a jour
+```
+
+**Structure Decision**: Renommage de fichiers (suppression ancien + creation nouveau). Pas de refactoring de la logique interne.
+
+## Complexity Tracking
+
+Aucune violation de constitution. Pas de complexite ajoutee.
+
+## Design
+
+### Approche
+
+Renommage direct en 3 etapes :
+
+1. **Fichier source** : `regen.py` → `stale.py`, fonction `regen()` → `stale()`, messages reformules
+2. **Enregistrement CLI** : dans `cli.py`, changer `app.command("regen")` → `app.command("stale")` et l'import correspondant
+3. **References** : commande Claude Code, tests, docs
+
+### Modifications des messages
+
+| Avant | Apres |
+|-------|-------|
+| `devflow regen — {name}` | `devflow stale — {name}` |
+| `Regenerer ?` | `Voir les commandes de regeneration ?` |
+| `Lancez les commandes suivantes dans l'ordre :` | Inchange (factuel) |
+| `Ou utilisez /devflow.regen pour execution automatique.` | Inchange |
+
+### Ce qui ne change PAS
+
+- `staleness.py` : module de detection (inchange)
+- `REGEN_COMMANDS` : dictionnaire de mapping artefact → commande (le nom est interne, pas expose a l'utilisateur)
+- `/devflow.regen` (nom de la commande Claude Code) : garde son nom car elle fait la vraie regeneration en cascade. Seul l'appel CLI interne change.
+- Logique de detection, format JSON, options --only et --json

devflow_cli-2.3.0/.specify/specs/022-fix-regen-command/research.md

@@ -0,0 +1,32 @@
+# Research: Fix Regen Command
+
+**Branch**: `022-fix-regen-command` | **Date**: 2026-03-21
+
+## Renommage vs alias de compatibilite
+
+**Decision**: Renommage direct sans alias.
+
+**Rationale**: La commande `regen` n'a jamais regenere quoi que ce soit — elle detecte et suggere. Un alias preserverait un nom trompeur. La seule reference externe est `/devflow.regen` (commande Claude Code) qu'on met a jour simultanement.
+
+**Alternatives considered**:
+- Alias `regen` → `stale` : preserve la compatibilite mais perpetue la confusion
+- Deprecation warning pendant N versions : over-engineering pour un outil personnel
+
+## Nom de la commande Claude Code
+
+**Decision**: `/devflow.regen` garde son nom.
+
+**Rationale**: Contrairement a la CLI, la commande Claude Code `/devflow.regen` fait reellement la regeneration (elle execute les commandes en cascade). Le nom est donc correct pour elle. Seul l'appel interne change (`devflow stale --json` au lieu de `devflow regen --json`).
+
+**Alternatives considered**:
+- Renommer aussi en `/devflow.stale` : incoherent — la commande Claude Code regenere vraiment
+- Creer `/devflow.stale` comme alias de detection pure : inutile — `devflow stale --json` suffit
+
+## Nom de la constante REGEN_COMMANDS
+
+**Decision**: Garder le nom `REGEN_COMMANDS` dans `staleness.py`.
+
+**Rationale**: C'est un nom interne (pas expose a l'utilisateur). Le renommer en `STALE_COMMANDS` ou `REGEN_MAPPING` serait du refactoring cosmétique sans valeur. Constitution Principe V : "Les patterns existants DOIVENT etre suivis."
+
+**Alternatives considered**:
+- Renommer en `STALE_COMMANDS` : changement cosmétique, touche plus de fichiers sans benefice