Name: us-generate
Author: zekiriabd

Prompt file imported from zekiriabd/SDD-Pro (.codex/prompts/us-generate.md). Fill in {{arguments}} before use. Copyright stays with the author.

Arguments: {{arguments}}

/us-generate — Découpe une FEAT en User Stories

⚠️ Commande interne v7.0.0 — invoquée par /sdd-full STEP 2. Utilisateur final : préférer /sdd-full ou /dev-run (gèrent pré-conditions, idempotence, état).

Invoque l'agent PO pour découper une FEAT fonctionnelle en User Stories structurées (cible UsGranularityTarget défaut 3, warn au-delà de UsGranularityWarnAt défaut 6, hard cap UsGranularityHardCap défaut 10) dans workspace/.

Usage :

/us-generate {n} — où {n} est le numéro de la FEAT
/us-generate {n} --replace-pseudo — migration POC → standard : supprime la pseudo-US générée par /sdd-poc avant de générer les vraies US

STEP 1 — Valider les arguments

Arguments :

{n} (entier ≥ 1, obligatoire)
--allow-large-feat (optionnel, v7.0.0 P2 #13) — bypass conscient du hard cap UsGranularityHardCap (default 10). À utiliser pour FEATs métier légitimement très larges (≥ 11 flux distincts). Effet : export SDD_ALLOW_LARGE_FEAT=1 avant invocation agent po, audit-log dans workspace/.sys/.audit/force-bypass.log. Préférer split FEAT.
--replace-pseudo (optionnel, fix C1 audit 2026-08-30) — migration POC → standard (chemin promis par /sdd-poc STEP 8 et feat_to_pseudo_us.py). Supprime AVANT génération les pseudo-US POC de la FEAT (fichiers workspace/us/{n}-*.md portant le marqueur frontmatter generated-by: feat_to_pseudo_us.py), puis la génération PO produit les vraies US granulaires. Sans ce flag, une pseudo-US résiduelle cohabite avec les vraies US (le PO écrase {n}-{m}-{Name}.md par basename, pas par {m} — la pseudo {n}-1-{FeatName}.md survivrait si le {Name} réel diffère) → WARN collision émis (cf. STEP 2.4 et po.md STEP 2.bis). No-op silencieux si aucune pseudo-US détectée (idempotent).

Si {n} absent → demander :

Quel est le numéro de la FEAT à découper ? (ex. : 1 pour workspace/feats/1-Auth.md)

Si non numérique → ERROR :

ERROR: /us-generate — argument invalide
CAUSE: [INVALID_ARG] "{argument}" n'est pas un entier
FIX: relancer /us-generate {n} avec n entier (ex. /us-generate 1)

Propagation `--allow-large-feat`

if [[ "$@" == *--allow-large-feat* ]]; then
    export SDD_ALLOW_LARGE_FEAT=1
    mkdir -p workspace/.sys/.audit
    echo "$(date -u +%Y-%m-%dT%H:%M:%SZ) /us-generate {n} --allow-large-feat (bypass UsGranularityHardCap)" \
      >> workspace/.sys/.audit/force-bypass.log
fi

L'agent po (STEP 5) lit cette env var pour passer outre le hard cap.

STEP 2 — Vérifier la FEAT existe

Glob workspace/feats/{n}-*.md.

0 fichier → ERROR :

ERROR: /us-generate — FEAT introuvable
CAUSE: [FEAT_NOT_FOUND] aucun fichier workspace/feats/{n}-*.md
FIX: créer la FEAT via /feat-generate ou la déposer manuellement

1 fichier → ERROR :

ERROR: /us-generate — numérotation invalide
CAUSE: [FEAT_AMBIGUOUS] plusieurs fichiers commencent par {n}- dans workspace/feats/
FIX: renommer pour qu'un seul fichier ait le préfixe {n}-

STEP 2.4 — Pseudo-US POC : remplacement ou WARN collision (fix C1, 2026-08-30)

Détecter les pseudo-US POC de la FEAT via le marqueur frontmatter écrit par feat_to_pseudo_us.py (generated-by: feat_to_pseudo_us.py) :

PSEUDO_US=$(grep -l "generated-by: feat_to_pseudo_us.py" workspace/us/{n}-*.md 2>/dev/null)

if [[ "$@" == *--replace-pseudo* ]]; then
  if [ -n "$PSEUDO_US" ]; then
    N_PSEUDO=$(echo "$PSEUDO_US" | wc -l)
    echo "$PSEUDO_US" | xargs rm -f
    echo "[PO] $N_PSEUDO pseudo-US POC supprimée(s) avant génération (--replace-pseudo). (5%)"
  else
    echo "[PO/SKIP] --replace-pseudo : aucune pseudo-US POC détectée (no-op idempotent). (5%)"
  fi
elif [ -n "$PSEUDO_US" ]; then
  echo "🟡 [PO/WARN] Pseudo-US POC présente(s) sans --replace-pseudo : $PSEUDO_US" >&2
  echo "   Elle(s) survivront à la génération si le {Name} réel diffère → doublon d'US {n}-1." >&2
  echo "   Recommandé : /us-generate {n} --replace-pseudo (migration POC → standard)." >&2
fi

Pourquoi ici et pas dans l'agent po : la suppression est une décision d'orchestration (flag CLI) ; l'agent po reste strictement exécutif. Il porte néanmoins le même check en filet de sécurité WARN (invocation po standalone hors /us-generate) — cf. agents/po.md STEP 2.bis.

STEP 2.5 — Checkpoint skip (v6.6.4, opt-in)

Si CheckpointMode: resume dans Project Config (défaut off = comportement v6.6.3 strict) :

from sdd_lib.checkpoint import is_phase_resumable

inputs = [
    f"workspace/feats/{n}-*.md",      # FEAT parent
    "workspace/stack/stack.md",       # Project Config + stacks actifs
]
resumable, reason = is_phase_resumable(
    feat=n, phase="us-generate", input_paths=resolved_inputs,
)
if resumable:
    print(f"⊘ /us-generate {n}: skipped (checkpoint hit)")
    # STOP avec succès, ne pas re-déléguer à l'agent PO

Si CheckpointMode ∈ {off, record} → skip ce STEP, continuer.

Émissions possibles : [CHECKPOINT_HASH_MISMATCH], [CHECKPOINT_INPUT_MISSING], [CHECKPOINT_STATE_UNREADABLE]. Cf. error-classification.md §1.14.

STEP 3 — Invoquer l'agent PO

Lancer l'agent po (défini dans .claude/agents/po.md) avec le numéro {n} en argument. L'agent gère le découpage, la traçabilité et l'écriture des fichiers US dans workspace/.

Attendre la fin de l'agent. Relayer sa sortie telle quelle (ligne de succès ou bloc ERROR 3 lignes).

STEP 3.0 — Résoudre le sentinel `Parent FEAT hash` (v7.0.0-alpha, 2026-05-22 ; refactor 2026-06-05)

Si l'agent po a réussi (US écrites), patcher les sentinels sha256:COMPUTE_REQUIRED en hash sha256 réel avant STEP 3.bis.

L'agent po n'a pas le tool Bash (cf. po.md frontmatter tools: Read, Write, Edit, Glob, Grep) et ne peut pas calculer le hash lui-même. Il écrit le sentinel littéral, et cette commande le résout en post-step déterministe (0 token LLM, ~50 ms).

v7.0.0-alpha audit P0-workflow 2026-06-05 — historiquement l'inline python -c "..." vivait ici. Refactor : extrait vers sdd_scripts/resolve_us_hash_sentinel.py (SSoT) + posé comme SubagentStop hook matcher=po (defense-in-depth). Le hook ferme le gap où po était invoqué standalone (hors /us-generate) et laissait le sentinel non résolu → tous les downstream émettaient [FEAT_HASH_MISMATCH]. Ce STEP reste le chemin nominal ; le hook est un filet de sécurité (idempotent — no-op si déjà résolu).

Invocation (déterministe, 0 token LLM, ~50 ms, cross-platform) :

python .sdd/python/sdd_scripts/resolve_us_hash_sentinel.py --feat-number {n}

Garanties (préservées vs implémentation inline) :

Aucune dépendance externe (sed/python/Git Bash) — Python stdlib seulement
UTF-8 sans BOM (compatible parser frontmatter YAML cross-OS)
Line endings préservés (newline='' → conserve LF original, pas de CRLF Windows)
Idempotent : re-exécution sur US déjà patchées → 0 patch

Exit	Sens	Action caller
`0`	succès (N US patchées OU rien à faire)	continuer STEP 3.bis
`2`	sentinel persiste après patch (corruption FS)	STOP + ERROR `[PO_HASH_PLACEHOLDER]`
`3`	erreur infra (FEAT file missing, FS perms)	STOP + ERROR `[INFRA_BLOCKED]`

Format ERROR (exit 2) :

ERROR: /us-generate {n} — sentinel hash non résolu
CAUSE: [PO_HASH_PLACEHOLDER] sha256:COMPUTE_REQUIRED persiste dans {N} fichier(s) US après patch
FIX: vérifier permissions FS sur workspace/us/, relancer /us-generate {n} (idempotent)

STEP 3.bis — Checkpoint record (v6.6.4, opt-in)

Si l'agent PO a réussi (US écrites) ET CheckpointMode ∈ {record, resume} :

from sdd_lib.checkpoint import record_input_hash

record_input_hash(
    run_id=$RUN_ID,
    phase="us-generate",
    input_paths=resolved_inputs,    # FEAT + stack.md
)

Erreur silencieuse si state.json absent → WARN, non bloquant.

STEP 3.ter — Auto-ingest FEAT/US dans console.db (depuis 2026-05-21)

Si l'agent PO a réussi (US écrites), invoquer systématiquement le script déterministe ingest_feats_us.py pour populer correctement les tables feats et us de workspace/db/console.db (cf. gap framework identifié 2026-05-21 — auparavant seules les colonnes skeleton feat_n + feat-{n} étaient remplies par les auditors via ensure_feat_skeleton(), laissant name, actors_json, ac_count, sfd_count, br_count, fd_count, covers_json, status à null/zéro et brisant l'affichage de la console web dashboard).

