Changement (Brownfield)

Modification (Brownfield)

Effectuez une modification délimitée et révisable sur une spécification et une base de code existantes, sans rédiger de nouveau PRD. Une modification produit une proposition plus exactement un lot de quatre documents ; après validation QA, les différences confirmées sont réintégrées dans la spécification et la proposition est archivée. Cette compétence est conçue pour être d'abord guidée par des instructions : chaque étape dispose d'un recours manuel et les scripts inclus sont des aides optionnelles.

Position dans le pipeline : spec-generator -> modification -> task-decomposition -> plan-linter (Porte 1) -> review (Porte 2) -> dev -> qa -> converge -> archive.

spécification existante + modification délimitée
  -> .specs/change-context/standards.md        (standards_extract.py ; contraintes implicites)
  -> .specs/changes/<id-modification>/proposal.md    (cycle de vie : proposée -> appliquée -> archivée)
  -> tasks/<id-modification>/01..04                  (un contrat, un lot)
  -> Porte 1 plan-linter -> Porte 2 review -> dev <-> qa -> converge -> proposition archivée

Quand l'utiliser

• Une spécification ou une base de code livrée a besoin d'une modification incrémentale : une correction de bug, une petite fonctionnalité, un ajustement de comportement, un ajustement NFR délimité.
• La modification peut réutiliser une ancre #sec-* existante et respecte le budget de différence micro/standard.
• Vous souhaitez le cycle proposition -> application -> archivage tout en respectant le protocole de tâches en quatre documents de ce dépôt et les rôles de propriétaire unique par fichier.

Quand ne pas l'utiliser

• Le travail est greenfield, ou aucune spécification amont n'existe encore : utilisez prd-generator, puis spec-generator, puis task-decomposition.
• La modification nécessite une nouvelle décision d'architecture, une nouvelle limite de composant, une nouvelle contrainte transversale, ou une toute nouvelle section de spécification (une nouvelle ancre #sec-*) : montez à spec-generator au lieu de la faire passer par une modification.
• Vous avez uniquement besoin de découper une spécification approuvée en tâches : utilisez task-decomposition.
• Vous avez uniquement besoin d'auditer des lots ou des propositions existants : utilisez plan-linter.
• La tâche est déjà planifiée et attend la mise en œuvre/vérification : utilisez dev / qa.

Entrées

• La spécification de base : .specs/02-tech-spec.md (et ses parties modulaires) par défaut.
• L'exigence pour la modification délimitée, rédigée par le demandeur en langage naturel.
• Le rapport des conventions du dépôt généré à l'étape 1.
• Optionnel: le lot de tâches existant à partir duquel la modification continue, et les ADR pertinents.

Sorties

Artéfact	Propriétaire après échafaudage	Objectif
.specs/change-context/standards.md	Outillage	Standards déterministes du dépôt et contraintes implicites (généré, jamais modifié à la main).
.specs/changes/<id-modification>/proposal.md	Planificateur	Proposition de modification délimitée : motivation, diff incrémental, zone d'impact, invariants/NFR, restauration, vérification.
.specs/changes/<id-modification>/convergence.md	Outillage de convergence	Rédigé après validation QA ; enregistre ce qui a été intégré dans la spécification.
tasks/<id-modification>/01-contrat.md ... 04-processus.md	Planificateur / Dev / QA / outillage	Exactement un lot de quatre documents, réutilisant les modèles de décomposition des tâches.

La proposition n'est pas un PRD et n'est pas une spécification de remplacement. C'est un delta qui nomme les ancres existantes qu'elle modifie. Cycle de vie complet et règles de dimensionnement : references/brownfield-protocol.md.

Flux de travail

1. Extraire les standards du dépôt (une fois par modification de configuration) :

   python .agents/skills/change/scripts/standards_extract.py --repo-root . --json
   python .agents/skills/change/scripts/standards_extract.py --repo-root . --check
   

   Lisez .specs/change-context/standards.md avant de planifier. Sa section « Contraintes implicites » est contraignante : utilisez uniquement les commandes qu'elle atteste, respectez la structure de test déclarée, les socles d'exécution et les ancres existantes. Le code de sortie 1 de --check signifie que le rapport est obsolète ; régénérez-le avant de planifier. Ne modifiez jamais le rapport à la main.

2. Échafauder la proposition et un lot de tâches (la seule étape qui écrit des fichiers) :

   python .agents/skills/change/scripts/scaffold_change.py \
     --change-id CHG-001-limiter-connexion \
     --title "Limiter les tentatives de connexion" \
     --anchor "#sec-auth-tokens" \
     --kind modifier \
     --size-class micro --estimated-lines 40 \
     --touch-files "modify:src/auth/rate_limit.py" \
     --repo-root .
   

   L'échafaudeur valide les ancres par rapport à la spécification de base, calcule base_spec_sha256, et délègue à task-decomposition (scaffold_task.py) ou émet un lot minimal en ligne si absent. Utilisez --dry-run pour prévisualiser et --force pour écraser les exécutions jetables.

3. Le planificateur remplit la proposition et le contrat. Remplacez les guides dans la proposition (motivation, blocs [CHG-<n>], chemins, invariants/NFR, restauration, vérification) et les placeholders du contrat (module, adherence_adrs, dod, cas limites, prose des invariants). N'inventez pas de chemins ou d'ancres. Laissez les formulaires de rôle 02/03 vides ; laissez le status: proposée dans la proposition.

