marcioaltoe/write-tasks

Write Tasks

Transformer docs/specs/<slug>/_prd.md (et _techspec.md lorsqu'elle existe) en un graphe de tâches exécutable : un fichier task_NN.md par tâche plus _tasks.md, le manifeste à partir duquel implement-task et le Démon Roundfix planifient. Les artefacts sont le contrat — une session d'agent fraîche doit pouvoir récupérer un fichier de tâche et le construire sans autre contexte que le dossier de spécification.

Planification de niveau léger

Une Tâche avec complexity: low qui n'est pas QA et ne déclare aucun Chemin Gouverné s'exécute sur le niveau léger. L'auteur peut exécuter roundfix spec judge <slug> --stage tasks pour une suggestion de niveau consultative avant que la Pull Request de planification ne soit fusionnée ; la suggestion ne contrôle pas l'envoi.

Préconditions

$ARGUMENTS nomme la spécification. _prd.md doit exister. Si _techspec.md est manquante pour une fonctionnalité avec une surface architecturale réelle, exécutez write-techspec d'abord puis décomposez — la création de l'artefact manquant est la résolution, jamais une raison de s'arrêter pour obtenir la permission. En travail autonome, cela ne nécessite aucune confirmation : diriger le travail autonome autorise toute la chaîne de création pour chaque Spécification déjà dans la file d'attente approuvée, conformément à docs/agents/autonomous-work.md. Demandez l'acceptation uniquement lorsqu'il est explicitement demandé de décomposer sans une spécification technique, puis compensez par une exploration plus approfondie du code avant la décomposition.

Vérification préalable des contraintes du projet

Exécutez cette vérification préalable avant de dériver ou d'approuver une décomposition :

1. Classez la Spécification. Une Spécification située sous le répertoire d'archive résolu (docs/history/specs/ pour la racine docs/specs intégrée, ou <spec-root>/_archived/ pour une racine externe ou non par défaut), ou une spécification dont il est prouvé qu'elle a été achevée avant l'application de ce contrat, est une Spécification héritée achevée ou archivée. Laissez chaque artefact hérité identique en octets : ne pas remblayer, reformater, régénérer ou réécrire.
2. Pour chaque Spécification active, non archivée et pas encore achevée, exigez que la PRD et chaque Spécification Technique présente contiennent des sections Project Constraints complètes. Chaque section doit enregistrer Identifier strategy, Authentication and HTTP, Active ADR obligations, et Tooling authority comme applicable ou non applicable avec une raison, et chaque ligne doit citer son chemin source docs/agents/ opératoire.
3. Si l'un des artefacts actifs est absent ou incomplet, refusez de créer ou de mettre à jour _tasks.md ou tout fichier de Tâche. Nommez chaque ligne, raison ou chemin source manquant et renvoyez la Spécification via la compétence d'auteur propriétaire.
4. Inspectez les tranches proposées pour toute création, édition, renommage, déplacement ou suppression de configuration d'outillage de dépôt, scripts, fichiers d'ignorance, déclarations de plugin ou pins de version. Un tel travail n'est autorisé que lorsque la PRD et la Spécification Technique présente enregistrent l'autorisation du mainteneur et les fichiers exacts et délimités relatifs au dépôt qu'elle couvre. Une demande d'implémentation générique, une approbation de configuration ou une affectation de Tâche ne constitue pas une autorisation. Sans l'autorisation et les fichiers délimités, refusez la décomposition.
5. Résolvez l'enregistrement opératoire à <spec-root>/<slug>/_authorization.md pour chaque tranche d'outillage. Un enregistrement absent, un enregistrement proposed, ou un enregistrement sans date d'octroi n'autorise rien ; refusez la décomposition jusqu'à ce qu'un octroi opératoire existe. Un nouvel octroi ou un octroi élargi doit atterrir dans l'ascendance cible avant la livraison de squash consommatrice, donc l'octroi ou l'amendement ne peut pas être intégré dans le changement qu'il autorise.
6. Copiez la liste des fichiers délimités dans la portée et les critères d'acceptation de chaque Tâche d'outillage autorisée. La Tâche ne peut modifier que ces chemins plus son propre fichier de Tâche ; divisez tout travail nécessitant une limite différente.
7. La liste operations de l'enregistrement doit autoriser chaque opération de livraison que la Spécification utilisera. roundfix deliver start refuse un enregistrement auquel il manque implement, commit, push, pull_request ou merge ; une Spécification sans Chemin Gouverné enregistre paths: [].
8. Un commit de Tâche conserve un fichier exécutable non suivi uniquement lorsque son chemin exact est répertorié sous executables dans l'enregistrement d'autorisation de la Spécification ; tout autre exécutable non suivi est refusé. La liste doit se trouver sur la cible de livraison avant que l'Exécution ne la lise. Les commits de Rapport QA et de Lot ne conservent jamais d'exécutable non suivi. Un dépôt avec core.fileMode false enregistre le fichier comme 100644.

Les dépendances restent la propriété exclusive de _tasks.md ; l'état de la Tâche reste la propriété exclusive de chaque fichier de Tâche. La vérification préalable ne déplace jamais l'une ou l'autre responsabilité.

Le code pour un autre système d'exploitation est vérifié en compilant son code non test pour ce système, avec un exemple tel que GOOS=windows go build -buildvcs=false ./<package>, et jamais avec go vet, qui compile également les tests écrits pour l'hôte.

Règles de propriété (ce qui vit où, et pourquoi)

• Les dépendances vivent uniquement dans le graphe _tasks.md. Jamais dans les fichiers de tâches. Deux copies d'une arête, c'est ainsi que les graphes dérivent.
• L'état vit uniquement dans le frontmatter de chaque fichier de tâche. _tasks.md possède la topologie, pas la progression — les planificateurs relisent les fichiers de tâches pour l'état.
• Le Type de Tâche est obligatoire dans chaque fichier de tâche. Utilisez exactement l'un de backend, frontend, data, infra, docs, test, chore, ou qa. Réservez qa pour la porte terminale unique créée et nommée par le champ qa: du manifeste. La Commande d'Implémentation consomme cette valeur pour le routage et rejette les valeurs manquantes ou inconnues ; ne laissez jamais d'espace réservé ou n'inférez pas le type plus tard.
• Références de contenu, jamais de doublons. Les fichiers de tâches pointent vers des sections PRD/Spécification Technique par leur nom ; une tâche qui réitère la spécification devient obsolète dès la première modification de la spécification. Liez une source adoptée à son chemin post-adoption dans la Spécification propriétaire avec une destination relative à ce fichier de tâche, jamais à son chemin de provenance pré-adoption. Une Spécification secondaire lie la copie du propriétaire principal et n'adopte rien. L'archive du propriétaire effectue un Relien d'Archive : elle promeut cette copie vers docs/references/ et réécrit les liens de la Spécification secondaire, de sorte que la source conserve un propriétaire et que la Spécification secondaire n'ait besoin d'aucune copie (ADR-0260, ADR-0083).
• Les entrées de contexte sont des chemins étiquetés. Ajoutez ## Context uniquement lorsque la Tâche a besoin d'instructions spécifiques ou de chemins d'interface au-delà de l'ensemble de spécifications standard. Utilisez des puces en forme de - instruction: <path>, - interface: <path>, - creates: <path>, ou - deletes: <path>. Les chemins doivent être propres, relatifs au dépôt et uniques ; une Tâche peut déclarer au plus 50 entrées uniques. Le Démon réserve ces chemins avant de remplir le Bundle de Contexte de Spécification de 200 chemins avec les fichiers modifiés antérieurement.
• Les modifications déclarées et les chemins gouvernés sont explicites. Chaque chemin qu'une Tâche modifie est déclaré sous interface: ou creates: ; chaque chemin qu'elle supprime est déclaré uniquement sous deletes:, jamais interface: et jamais instruction:. Une Tâche qui lit un fichier avant de le supprimer le liste toujours une fois, sous deletes:. Une suppression est ignorée par les vérifications de référence non résolue et compte dans la portée, les audits de collision de Chemin Gouverné et de Vague. Le Démon refuse le règlement avant la Vérification lorsqu'une suppression déclarée existe toujours, avec deletes: <path> still exists. Un chemin instruction: est en lecture seule et ne fait jamais entrer deux Tâches en collision. Chaque Tâche qui modifie une commande déclare le seul fichier de commande qu'elle modifie : .agents/skills/roundfix/references/<command>.md avec son miroir, et docs/user-guide/commands/<command>.md, jamais le SKILL.md ou commands.md de la compétence, à moins qu'elle ne modifie le fichier d'entrée lui-même. Deux Tâches qui déclarent le même fichier ne peuvent pas partager une Vague, donc les Tâches qui modifient différentes commandes peuvent s'exécuter ensemble et les Tâches qui modifient la même commande ont besoin d'une arête entre elles. Un Chemin Gouverné déclaré ou lu par Vérification doit apparaître dans les paths: de _authorization.md de la Spécification et dans les deux lignes bounded files: , ou la création est refusée avec SC-TOOLING-UNDECLARED. Une Tâche nommant une surface CLI se nomme elle-même ou via une Tâche dont elle dépend ; sinon, elle est signalée avec SC-CLI-UNDOCUMENTED.

Le Démon enregistre un chemin qu'une Tâche a modifié sans le déclarer sous ## Recorded paths lors du commit. L'audit de portée QA compte ce chemin enregistré comme déclaré, et l'enregistrement divulgue un changement et ne réserve rien. Déclarer chaque chemin prévisible reste la règle.

Un helper de test, un faux, un fixture ou un golden que deux Tâches peuvent chacune modifier est un chemin prévisible. Déclarez-le sous interface: dans chaque Tâche susceptible de le modifier, afin que roundfix spec check --strict signale SC-WAVE-COLLISION pendant que la Spécification est encore créée et que l'arête needs qu'elle nomme exécute ces Tâches en série. L'enregistrement ne réserve rien, et une Tâche achevée n'entre jamais en collision : le commit de règlement d'une Tâche est une preuve de collision uniquement tant que l'une des deux Tâches n'est pas achevée, par exemple une Tâche rouverte à pending, donc deux Tâches d'une même Vague qui s'achèvent toutes deux après avoir modifié le même fichier non déclaré ne sont jamais refusées. Déclarer le fichier est la seule protection.

Compétences Tâches pour les Surfaces de Comportement Modifiées

Lisez la Carte de Couverture des Compétences du dépôt à docs/references/skill-coverage.json lorsqu'elle existe. Pour chaque Surface de Comportement couverte dont une Tâche non QA déclare la source sous interface:, creates: ou deletes:, incluez une compétence Tâche non QA qui déclare l'un de ses fichiers de compétence de couverture sous interface: ou creates:. SC-SKILLS-UNTASKED signale une surface sans une telle Tâche.

Lorsque le changement ne nécessite pas de texte de compétence, enregistrez - unchanged: <surface id> — <reason> dans la section optionnelle ## Skills de la PRD et incluez une Tâche non QA déclarant la carte sous interface: oucreates: pour enregistrer la Revue de Couverture. L'entrée seule n'excuse pas la surface. SC-SKILLS-MALFORMED signale une entrée d'une autre forme, une surface inconnue ou une raison vide. Les deux règles commencent au commit qui a ajouté la carte ; les dépôts sans celle-ci les ignorent.

Une Tâche non QA déclarant une page Markdown sous docs/user-guide/ sous interface:, creates: ou deletes: doit également déclarer docs/references/behavior-surfaces.json sous interface: ou creates: et nommer l'étape -record-skill-coverage dans une exigence. Une autre Tâche ne peut pas la couvrir : le règlement de la Tâche de guide vérifie son empreinte. Les Limites de _authorization.md de la Spécification ne doivent jamais interdire cet enregistrement. SC-SURFACE-RECORD-UNTASKED signale l'un ou l'autre écart à partir de l'étape des Tâches, sans horizon, dans les dépôts qui possèdent l'enregistrement.

Règles de décomposition

Le code pour un autre système d'exploitation est vérifié en compilant son code non test pour ce système, avec un exemple tel que GOOS=windows go build -buildvcs=false ./<package>, et jamais avec go vet, qui compile également les tests écrits pour l'hôte.

• Tranches verticales. Chaque tâche livre un chemin étroit mais complet à travers chaque couche qu'elle touche, démontrable ou vérifiable par elle-même — une balle traçante, pas une couche (« tous les schémas » est une mauvaise tâche ; « les importations expirées réessayent et affichent leur statut » en est une bonne).

• Préfactorisation d'abord. Lorsqu'une tranche a besoin que le terrain soit préparé, faites-en sa propre tâche de tête : facilitez le changement, puis faites le changement facile.

• Caractérisez les surfaces externes pendant la création. Lorsqu'une Spécification traverse une surface externe telle qu'un adaptateur, un contrat ou une base de données, créez une Tâche de caractérisation qui enregistre ce que la véritable limite fait, et non ce qu'un faux fait, afin qu'une prémisse non prise en charge échoue pendant que la Spécification est encore en cours de création plutôt qu'à la porte QA.

  Listez-la dans needs, pas simplement plus tôt dans le fichier. Chaque Tâche dont la prémisse dépend de la caractérisation nomme cette Tâche dans son entrée needs dans _tasks.md. Les vagues d'exécution sont construites à partir des seuls needs, donc une Tâche qui apparaît simplement plus tard dans le manifeste peut s'exécuter dans la même vague que la caractérisation dont elle dépend, et lire une limite que personne n'a encore caractérisée. L'ordre des fichiers n'est pas une dépendance.

  Une Tâche de caractérisation touche une véritable limite, donc liez-la explicitement. Son fichier indique la cible qu'elle atteindra, par son nom. Elle lit plutôt qu'elle n'écrit, ou s'exécute contre une instance isolée que la Tâche elle-même crée et supprime ; elle ne caractérise jamais par défaut contre un état partagé ou de production. Elle utilise des identifiants limités à cette cible et pas plus larges, honore l'annulation, et nettoie ce qu'elle a créé même en cas d'échec. Une caractérisation qui doit écrire nécessite que cette écriture soit autorisée dans la Tâche comme toute autre action irréversible — enregistrer ce qu'une limite fait n'est pas une autorité pour la modifier.

  Sa Vérification affirme l'enregistrement, jamais la limite. Le Démon exécute les commandes ## Verification déclarées d'une Tâche textuellement via le shell, une fois contre l'arbre inchangé avant que le tour de l'Agent n'existe et à nouveau lors du règlement. Rien dans ce chemin ne lit les limites ci-dessus : elles contraignent l'Agent, et le Démon n'est pas l'Agent. Une Vérification qui atteint la véritable surface l'atteint donc sans limites, deux fois, y compris avant que tout travail n'ait été effectué. Vérifiez la caractérisation que la Tâche a enregistrée — sa forme, sa présence, ce que les Tâches en aval liront — et laissez l'appel à la limite dans le tour de l'Agent, où s'appliquent la cible déclarée de la Tâche, l'isolation, les identifiants et l'autorisation d'écriture. C'est la règle d'herméticité que ces commandes portent déjà, énoncée là où la tentation de la briser est la plus forte : une surface externe active est un état ambiant, et une commande qui en dépend n'est pas hermétique.

• Dimensionnée pour une session fraîche. Une tâche qu'un agent peut accomplir en une seule séance avec un contexte frais. Plus d'environ 7 sous-tâches ou fichiers signifie qu'il faut la diviser.

• Tests intégrés, jamais séparés. Les critères d'acceptation de chaque tâche incluent ses propres tests ; une tâche de fin « écrire les tests » signifie que les tâches antérieures n'ont jamais été terminées.

• Implémentable indépendamment. Une fois ses needs achevés, une tâche ne doit nécessiter aucun autre travail non terminé — c'est ce qui permet l'exécution parallèle sur plusieurs arbres de travail plus tard.

• La vérification doit être hermétique, portable, prouvant l'effet, et appartenant au Démon. Les commandes ## Verification de chaque tâche doivent pouvoir être satisfaites dans un arbre de travail frais en utilisant uniquement des entrées et commandes standard, sans dépendre de l'état ambiant (variables d'environnement non déclarées, fichiers modifiés précédemment, exécutions extérieures). Elles doivent prouver que l'effet déclaré a eu lieu : présence de fichier, sortie de build, échec de test attendu. Elles ne doivent pas exiger d'interaction humaine (pas de sélecteur interactif, pas de confirmation 'y'). Et elles sont possédées par le Démon — l'Agent peut les écrire, mais le Démon les exécute, donc elles ne peuvent pas utiliser des capacités propres à l'Agent.