python .sdd/python/sdd_scripts/ingest_feats_us.py 2>&1 | tail -1

Exit	Sens	Action caller
`0`	Ingest OK	continuer (log 1 ligne `[OK] ingested N FEATs + M US`)
`1`	DB introuvable / corrompue	WARN 1 ligne, continuer (non bloquant)

Idempotent : utilise ON CONFLICT(feat_n|us_id) DO UPDATE — re-exécution sans effet sur les counts (ré-écrit avec mêmes valeurs).

Coût : 0 token LLM, ~50 ms, parse markdown déterministe (regex SFD-N / BR-N / AC-N / FD-N / ## Actors / Covers:).

Non bloquant : un échec de l'ingest n'invalide pas le succès du PO. Les US sur disque restent la SSoT ; le DB n'est qu'un cache projeté pour la console web.

STEP 4 — Inventaire des mockups HTML (depuis v4)

Glob workspace/ui/{n}-*.html pour détecter les mockups déjà déposés.

Glob workspace/us/{n}-*.md pour récupérer les basenames d'US.

Cross-check :

HTML dont basename matche une US → couvert
HTML dont basename ne matche aucune US → orphelin (WARN)
US sans HTML → info (frontend possible sans mockup OU backend-only)

Émettre la liste compactement (1 ligne par US et 1 ligne par orphelin).

Si aucun HTML détecté ET au moins une US a une composante UI attendue, émettre une info non bloquante invitant à déposer les mockups (convention {n}-{m}-{Name}.html).

STEP 5 — Confirmation finale

Si l'agent PO réussit, ajouter le récap final :

✅ FEAT {n}-{FeatName} — planification terminée

US générées      : {U} fichiers dans workspace/us/
Mockups HTML     : {H} fichiers dans workspace/ui/ (ou "aucun")
HTML orphelins   : {O} (à corriger ou retirer)
US sans mockup   : {U-H}

Prochaine étape :
  - (optionnel) déposer/réviser les mockups HTML (workspace/ui/{n}-{m}-{Name}.html)
  - /dev-run {n} pour matérialiser le code (arch + db + back + front en parallèle)
  - ou /sdd-full {n} pour pipeline complet

Si l'agent échoue, ne rien ajouter (l'ERROR 3 lignes de l'agent suffit).

Règles de cette commande

Pas de Q/R utilisateur après le STEP 1 (l'agent est autonome)
Pas de modification de la FEAT parente
Pas de génération de code (réservé à /dev-backend, /dev-frontend, /dev-run)
Pas de lecture des mockups HTML ou du stack (réservé aux agents dev-*)

Install us-generate and it becomes one more candidate the router can pick - when it fits.

A listing is a routing target with a manifest: what it does, which domains it covers, what it costs and who publishes it. Once installed it sits beside your own models and tools, is scored like any other candidate for each request, and shows up in the trace when it wins. Ratings come from workspaces that installed it, one per account.

Arguments: {{arguments}} # /us-generate — Découpe une FEAT en User Stories  > ⚠️ **Commande interne v7.0.0** — invoquée par `/sdd-full` STEP 2. > Utilisateur final : préférer `/sdd-full` ou `/dev-run` (gèrent pré-conditions, idempotence, état). Invoque l'agent PO pour découper une FEAT fonctionnelle en User Stories structurées (cible `UsGranularityTarget` défaut 3, warn au-delà de `UsGranularityWarnAt` défaut 6, hard cap `UsGranularityHardCap` défaut 10) dans `workspace/`. **Usage :** - `/us-generate {n}` — où `{n}` est le numéro de la FEAT - `/us-generate {n} --replace-pseudo` — migration POC → standard : supprime la pseudo-US générée par `/sdd-poc` avant de générer les vraies US --- ## STEP 1 — Valider les arguments Arguments : - `{n}` (entier ≥ 1, **obligatoire**) - `--allow-large-feat` (optionnel, v7.0.0 P2 #13) — bypass conscient du hard cap `UsGranularityHardCap` (default 10). À utiliser pour FEATs métier légitimement très larges (≥ 11 flux distincts). Effet : export `SDD_ALLOW_LARGE_FEAT=1` avant invocation agent `po`, audit-log dans `workspace/.sys/.audit/force-bypass.log`. Préférer split FEAT. - `--replace-pseudo` (optionnel, fix C1 audit 2026-08-30) — **migration POC → standard** (chemin promis par `/sdd-poc` STEP 8 et `feat_to_pseudo_us.py`). Supprime AVANT génération les pseudo-US POC de la FEAT (fichiers `workspace/us/{n}-*.md` portant le marqueur frontmatter `generated-by: feat_to_pseudo_us.py`), puis la génération PO produit les vraies US granulaires. Sans ce flag, une pseudo-US résiduelle cohabite avec les vraies US (le PO écrase `{n}-{m}-{Name}.md` par basename, pas par `{m}` — la pseudo `{n}-1-{FeatName}.md` survivrait si le `{Name}` réel diffère) → WARN collision émis (cf. STEP 2.4 et po.md STEP 2.bis). No-op silencieux si aucune pseudo-US détectée (idempotent). Si `{n}` absent → demander : ``` Quel est le numéro de la FEAT à découper ? (ex. : 1 pour workspace/feats/1-Auth.md) ``` Si non numérique → ERROR : ``` ERROR: /us-generate — argument invalide CAUSE: [INVALID_ARG] "{argument}" n'est pas un entier FIX: relancer /us-generate {n} avec n entier (ex. /us-generate 1) ``` ### Propagation `--allow-large-feat` ```bash if [[ "$@" == *--allow-large-feat* ]]; then export SDD_ALLOW_LARGE_FEAT=1 mkdir -p workspace/.sys/.audit echo "$(date -u +%Y-%m-%dT%H:%M:%SZ) /us-generate {n} --allow-large-feat (bypass UsGranularityHardCap)" \ >> workspace/.sys/.audit/force-bypass.log fi ``` L'agent `po` (STEP 5) lit cette env var pour passer outre le hard cap. --- ## STEP 2 — Vérifier la FEAT existe Glob `workspace/feats/{n}-*.md`. - 0 fichier → ERROR : ``` ERROR: /us-generate — FEAT introuvable CAUSE: [FEAT_NOT_FOUND] aucun fichier workspace/feats/{n}-*.md FIX: créer la FEAT via /feat-generate ou la déposer manuellement ``` - > 1 fichier → ERROR : ``` ERROR: /us-generate — numérotation invalide CAUSE: [FEAT_AMBIGUOUS] plusieurs fichiers commencent par {n}- dans workspace/feats/ FIX: renommer pour qu'un seul fichier ait le préfixe {n}- ``` --- ## STEP 2.4 — Pseudo-US POC : remplacement ou WARN collision (fix C1, 2026-08-30) Détecter les pseudo-US POC de la FEAT via le marqueur frontmatter écrit par `feat_to_pseudo_us.py` (`generated-by: feat_to_pseudo_us.py`) : ```bash PSEUDO_US=$(grep -l "generated-by: feat_to_pseudo_us.py" workspace/us/{n}-*.md 2>/dev/null) if [[ "$@" == *--replace-pseudo* ]]; then if [ -n "$PSEUDO_US" ]; then N_PSEUDO=$(echo "$PSEUDO_US" | wc -l) echo "$PSEUDO_US" | xargs rm -f echo "[PO] $N_PSEUDO pseudo-US POC supprimée(s) avant génération (--replace-pseudo). (5%)" else echo "[PO/SKIP] --replace-pseudo : aucune pseudo-US POC détectée (no-op idempotent). (5%)" fi elif [ -n "$PSEUDO_US" ]; then echo "🟡 [PO/WARN] Pseudo-US POC présente(s) sans --replace-pseudo : $PSEUDO_US" >&2 echo " Elle(s) survivront à la génération si le {Name} réel diffère → doublon d'US {n}-1." >&2 echo " Recommandé : /us-generate {n} --replace-pseudo (migration POC → standard)." >&2 fi ``` > **Pourquoi ici et pas dans l'agent `po`** : la suppression est une décision > d'orchestration (flag CLI) ; l'agent `po` reste strictement exécutif. Il > porte néanmoins le même check en filet de sécurité WARN (invocation `po` > standalone hors `/us-generate`) — cf. `agents/po.md` STEP 2.bis. --- ## STEP 2.5 — Checkpoint skip (v6.6.4, opt-in) Si `CheckpointMode: resume` dans Project Config (défaut `off` = comportement v6.6.3 strict) : ```python from sdd_lib.checkpoint import is_phase_resumable inputs = [ f"workspace/feats/{n}-*.md", # FEAT parent "workspace/stack/stack.md", # Project Config + stacks actifs ] resumable, reason = is_phase_resumable( feat=n, phase="us-generate", input_paths=resolved_inputs, ) if resumable: print(f"⊘ /us-generate {n}: skipped (checkpoint hit)") # STOP avec succès, ne pas re-déléguer à l'agent PO ``` Si `CheckpointMode ∈ {off, record}` → skip ce STEP, continuer. Émissions possibles : `[CHECKPOINT_HASH_MISMATCH]`, `[CHECKPOINT_INPUT_MISSING]`, `[CHECKPOINT_STATE_UNREADABLE]`. Cf. `error-classification.md §1.14`. --- ## STEP 3 — Invoquer l'agent PO Lancer l'agent `po` (défini dans `.claude/agents/po.md`) avec le numéro `{n}` en argument. L'agent gère le découpage, la traçabilité et l'écriture des fichiers US dans `workspace/`. Attendre la fin de l'agent. Relayer sa sortie telle quelle (ligne de succès ou bloc ERROR 3 lignes). ### STEP 3.0 — Résoudre le sentinel `Parent FEAT hash` (v7.0.0-alpha, 2026-05-22 ; refactor 2026-06-05) Si l'agent `po` a réussi (US écrites), patcher les sentinels `sha256:COMPUTE_REQUIRED` en hash sha256 réel **avant** STEP 3.bis. L'agent `po` n'a pas le tool `Bash` (cf. po.md frontmatter `tools: Read, Write, Edit, Glob, Grep`) et ne peut pas calculer le hash lui-même. Il écrit le sentinel littéral, et cette commande le résout en post-step déterministe (0 token LLM, ~50 ms). > **v7.0.0-alpha audit P0-workflow 2026-06-05** — historiquement > l'inline `python -c "..."` vivait ici. Refactor : extrait vers > `sdd_scripts/resolve_us_hash_sentinel.py` (SSoT) + posé comme > SubagentStop hook matcher=`po` (defense-in-depth). Le hook ferme > le gap où `po` était invoqué standalone (hors `/us-generate`) et > laissait le sentinel non résolu → tous les downstream émettaient > `[FEAT_HASH_MISMATCH]`. Ce STEP reste le chemin nominal ; le hook > est un filet de sécurité (idempotent — no-op si déjà résolu). **Invocation** (déterministe, 0 token LLM, ~50 ms, cross-platform) : ```bash python .sdd/python/sdd_scripts/resolve_us_hash_sentinel.py --feat-number {n} ``` **Garanties** (préservées vs implémentation inline) : - Aucune dépendance externe (`sed`/`python`/Git Bash) — Python stdlib seulement - UTF-8 sans BOM (compatible parser frontmatter YAML cross-OS) - Line endings préservés (`newline=''` → conserve LF original, pas de CRLF Windows) - Idempotent : re-exécution sur US déjà patchées → 0 patch | Exit | Sens | Action caller | |---|---|---| | `0` | succès (N US patchées OU rien à faire) | continuer STEP 3.bis | | `2` | sentinel persiste après patch (corruption FS) | STOP + ERROR `[PO_HASH_PLACEHOLDER]` | | `3` | erreur infra (FEAT file missing, FS perms) | STOP + ERROR `[INFRA_BLOCKED]` | **Format ERROR (exit 2)** : ``` ERROR: /us-generate {n} — sentinel hash non résolu CAUSE: [PO_HASH_PLACEHOLDER] sha256:COMPUTE_REQUIRED persiste dans {N} fichier(s) US après patch FIX: vérifier permissions FS sur workspace/us/, relancer /us-generate {n} (idempotent) ``` ### STEP 3.bis — Checkpoint record (v6.6.4, opt-in) Si l'agent PO a réussi (US écrites) ET `CheckpointMode ∈ {record, resume}` : ```python from sdd_lib.checkpoint import record_input_hash record_input_hash( run_id=$RUN_ID, phase="us-generate", input_paths=resolved_inputs, # FEAT + stack.md ) ``` Erreur silencieuse si state.json absent → WARN, non bloquant. --- ### STEP 3.ter — Auto-ingest FEAT/US dans console.db (depuis 2026-05-21) Si l'agent PO a réussi (US écrites), invoquer **systématiquement** le script déterministe `ingest_feats_us.py` pour populer correctement les tables `feats` et `us` de `workspace/db/console.db` (cf. gap framework identifié 2026-05-21 — auparavant seules les colonnes skeleton `feat_n` + `feat-{n}` étaient remplies par les auditors via `ensure_feat_skeleton()`, laissant `name`, `actors_json`, `ac_count`, `sfd_count`, `br_count`, `fd_count`, `covers_json`, `status` à null/zéro et brisant l'affichage de la console web dashboard). ```bash python .sdd/python/sdd_scripts/ingest_feats_us.py 2>&1 | tail -1 ``` | Exit | Sens | Action caller | |---|---|---| | `0` | Ingest OK | continuer (log 1 ligne `[OK] ingested N FEATs + M US`) | | `1` | DB introuvable / corrompue | WARN 1 ligne, continuer (non bloquant) | **Idempotent** : utilise `ON CONFLICT(feat_n|us_id) DO UPDATE` — re-exécution sans effet sur les counts (ré-écrit avec mêmes valeurs). **Coût** : 0 token LLM, ~50 ms, parse markdown déterministe (regex SFD-N / BR-N / AC-N / FD-N / `## Actors` / `Covers:`). **Non bloquant** : un échec de l'ingest n'invalide pas le succès du PO. Les US sur disque restent la SSoT ; le DB n'est qu'un cache projeté pour la console web. --- ## STEP 4 — Inventaire des mockups HTML (depuis v4) Glob `workspace/ui/{n}-*.html` pour détecter les mockups déjà déposés. Glob `workspace/us/{n}-*.md` pour récupérer les basenames d'US. Cross-check : - HTML dont basename matche une US → couvert - HTML dont basename ne matche aucune US → orphelin (WARN) - US sans HTML → info (frontend possible sans mockup OU backend-only) Émettre la liste compactement (1 ligne par US et 1 ligne par orphelin). Si aucun HTML détecté ET au moins une US a une composante UI attendue, émettre une info non bloquante invitant à déposer les mockups (convention `{n}-{m}-{Name}.html`). --- ## STEP 5 — Confirmation finale Si l'agent PO réussit, ajouter le récap final : ``` ✅ FEAT {n}-{FeatName} — planification terminée US générées : {U} fichiers dans workspace/us/ Mockups HTML : {H} fichiers dans workspace/ui/ (ou "aucun") HTML orphelins : {O} (à corriger ou retirer) US sans mockup : {U-H} Prochaine étape : - (optionnel) déposer/réviser les mockups HTML (workspace/ui/{n}-{m}-{Name}.html) - /dev-run {n} pour matérialiser le code (arch + db + back + front en parallèle) - ou /sdd-full {n} pour pipeline complet ``` Si l'agent échoue, ne rien ajouter (l'ERROR 3 lignes de l'agent suffit). --- ## Règles de cette commande - Pas de Q/R utilisateur après le STEP 1 (l'agent est autonome) - Pas de modification de la FEAT parente - Pas de génération de code (réservé à `/dev-backend`, `/dev-frontend`, `/dev-run`) - Pas de lecture des mockups HTML ou du stack (réservé aux agents dev-*)

{ "prompt": "\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\nArguments: {{arguments}}\n\n# /us-generate — Découpe une FEAT en User Stories\n\n\n\n> ⚠️ **Commande interne v7.0.0** — invoquée par `/sdd-full` STEP 2.\n> Utilisateur final : préférer `/sdd-full` ou `/dev-run` (gèrent pré-conditions, idempotence, état).\n\nInvoque l'agent PO pour découper une FEAT fonctionnelle en User\nStories structurées (cible `UsGranularityTarget` défaut 3, warn au-delà de\n`UsGranularityWarnAt` défaut 6, hard cap `UsGranularityHardCap` défaut 10)\ndans `workspace/`.\n\n**Usage :**\n- `/us-generate {n}` — où `{n}` est le numéro de la FEAT\n- `/us-generate {n} --replace-pseudo` — migration POC → standard : supprime\n la pseudo-US générée par `/sdd-poc` avant de générer les vraies US\n\n---\n\n## STEP 1 — Valider les arguments\n\nArguments :\n- `{n}` (entier ≥ 1, **obligatoire**)\n- `--allow-large-feat` (optionnel, v7.0.0 P2 #13) — bypass conscient du\n hard cap `UsGranularityHardCap` (default 10). À utiliser pour FEATs\n métier légitimement très larges (≥ 11 flux distincts). Effet : export\n `SDD_ALLOW_LARGE_FEAT=1` avant invocation agent `po`, audit-log dans\n `workspace/.sys/.audit/force-bypass.log`. Préférer split FEAT.\n- `--replace-pseudo` (optionnel, fix C1 audit 2026-08-30) — **migration\n POC → standard** (chemin promis par `/sdd-poc` STEP 8 et\n `feat_to_pseudo_us.py`). Supprime AVANT génération les pseudo-US POC de\n la FEAT (fichiers `workspace/us/{n}-*.md` portant le marqueur frontmatter\n `generated-by: feat_to_pseudo_us.py`), puis la génération PO produit les\n vraies US granulaires. Sans ce flag, une pseudo-US résiduelle cohabite\n avec les vraies US (le PO écrase `{n}-{m}-{Name}.md` par basename, pas\n par `{m}` — la pseudo `{n}-1-{FeatName}.md` survivrait si le `{Name}`\n réel diffère) → WARN collision émis (cf. STEP 2.4 et po.md STEP 2.bis).\n No-op silencieux si aucune pseudo-US détectée (idempotent).\n\nSi `{n}` absent → demander :\n```\nQuel est le numéro de la FEAT à découper ? (ex. : 1 pour workspace/feats/1-Auth.md)\n```\n\nSi non numérique → ERROR :\n```\nERROR: /us-generate — argument invalide\nCAUSE: [INVALID_ARG] \"{argument}\" n'est pas un entier\nFIX: relancer /us-generate {n} avec n entier (ex. /us-generate 1)\n```\n\n### Propagation `--allow-large-feat`\n\n```bash\nif [[ \"$@\" == *--allow-large-feat* ]]; then\n export SDD_ALLOW_LARGE_FEAT=1\n mkdir -p workspace/.sys/.audit\n echo \"$(date -u +%Y-%m-%dT%H:%M:%SZ) /us-generate {n} --allow-large-feat (bypass UsGranularityHardCap)\" \\\n >> workspace/.sys/.audit/force-bypass.log\nfi\n```\n\nL'agent `po` (STEP 5) lit cette env var pour passer outre le hard cap.\n\n---\n\n## STEP 2 — Vérifier la FEAT existe\n\nGlob `workspace/feats/{n}-*.md`.\n- 0 fichier → ERROR :\n ```\n ERROR: /us-generate — FEAT introuvable\n CAUSE: [FEAT_NOT_FOUND] aucun fichier workspace/feats/{n}-*.md\n FIX: créer la FEAT via /feat-generate ou la déposer manuellement\n ```\n- > 1 fichier → ERROR :\n ```\n ERROR: /us-generate — numérotation invalide\n CAUSE: [FEAT_AMBIGUOUS] plusieurs fichiers commencent par {n}- dans workspace/feats/\n FIX: renommer pour qu'un seul fichier ait le préfixe {n}-\n ```\n\n---\n\n## STEP 2.4 — Pseudo-US POC : remplacement ou WARN collision (fix C1, 2026-08-30)\n\nDétecter les pseudo-US POC de la FEAT via le marqueur frontmatter écrit par\n`feat_to_pseudo_us.py` (`generated-by: feat_to_pseudo_us.py`) :\n\n```bash\nPSEUDO_US=$(grep -l \"generated-by: feat_to_pseudo_us.py\" workspace/us/{n}-*.md 2>/dev/null)\n\nif [[ \"$@\" == *--replace-pseudo* ]]; then\n if [ -n \"$PSEUDO_US\" ]; then\n N_PSEUDO=$(echo \"$PSEUDO_US\" | wc -l)\n echo \"$PSEUDO_US\" | xargs rm -f\n echo \"[PO] $N_PSEUDO pseudo-US POC supprimée(s) avant génération (--replace-pseudo). (5%)\"\n else\n echo \"[PO/SKIP] --replace-pseudo : aucune pseudo-US POC détectée (no-op idempotent). (5%)\"\n fi\nelif [ -n \"$PSEUDO_US\" ]; then\n echo \"🟡 [PO/WARN] Pseudo-US POC présente(s) sans --replace-pseudo : $PSEUDO_US\" >&2\n echo \" Elle(s) survivront à la génération si le {Name} réel diffère → doublon d'US {n}-1.\" >&2\n echo \" Recommandé : /us-generate {n} --replace-pseudo (migration POC → standard).\" >&2\nfi\n```\n\n> **Pourquoi ici et pas dans l'agent `po`** : la suppression est une décision\n> d'orchestration (flag CLI) ; l'agent `po` reste strictement exécutif. Il\n> porte néanmoins le même check en filet de sécurité WARN (invocation `po`\n> standalone hors `/us-generate`) — cf. `agents/po.md` STEP 2.bis.\n\n---\n\n## STEP 2.5 — Checkpoint skip (v6.6.4, opt-in)\n\nSi `CheckpointMode: resume` dans Project Config (défaut `off` =\ncomportement v6.6.3 strict) :\n\n```python\nfrom sdd_lib.checkpoint import is_phase_resumable\n\ninputs = [\n f\"workspace/feats/{n}-*.md\", # FEAT parent\n \"workspace/stack/stack.md\", # Project Config + stacks actifs\n]\nresumable, reason = is_phase_resumable(\n feat=n, phase=\"us-generate\", input_paths=resolved_inputs,\n)\nif resumable:\n print(f\"⊘ /us-generate {n}: skipped (checkpoint hit)\")\n # STOP avec succès, ne pas re-déléguer à l'agent PO\n```\n\nSi `CheckpointMode ∈ {off, record}` → skip ce STEP, continuer.\n\nÉmissions possibles : `[CHECKPOINT_HASH_MISMATCH]`, `[CHECKPOINT_INPUT_MISSING]`,\n`[CHECKPOINT_STATE_UNREADABLE]`. Cf. `error-classification.md §1.14`.\n\n---\n\n## STEP 3 — Invoquer l'agent PO\n\nLancer l'agent `po` (défini dans `.claude/agents/po.md`) avec le numéro\n`{n}` en argument. L'agent gère le découpage, la traçabilité et l'écriture\ndes fichiers US dans `workspace/`.\n\nAttendre la fin de l'agent. Relayer sa sortie telle quelle (ligne de succès\nou bloc ERROR 3 lignes).\n\n### STEP 3.0 — Résoudre le sentinel `Parent FEAT hash` (v7.0.0-alpha, 2026-05-22 ; refactor 2026-06-05)\n\nSi l'agent `po` a réussi (US écrites), patcher les sentinels\n`sha256:COMPUTE_REQUIRED` en hash sha256 réel **avant** STEP 3.bis.\n\nL'agent `po` n'a pas le tool `Bash` (cf. po.md frontmatter `tools:\nRead, Write, Edit, Glob, Grep`) et ne peut pas calculer le hash\nlui-même. Il écrit le sentinel littéral, et cette commande le résout\nen post-step déterministe (0 token LLM, ~50 ms).\n\n> **v7.0.0-alpha audit P0-workflow 2026-06-05** — historiquement\n> l'inline `python -c \"...\"` vivait ici. Refactor : extrait vers\n> `sdd_scripts/resolve_us_hash_sentinel.py` (SSoT) + posé comme\n> SubagentStop hook matcher=`po` (defense-in-depth). Le hook ferme\n> le gap où `po` était invoqué standalone (hors `/us-generate`) et\n> laissait le sentinel non résolu → tous les downstream émettaient\n> `[FEAT_HASH_MISMATCH]`. Ce STEP reste le chemin nominal ; le hook\n> est un filet de sécurité (idempotent — no-op si déjà résolu).\n\n**Invocation** (déterministe, 0 token LLM, ~50 ms, cross-platform) :\n\n```bash\npython .sdd/python/sdd_scripts/resolve_us_hash_sentinel.py --feat-number {n}\n```\n\n**Garanties** (préservées vs implémentation inline) :\n- Aucune dépendance externe (`sed`/`python`/Git Bash) — Python stdlib seulement\n- UTF-8 sans BOM (compatible parser frontmatter YAML cross-OS)\n- Line endings préservés (`newline=''` → conserve LF original, pas de CRLF Windows)\n- Idempotent : re-exécution sur US déjà patchées → 0 patch\n\n| Exit | Sens | Action caller |\n|---|---|---|\n| `0` | succès (N US patchées OU rien à faire) | continuer STEP 3.bis |\n| `2` | sentinel persiste après patch (corruption FS) | STOP + ERROR `[PO_HASH_PLACEHOLDER]` |\n| `3` | erreur infra (FEAT file missing, FS perms) | STOP + ERROR `[INFRA_BLOCKED]` |\n\n**Format ERROR (exit 2)** :\n```\nERROR: /us-generate {n} — sentinel hash non résolu\nCAUSE: [PO_HASH_PLACEHOLDER] sha256:COMPUTE_REQUIRED persiste dans {N} fichier(s) US après patch\nFIX: vérifier permissions FS sur workspace/us/, relancer /us-generate {n} (idempotent)\n```\n\n### STEP 3.bis — Checkpoint record (v6.6.4, opt-in)\n\nSi l'agent PO a réussi (US écrites) ET `CheckpointMode ∈ {record, resume}` :\n\n```python\nfrom sdd_lib.checkpoint import record_input_hash\n\nrecord_input_hash(\n run_id=$RUN_ID,\n phase=\"us-generate\",\n input_paths=resolved_inputs, # FEAT + stack.md\n)\n```\n\nErreur silencieuse si state.json absent → WARN, non bloquant.\n\n---\n\n### STEP 3.ter — Auto-ingest FEAT/US dans console.db (depuis 2026-05-21)\n\nSi l'agent PO a réussi (US écrites), invoquer **systématiquement** le script\ndéterministe `ingest_feats_us.py` pour populer correctement les tables\n`feats` et `us` de `workspace/db/console.db` (cf. gap framework\nidentifié 2026-05-21 — auparavant seules les colonnes skeleton `feat_n` +\n`feat-{n}` étaient remplies par les auditors via `ensure_feat_skeleton()`,\nlaissant `name`, `actors_json`, `ac_count`, `sfd_count`, `br_count`,\n`fd_count`, `covers_json`, `status` à null/zéro et brisant l'affichage\nde la console web dashboard).\n\n```bash\npython .sdd/python/sdd_scripts/ingest_feats_us.py 2>&1 | tail -1\n```\n\n| Exit | Sens | Action caller |\n|---|---|---|\n| `0` | Ingest OK | continuer (log 1 ligne `[OK] ingested N FEATs + M US`) |\n| `1` | DB introuvable / corrompue | WARN 1 ligne, continuer (non bloquant) |\n\n**Idempotent** : utilise `ON CONFLICT(feat_n|us_id) DO UPDATE` — re-exécution\nsans effet sur les counts (ré-écrit avec mêmes valeurs).\n\n**Coût** : 0 token LLM, ~50 ms, parse markdown déterministe (regex SFD-N /\nBR-N / AC-N / FD-N / `## Actors` / `Covers:`).\n\n**Non bloquant** : un échec de l'ingest n'invalide pas le succès du PO.\nLes US sur disque restent la SSoT ; le DB n'est qu'un cache projeté pour\nla console web.\n\n---\n\n## STEP 4 — Inventaire des mockups HTML (depuis v4)\n\nGlob `workspace/ui/{n}-*.html` pour détecter les mockups déjà déposés.\n\nGlob `workspace/us/{n}-*.md` pour récupérer les basenames d'US.\n\nCross-check :\n- HTML dont basename matche une US → couvert\n- HTML dont basename ne matche aucune US → orphelin (WARN)\n- US sans HTML → info (frontend possible sans mockup OU backend-only)\n\nÉmettre la liste compactement (1 ligne par US et 1 ligne par orphelin).\n\nSi aucun HTML détecté ET au moins une US a une composante UI attendue,\némettre une info non bloquante invitant à déposer les mockups\n(convention `{n}-{m}-{Name}.html`).\n\n---\n\n## STEP 5 — Confirmation finale\n\nSi l'agent PO réussit, ajouter le récap final :\n```\n✅ FEAT {n}-{FeatName} — planification terminée\n\nUS générées : {U} fichiers dans workspace/us/\nMockups HTML : {H} fichiers dans workspace/ui/ (ou \"aucun\")\nHTML orphelins : {O} (à corriger ou retirer)\nUS sans mockup : {U-H}\n\nProchaine étape :\n - (optionnel) déposer/réviser les mockups HTML (workspace/ui/{n}-{m}-{Name}.html)\n - /dev-run {n} pour matérialiser le code (arch + db + back + front en parallèle)\n - ou /sdd-full {n} pour pipeline complet\n```\n\nSi l'agent échoue, ne rien ajouter (l'ERROR 3 lignes de l'agent suffit).\n\n---\n\n## Règles de cette commande\n\n- Pas de Q/R utilisateur après le STEP 1 (l'agent est autonome)\n- Pas de modification de la FEAT parente\n- Pas de génération de code (réservé à `/dev-backend`, `/dev-frontend`, `/dev-run`)\n- Pas de lecture des mockups HTML ou du stack (réservé aux agents dev-*)", "variables": [ "arguments" ], "notes": "Arguments: ${arguments}", "metadata": { "source": { "provider": "github-codex-prompts", "repository": "https://github.com/zekiriabd/SDD-Pro", "path": ".codex/prompts/us-generate.md", "ref": "d61307fb26d4341b99c51c95629b6c43c5c35451", "url": "https://github.com/zekiriabd/SDD-Pro/blob/d61307fb26d4341b99c51c95629b6c43c5c35451/.codex/prompts/us-generate.md", "key": "zekiriabd/SDD-Pro/.codex/prompts/us-generate.md" } } }

us-generate

About

/us-generate — Découpe une FEAT en User Stories

STEP 1 — Valider les arguments

Propagation `--allow-large-feat`

STEP 2 — Vérifier la FEAT existe

STEP 2.4 — Pseudo-US POC : remplacement ou WARN collision (fix C1, 2026-08-30)

STEP 2.5 — Checkpoint skip (v6.6.4, opt-in)

STEP 3 — Invoquer l'agent PO

STEP 3.0 — Résoudre le sentinel `Parent FEAT hash` (v7.0.0-alpha, 2026-05-22 ; refactor 2026-06-05)

STEP 3.bis — Checkpoint record (v6.6.4, opt-in)

STEP 3.ter — Auto-ingest FEAT/US dans console.db (depuis 2026-05-21)

STEP 4 — Inventaire des mockups HTML (depuis v4)

STEP 5 — Confirmation finale

Règles de cette commande

Install us-generate and it becomes one more candidate the router can pick - when it fits.

Use it

Manifest

Reviews

About

/us-generate — Découpe une FEAT en User Stories

STEP 1 — Valider les arguments

Propagation --allow-large-feat

STEP 2 — Vérifier la FEAT existe

STEP 2.4 — Pseudo-US POC : remplacement ou WARN collision (fix C1, 2026-08-30)

STEP 2.5 — Checkpoint skip (v6.6.4, opt-in)

STEP 3 — Invoquer l'agent PO

STEP 3.0 — Résoudre le sentinel Parent FEAT hash (v7.0.0-alpha, 2026-05-22 ; refactor 2026-06-05)

STEP 3.bis — Checkpoint record (v6.6.4, opt-in)

STEP 3.ter — Auto-ingest FEAT/US dans console.db (depuis 2026-05-21)

STEP 4 — Inventaire des mockups HTML (depuis v4)

STEP 5 — Confirmation finale

Règles de cette commande

Install us-generate and it becomes one more candidate the router can pick - when it fits.

Use it

Manifest

Reviews

Propagation `--allow-large-feat`

STEP 3.0 — Résoudre le sentinel `Parent FEAT hash` (v7.0.0-alpha, 2026-05-22 ; refactor 2026-06-05)