Concepts fondamentaux

AWR conserve les faits de travail d'un projet en dehors de toute conversation d'agent individuelle, de sorte que le travail survit aux pertes de contexte, aux changements d'agent et aux redémarrages. Cet article explique les cinq idées derrière ce modèle ; les commandes du Démarrage rapide et les routines du Flux de travail quotidien se lisent ensuite naturellement.

Le principe central : vos fichiers sources (registres, plans) font autorité, et tout ce que le moteur stocke — sessions, réservations, preuves — est une projection vérifiable de ces faits. AWR n'invente jamais une intention manquante, et ne laisse jamais une transcription de conversation se substituer à un fait enregistré.

Les faits du projet : le registre source

Le registre source d'AWR est un petit contrat de travail que vous conservez dans des fichiers de projet ordinaires : un registre YAML tel que work-ledger.yaml, ou un registre Markdown existant (*-ledger.md) qui reste en lecture seule à travers AWR et est édité dans son fichier d'origine. Un registre enregistre deux sortes de faits :

Objectifs — ce que le projet cherche à accomplir, avec des critères de succès. Les objectifs peuvent être draft, candidate ou needs_confirmation en cas d'incertitude, et active ou confirmed lorsqu'ils sont étayés par du matériel source ou une instruction de l'utilisateur. AWR vérifie la déclaration ; il ne certifie pas que l'objectif correspond à ce qu'un humain voulait dire.
Éléments de travail — les tâches, décrites ci-dessous.

Un registre minimal ressemble à ceci :

goals:
  - id: search
    title: Let readers find documents
    status: active
    summary: The user requested search in the existing portal; see README.md.
    success_criteria: [Readers find a requested document]
work_items:
  - id: search-api
    title: Add document search
    status: ready
    goal: search
    acceptance: [A matching query returns the requested document]
    next_action: Implement the search handler using the current document index

Vous placez ces fichiers sous la gestion d'AWR avec init. Rien n'est écrit tant que vous n'acceptez pas l'aperçu :

awr --project /absolute/project init
awr --project /absolute/project init --accept
awr --project /absolute/project intake inspect --json

L'init n'écrase jamais de fichiers existants, et l'inspection ne rafraîchit qu'un cache de projection reconstructible — jamais vos objectifs, vos fichiers de tâches ou votre état d'exécution.

Tâches : les éléments de travail

Un élément de travail est une tâche dans le registre. Ses champs clés sont ceux qu'AWR peut réellement vérifier :

acceptance — les critères d'achèvement : ce qui doit être observablement vrai quand la tâche est terminée. Un rapport d'achèvement est ensuite vérifié contre ces critères exacts.
next_action — l'étape suivante persistée, et le champ le plus précieux pour la reprise : il permet à une session fraîche de continuer sans relire l'historique.
Champs de support : summary, goal, kind, paths, tags, priority, depends_on, owner et milestone.

Vous créez une tâche à partir d'un brouillon JSON qui n'énonce que des faits explicitement connus :

awr work create --input draft.json

La création produit toujours un brouillon. Les objectifs ou faits requis manquants restent visibles, et un brouillon ne donne aucune permission d'exécuter ou d'achever quoi que ce soit ; l'appliquer est une étape séparée et explicite.

AWR rapporte aussi des états d'organisation au niveau du projet tels que not_initialized, needs_organization, ready, blocked, awaiting_verification, completed et closed_without_completion. Deux comptent le plus au quotidien : ready signifie qu'au moins une tâche a un objectif déclaré dans la source, des critères d'acceptation, une action suivante et des prérequis résolus ; awaiting_verification signifie que le registre indique des tâches terminées mais que leurs rapports d'acceptation n'ont pas tous encore été vérifiés.

Points de contrôle et sessions

Une session est l'attachement de travail d'un agent à un élément de travail. Un point de contrôle est l'enregistrement durable de l'état de cette session : l'action suivante persistée, les boucles ouvertes, et le delta réel des événements AWR et des sources — pas une copie de la conversation.

Quand une session client démarre ou reprend après une compaction, AWR renvoie un contexte de reprise construit à partir du point de contrôle. Quand le tour s'arrête ou se termine, l'action suivante modifiée et les boucles ouvertes sont enregistrées avant de pouvoir être perdues :

awr client progress --client codex --external-session CLIENT_ID \
  --next-action "Apply the reviewer corrections" --open-loop "Independent review remains"

