ultragoal

<Use_When>

• L'utilisateur souhaite un moyen durable et natif au dépôt de suivre un ultragoal à travers plusieurs sessions Claude ou arbres de travail
• Le travail est suffisamment volumineux pour justifier plusieurs « stories » ordonnées avec des compteurs de tentatives et des preuves par story
• L'utilisateur souhaite que la complétion finale soit conditionnée par ai-slop-cleaner + vérification + $code-review
• L'utilisateur souhaite que la directive Claude /goal active soit coordonnée avec le registre afin qu'un redémarrage de session ne perde pas la progression </Use_When>

<Do_Not_Use_When>

• La tâche est une petite modification unique — utilisez plutôt la délégation directe ou ralph
• L'utilisateur souhaite que l'assistant invoque littéralement /goal depuis le shell — ce n'est pas possible ; omc ultragoal écrit uniquement des artefacts et imprime un texte de transfert
• L'utilisateur souhaite un artefact de planification uniquement, sans boucle d'exécution — utilisez plutôt plan </Do_Not_Use_When>

<Why_This_Exists> Le /goal de Claude Code est un hook Stop limité à la session : il empêche la session de s'arrêter tant qu'une condition n'est pas remplie, et se désactive automatiquement en cas de succès. C'est une excellente primitive d'exécution pour une seule session, mais elle perd l'état entre les sessions et n'impose pas en soi de porte de révision finale. omc ultragoal ajoute un plan durable, un registre et une couche de contrôle pour qu'une initiative longue et multi-étapes puisse survivre aux redémarrages de session, aux nouveaux arbres de travail et aux itérations de révision, tout en tirant parti de /goal de Claude pour maintenir l'agent actif concentré. </Why_This_Exists>

<How_To_Use>

1. Créer un plan à partir d'un brief :

   omc ultragoal create-goals --brief-file plan.md
   

   Ou avec des stories explicites :

   omc ultragoal create-goals --brief "livrer la migration" \
     --goal "Schema::Ajouter les nouvelles colonnes" \
     --goal "Backfill::Remplir les lignes par lots" \
     --goal "Cutover::Supprimer les anciennes colonnes et basculer les lectures"
   

   Le mode par défaut est aggregate (un seul /goal Claude couvre l'ensemble). Passez --claude-goal-mode per-story si vous souhaitez que chaque story ait son propre /goal.

   Espaces de travail multi-dépôts / sessions parallèles : lorsque plusieurs sessions Claude dans le même espace de travail doivent exécuter /ultragoal simultanément, passez soit --plan-id <id-stable> soit --auto-plan-id pour que le plan soit écrit dans .omc/ultragoal/plans/{planId}/ au lieu du chemin de plan unique partagé. Sans ce drapeau, deux sessions créant des goals se chevaucheraient. --auto-plan-id dérive {epochMs}-{slug} du titre du brief. Ensuite, transmettez le même --plan-id <id> à chaque sous-commande ultérieure de cette session. Utilisez omc ultragoal list-plans pour énumérer les planIds disponibles si nécessaire.

2. Démarrer (ou reprendre) la story suivante :

   omc ultragoal complete-goals [<goal-id>]
   

   Sans identifiant de goal, cette commande conserve le comportement par défaut de reprendre la story active ou de démarrer la première story en attente. Avec un identifiant de goal, OMC cible exactement cette story éligible nommée (une story en attente peut être démarrée dans le désordre) ; elle ne passe jamais à une autre story. Une story active différente, un identifiant inconnu, une story terminée ou bloquée par la révision, ou une story échouée sans --retry-failed est rejetée sans modification de l'état. Une story nommée en cours est reprise sans changer son nombre de tentatives. Ceci imprime un texte de transfert destiné au modèle. L'agent Claude actif doit le lire et :

   • Définir le /goal Claude natif pour cette session — dans Claude Code autonome, ni le shell ni l'agent ne peuvent le faire, demandez donc à l'utilisateur de taper /goal <objectif agrégé> et d'attendre. --claude-goal-json (ci-dessous) ne fait que rapprocher le registre et ne satisfait pas la garde PreToolUse /goal, qui bloque les appels d'outil jusqu'à ce qu'elle observe un /goal actif.
   • Travailler la story.
   • Lorsque la story est terminée (et pour la story finale, après la porte de qualité complète), partager un instantané de l'état actif du /goal et appeler checkpoint.

3. Enregistrer un checkpoint pour une story :

   omc ultragoal checkpoint --goal-id G001-... --status complete \
     --evidence "tests/files/Preuve PR" \
     --claude-goal-json '{"goal":{"objective":"...","status":"active"}}'
   

   Pour la story finale, passez également --quality-gate-json contenant les preuves aiSlopCleaner, verification et codeReview (toutes propres).

4. Si la révision finale n'est pas propre, NE marquez PAS comme terminée. Enregistrez les blocages :

   omc ultragoal record-review-blockers --goal-id G00X-... \
     --title "Résoudre les blocages de la révision de code finale" \
     --objective "Corriger les problèmes de révision trouvés et relancer les portes finales" \
     --evidence "<les résultats de la révision>" \
     --claude-goal-json '{"goal":{"objective":"...","status":"active"}}'
   

   Ceci ajoute une nouvelle story de blocage et maintient le /goal Claude actif.

5. Inspecter l'état à tout moment :

   omc ultragoal status
   

</How_To_Use>

<Important_Limitations>

• Le shell ne peut pas invoquer ni modifier l'état de /goal de Claude Code. omc ultragoal ne fait que persister des artefacts durables et imprimer des instructions que l'agent Claude actif lit et exécute dans la session.
• Les instantanés passés via --claude-goal-json sont des preuves fournies par le modèle de l'état actif de /goal ; OMC les valide pour leur cohérence textuelle avec l'objectif attendu du plan et l'événement du registre, mais il ne peut pas observer indépendamment l'état de /goal de Claude. Ils ne satisfont pas la garde PreToolUse /goal, qui nécessite un /goal actif réel — un instantané injecté par l'hôte ou le /goal natif défini par l'utilisateur dans la session.
• Si la commande slash /goal de Claude est renommée ou restructurée, seul le libellé du transfert doit changer ; la logique de rapprochement est indépendante du nom. </Important_Limitations>

Mises en garde pour les sessions parallèles

• Point d'ancrage pour espace de travail multi-dépôts : placez un marqueur .omc-workspace dans le répertoire parent afin que plusieurs sessions dans des sous-dépôts partagent un seul .omc/. Ordre de résolution : OMC_STATE_DIR > .omc-workspace > git > cwd. Voir docs/REFERENCE.md.
• Source de l'identifiant de session : La variable d'environnement OMC_SESSION_ID l'emporte dans les contextes CLI ; les données payload.data.session_id l'emportent dans les contextes de hook.
• Identifiant de plan (le cas échéant) : Deux exécutions dans le même espace de travail entreront en conflit sur les artefacts de plan partagés. Utilisez des identifiants de session distincts (le session_id du payload du hook est déjà isolé par session Claude Code), ou passez --plan-id pour que les exécutions ultragoal parallèles aient des registres séparés.
• Verdict pour le parallélisme : pris en charge (chaque session écrit son propre état limité à la session).