4. Porte 1, puis Porte 2. Exécutez la Porte 1 déterministe, puis la revue sémantique indépendante :

   # Exécutez depuis la racine du dépôt. L'aide de la Porte 1 nécessite que la compétence plan-linter soit installée.
   python .agents/skills/plan-linter/scripts/plan_linter.py --tasks-dir ./tasks --repo-root . --spec .specs/02-tech-spec.md --changes-dir .specs/changes
   python .agents/skills/change/scripts/lint_change.py --change-id CHG-001-limiter-connexion --repo-root .
   

   La Porte 1 doit passer avant la mise en œuvre ; la Porte 2 ne doit pas signaler BLOQUÉ ou DEMANDE DES MODIFICATIONS.

5. Mettre en œuvre et vérifier. Exécutez dev (uniquement les touch_files déclarés, remplissez 02, transférez) et qa (tests indépendants sous tests/acceptance/, remplissez 03, un verdict). La proposition passe à appliquée une fois la mise en œuvre et la vérification réussies.

6. Converger et archiver. Après QA_PASSEE, exécutez converge pour ajouter les écarts confirmés à .specs/02-tech-spec.md, écrire convergence.md, déplacer le lot dans tasks/archive/, et définir le status: archivée de la proposition. Sans converge, effectuez la réécriture d'ajout identique manuellement.

Recours manuel (sans Python)

1. Construisez la liste des standards à la main : configurations de la racine du dépôt, arbres de test/source, exécutions, ancres #sec-*.
2. Copiez assets/templates/proposal.template.md vers .specs/changes/<id-modification>/proposal.md, remplissez chaque jeton ({{...}}), et calculez base_spec_sha256.
3. Créez le lot de quatre documents tasks/<id-modification>/ en utilisant les modèles de task-decomposition ou le recours dans references/brownfield-protocol.md.
4. Exécutez les listes de contrôle Porte 1 / Porte 2 manuellement ; enregistrez les preuves dans le lot.
5. Suivez les étapes 5 à 6 du flux de travail avec les mêmes artéfacts.

Liste de contrôle de qualité

• Rapport de normes généré et à jour (standards_extract.py --check sort avec 0).
• Frontmatter de la proposition complet, status: proposée, kind correct, base_spec_sha256 à jour.
• Chaque bloc [CHG-<n>] nomme une ancre #sec-* réelle qui existe dans la spécification de base.
• Exactement un lot de tâches existe ; change_id est égal à l'id de la proposition et origin_spec_anchor est l'une des impact_anchors de la proposition.
• Budget de différence respecté : micro correspond à 1 fichier touché (10-49 lignes par défaut) ; standard correspond à 1-3 fichiers (50-250 lignes par défaut). Nombres configurables dans la configuration plan-linter.
• La porte 1 passe sur le contrat rempli et la proposition est ouverte (proposée/appliquée).
• La revue de la Porte 2 n'a pas de résultats bloquants ; le relecteur est indépendant et en lecture seule.
• Dev n'a implémenté que les touch_files ; QA a émis exactement un verdict avec des preuves.
• Converge a ajouté les différences à la spécification et la proposition est archivée.

Règles anti-hallucination

• N'inventez jamais de chemins de fichiers. Chaque entrée touch_files doit être un fichier existant à modifier ou un nouveau fichier dans un répertoire existant à créer (relatif au dépôt, avec des barres obliques).
• Chaque bloc de différence nomme une ancre réelle. Réutilisez une ancre #sec-* existante ; l'échafaudeur et le linter rejettent les ancres manquantes ou déplacées.
• N'inventez pas de commandes ou de conventions. Seules les commandes attestées par la configuration déclarée (le rapport de normes) peuvent apparaître dans la définition du fini (DoD) du contrat.
• Un changement structurel est escaladé. Si la modification nécessite une nouvelle section/ancre de spécification, un nouveau composant, une nouvelle ADR, ou une modification d'invariant, arrêtez-vous et utilisez spec-generator.
• Ne surestimez pas les portes. La Porte 1 est une comptabilité déterministe, la Porte 2 est une revue par consigne ; git et CI restent les autorités.

Scripts d'aide

• scripts/standards_extract.py — extracteur de normes déterministe ; écrit .specs/change-context/standards.md (--json, --check, --dry-run, --version).
• scripts/scaffold_change.py — crée une proposition et un lot de tâches (--dry-run, --force, --json, --version).
• scripts/lint_change.py — vérification de la cohérence proposition/lot et de la dérive de la spécification de base (--json, --version).

Tous les aides sont uniquement avec la bibliothèque standard, résolvent leur propre répertoire et sortent avec 0 (succès), 1 (échec de la porte), 2 (erreur d'utilisation), 3 (erreur inattendue).

Gestion des échecs

• Spécification de base manquante : Arrêtez-vous. Une modification brownfield nécessite une spécification de base ; l'échafaudeur sort avec 2.
• Ancre inconnue : Arrêtez-vous et réutilisez une ancre existante, ou escaladez vers spec-generator.
• Rapport obsolète ou dérive de spécification (sortie 1) : Régénérez le rapport, rebasez la proposition, relancez la Porte 1 ; ne modifiez jamais base_spec_sha256 à la main.
• Le répertoire de modification existe : Relancez avec --force uniquement s'il est jetable ; sinon, modifiez la proposition existante.
• Scripts indisponibles : Suivez le recours manuel ; le flux de travail est d'abord basé sur des consignes.

Limites honnêtes

• Le rapport de normes décrit la configuration déclarée, pas nécessairement la pratique appliquée ; c'est une consigne pour le planificateur, pas une preuve de conformité.
• base_spec_sha256 détecte tout changement d'octet dans la spécification de base ; après convergence, la proposition archivée est exemptée des vérifications de dérive.
• Les scripts optionnels peuvent être contournés ; CI et les autorisations du dépôt restent les autorités.