Les événements en double avec un travail inchangé réutilisent leur point de contrôle ; un tour continué avec une progression modifiée en crée un nouveau. Une limite honnête : l'adaptateur de hooks natifs qui automatise cela n'est actuellement installé que pour Codex. Les autres hôtes utilisent le lieur L0 (--client generic), qui attache une conversation hôte à une session AWR active sans installer de hooks. L'adaptateur ne lit jamais le corps des transcriptions — il enregistre ce que vous lui dites, pas ce qu'un modèle a dit.

Réservations et passation

Une réservation est le verrou explicite qu'une session détient avant d'exécuter une tâche. AWR exige que vous acquériez la réservation de session avant l'exécution, et l'achèvement la revérifie — c'est ainsi que deux agents évitent de travailler silencieusement sur la même tâche.

Une passation transfère le travail d'une session ou d'un client vers un successeur. Vous reprenez une session explicitement, avec des contrôles de révision et une transition de successeur :

awr session resume --from-session AWR_SESSION_ID --agent successor \
  --provider generic --model selected-model --no-claim --expected-revision REVISION

Ou liez une nouvelle conversation client à sa prédécesseure :

awr client bind --client generic --external-session NEW_CLIENT_ID \
  --work INTAKE-001 --from-session AWR_PREDECESSOR_ID

La passation déplace des faits enregistrés — état du registre, points de contrôle, historique d'exécution — pas la mémoire de processus. Les hooks d'arrêt sont consultatifs : ils ne libèrent jamais de réservations et ne terminent jamais de sessions, ce qui reste votre responsabilité explicite lors de la passation.

Livraison et acceptation

L'acceptation est le domaine où AWR est délibérément strict. Une tâche n'est pas terminée parce que quelqu'un a écrit status: completed dans un registre. Elle est terminée quand un rapport d'achèvement enregistré est vérifié contre les critères d'acceptation actuels du registre.

Un rapport d'achèvement enregistre la commande réellement exécutée, le périmètre réellement vérifié, l'heure, et des contrôles nommés — chacun correspondant à un critère d'acceptation exact et décrivant le résultat observé, pas le résultat visé :

{
  "version": 1,
  "work_item": "WORK",
  "source_sha": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "command": "the command or verification procedure actually executed",
  "scope": ["the scope actually verified"],
  "verified_at": 1,
  "checks": [{
    "name": "independent check name",
    "passed": true,
    "details": "the observed outcome, not an intended result",
    "criteria": ["an exact current source acceptance criterion"]
  }]
}

Avant d'achever, vous effectuez le précontrôle du rapport :

awr work prepare-completion WORK --report report.json --evidence-key KEY \
  --source-sha FULL_SHA --level locally_verified

Le précontrôle n'exécute aucune commande, n'enregistre aucune preuve et n'achève aucune tâche — il lit les octets du rapport et renvoie les arguments de preuve et le mapping d'acceptation. L'achèvement lui-même est une écriture séparée qui revérifie les réservations, les dépendances, la fraîcheur des sources et les octets du rapport ; modifier un rapport après le précontrôle invalide son empreinte. L'achèvement déclaré dans la source seul ne fournit jamais un reçu vérifié, et source_completed et verified_completed restent des compteurs distincts dans les rapports d'état.

Une tâche, de bout en bout

Relions le tout avec la tâche de recherche du registre ci-dessus :

Faits. Vous exécutez awr --project /absolute/project init --accept ; le registre avec l'objectif search et l'élément de travail search-api devient faisant autorité.
Tâche. L'élément de travail porte des critères d'acceptation et une action suivante, donc le projet rapporte ready.
Session et réservation. Vous préparez le travail à partir d'un instantané, puis acquérez la réservation de session avant de toucher au code :

   awr work prepare search-api --session AWR_SESSION_ID --source-sha FULL_SHA

Point de contrôle. Pendant que vous travaillez, vous enregistrez la progression avec awr client progress, de sorte que l'action suivante et les boucles ouvertes survivent à un crash ou à une compaction.
Passation (si nécessaire). Un successeur reprend avec awr session resume --from-session … et obtient les mêmes faits, sans qu'aucun historique de chat ne soit rejoué.
Livraison. Vous écrivez un rapport dont les contrôles correspondent au critère d'acceptation exact, vous le précontrôlez avec awr work prepare-completion, et ce n'est qu'ensuite que vous enregistrez l'achèvement. L'état montre désormais la tâche comme vérifiée contre le SHA source, et non simplement marquée terminée.

Pour aller plus loin

Démarrage rapide — exécutez ces concepts pour la première fois.
Flux de travail quotidien — la boucle de routine : préparer, réserver, enregistrer un point de contrôle et achever.