Aller au contenu
English

Évaluer un projet intégrateur faible

  • Étude de cas 2
  • 180 min
  • Facultative · 1 étude de cas requise pour le certificat

Où nous en sommes

Cette étude de cas applique les vérifications du cours de l'autre côté de la table : vous évaluez le projet intégrateur faible d'une autre personne comme le ferait un employeur attentif. Vous le notez selon la grille, trouvez ses problèmes en exécutant les vérifications et rédigez un plan de correction par ordre de gravité.

Ce que vous saurez faire

Évaluez le projet intégrateur d’une autre personne comme le ferait un employeur attentif. Évaluez-le selon la grille du cours, avec une raison et une preuve pour chaque résultat. Trouvez les problèmes en exécutant les vérifications du cours, pas en lisant le README. Rédigez ensuite un plan de correction que l’auteur peut suivre, par ordre de gravité des conséquences.

Étude de casPièce de portfolioDonnées synthétiques

Jeu de données
Le projet intégrateur faible de Theo (construit), basé sur l'ensemble de données de deux boutiques du cours (créé pour cette étude de cas)
Durée
Environ 3 heures
S’exécute dans
VS Code, Python 3.12+, Git, Docker
Compétences utilisées
  • Évaluation selon une grille
  • Affirmations et preuves
  • Vérifications d'isolation
  • Verrouillage des données réservées et historique Git
  • Vérifications des citations
  • Recherche de secrets dans l'historique
  • Problèmes introduits volontairement
  • Un plan de correction par ordre de gravité des conséquences

Décompressez le projet de départ, ouvrez le dossier dans VS Code et suivez les étapes ci-dessous. Elles commencent par un nouvel environnement virtuel.

Tout dans cette remise est construit. Theo Marsh n’est pas une personne réelle. L’équipe du cours a créé son dépôt à partir du doc-assistant terminé du cours et y a introduit des problèmes volontairement. Les secrets dans son historique ont été inventés pour cette page et n’ont jamais fonctionné. Les fichiers de départ contiennent le dépôt de Theo et la trousse du réviseur. Le téléchargement final ajoute l’évaluation corrigée, le plan de correction et la nouvelle remise de Theo.

Avant de commencerCe qu’il faut savoir et avoir sous la mainEnviron 180 minutes

Ce que vous devez savoir

Cette étude de cas utilise tout le cours, du point de vue du réviseur. Elle s’appuie surtout sur :

Ce qu’il vous faut sur votre ordinateur

  • Python 3.12 ou une version plus récente, Git, VS Code et Docker Desktop, comme dans le cours.
  • Environ 1 Go d’espace disque libre pour les paquets (surtout torch) et les modèles. Si vous avez réalisé le projet du cours, les modèles sont déjà dans votre cache.
  • Aucune clé et aucun coût : les réponses sont celles que l’équipe du cours a enregistrées.

Testé sur macOS (Apple M4, 16 Go, PostgreSQL 18.6, Python 3.12.13). Les commandes Windows et Linux sont écrites, mais non testées.

Hana Kim dirige l’ingénierie dans une petite agence de logiciels. Elle recrute une personne pour un poste junior en ingénierie de l’IA. Theo Marsh a posé sa candidature avec un lien vers son projet intégrateur : un assistant documentaire pour deux boutiques. Le projet suit le parcours standard du cours. Le README est confiant : « prêt pour la production », « 97 % d’exactitude », « isolation complète des locataires ». Hana et Theo sont des personnages inventés pour cette étude de cas.

Hana a une entrevue avec Theo vendredi. Elle vous demande d’abord d’évaluer le projet intégrateur. « Utilisez la grille du cours, dit-elle. Il me faut un résultat pour chaque élément, avec une raison que je peux vérifier. Si j’embauche sur la base d’une démo qui cache une fuite, notre premier client trouvera cette fuite. Si je refuse une bonne candidature junior à cause d’une impression, c’est injuste, et nous perdons cette personne. »

Les deux erreurs ont un coût. Une réussite accordée à tort introduit une fuite ou une clé divulguée dans le projet d’un client. Un échec attribué à tort écarte une personne pour un problème qui n’existe pas. Les preuves protègent contre les deux : chaque résultat renvoie à une commande, un fichier ou un commit que chacun peut vérifier.

L’objectif. En environ trois heures, quatre choses :

  1. Un résultat pour chacun des quatre éléments de la grille, avec une raison et les preuves.
  2. Tous les problèmes détectables par une vérification, trouvés en exécutant cette vérification.
  3. Un plan de correction par ordre de gravité des conséquences, avec la vérification qui prouve chaque correction.
  4. Une évaluation que Theo pourrait lire sans se sentir attaqué : elle porte sur le travail, pas sur la personne.

Vous créez une évaluation, pas un produit. Elle comprend trois parties, dans reviewer-kit/review-template.md :

Partie Contenu
Résultats une ligne par élément de la grille : le résultat, la raison, les preuves
Tableau des affirmations chaque affirmation du README, du rapport et de la démo, avec les preuves trouvées
Constats et plan de correction un bloc par problème (description, preuves, conséquences, élément de la grille), puis les corrections dans l’ordre

Vous mesurez aussi votre méthode d’évaluation : trois façons d’évaluer le même dépôt, et ce que chacune trouve. À la fin, vous appliquez votre méthode à la nouvelle remise de Theo pour vérifier qu’elle n’invente pas de problèmes.

Le README.md de la trousse le dit dès les premières lignes : la remise est construite. Le dépôt de Theo est le doc-assistant terminé du cours, avec neuf commits dans son historique. Son code est sous licence MIT, et ses documents forment l’ensemble synthétique du cours (CC0). Rien ici ne vient d’une vraie boutique ou d’une personne réelle.

Dossier Description
theo-doc-assistant/ la remise, un dépôt Git avec 9 commits
reviewer-kit/marking-rubric.md la grille du cours, inchangée
reviewer-kit/checklist.md l’évaluation, étape par étape
reviewer-kit/review-template.md l’évaluation à remplir
reviewer-kit/secret_scan.py une recherche de secrets dans chaque commit
reviewer-kit/citation_check.py les vérifications des citations du cours, exécutées en dehors du pipeline

Pourquoi une remise construite plutôt qu’un vrai dépôt? L’équipe du cours a comparé trois options; les raisons figurent dans la fiche du jeu de données du téléchargement. Le dépôt d’une personne réelle n’a souvent aucune licence, et une évaluation publique de son travail est injuste envers elle. Personne ne connaît tous ses problèmes, donc vous ne pourriez pas vérifier votre évaluation. Il n’aurait pas non plus deux boutiques ni de verrouillage des données réservées. Les vérifications les plus importantes de la grille ne pourraient donc pas s’exécuter.

  1. Téléchargez les fichiers de départ dans l’encadré en haut de cette page, puis décompressez-les dans votre dossier de projets. Vous obtenez weak-capstone-review/.

  2. Dans VS Code, choisissez File > Open Folder (Fichier, ouvrir un dossier) et ouvrez weak-capstone-review/theo-doc-assistant. Ouvrez un terminal : Terminal > New Terminal (Terminal, nouveau terminal).

  3. Si la base de données de votre propre projet intégrateur fonctionne, arrêtez-la d’abord : exécutez docker compose stop dans son dossier. Les deux utilisent le port 5432.

  4. Créez un environnement virtuel, installez les paquets et démarrez la base de données :

    Fenêtre de terminal
    python3 -m venv .venv
    source .venv/bin/activate
    pip install -r requirements.txt
    cp .env.example .env
    python -m idp init
    docker compose up -d --wait db
    python -m doc_assistant.migrate
    python -m scripts.load_pack

    La dernière commande affiche :

    Identity: 2 shops, 7 people, 6 memberships
    larkfield: 36 documents uploaded, 0 already there
    bramble: 15 documents uploaded, 0 already there
    Indexing with intfloat/multilingual-e5-small@614241f ...
    Indexed 51 documents in 8.6 s (failed 0).
    bramble: 15 documents, 60 passages, 0 failed
    larkfield: 36 documents, 185 passages, 0 failed

    La première fois, elle télécharge aussi le modèle de plongement (embedding), ce qui prend plus de temps. Vos durées seront différentes.

Toutes les commandes de cette page s’exécutent dans theo-doc-assistant/, avec .venv actif. Les scripts de la trousse se trouvent un dossier plus haut; vous les appelez donc avec python ../reviewer-kit/….

Commencez par les documents, mais n’attribuez encore aucun résultat. Une première impression n’est pas une preuve, et elle persiste. Copiez plutôt chaque affirmation dans le tableau des affirmations de votre modèle. Une affirmation est une phrase qui peut être vraie ou fausse. Le README et le rapport de Theo présentent celles-ci :

Affirmation Emplacement
« 97 % d’exactitude sur les questions d’évaluation » README
« 94,7 % sur les questions réservées » README, rapport
« 100 % fondé sur les sources : chaque réponse cite ses documents sources » README; « Citations valides : 100 % » dans le rapport
« Isolation complète des locataires »; « J’ai testé en me connectant comme chaque personne » README, rapport
« Utilisé par le personnel de soutien de deux boutiques » README
« Prêt pour la production » README, rapport
« Injection suivie : 0 »; « Temps médian par question : 12 ms » rapport

Lisez ensuite l’historique une fois, en commençant par le bas. Il est court :

Fenêtre de terminal
git log --oneline
6423863 Submission: README, evaluation report and demo script
595b283 CI: faster pipeline
32a99bb Remove .env from the repository
25945bd Held-out set: remove 3 broken questions
1c8721f Faster answers: skip the citation check
9a5083d Evidence panel: open the passage of every citation
a62bd2e Tune: hybrid search (60 of 62 on the tuning set)
e3b34e7 Add my settings so that the live model works
491336d Start my capstone on the standard track: data pack, questions, held-out set reserved

Ce que cela nous apprend. Theo écrit des messages de commit clairs : chacun indique ce qui a changé. Quatre d’entre eux nomment un élément que ce cours protège : les données réservées, la vérification des citations, .env et le pipeline CI. Ce n’est pas la preuve d’un problème. Cela vous indique où regarder d’abord.

La plupart des évaluations de portfolio s’arrêtent à l’une de deux étapes. Essayez d’abord les deux, comme référence de base.

Évaluation A : suivre le README et la démo. Les étapes du README fonctionnent, comme vous l’avez vu pendant la préparation. Posez ensuite les questions du script de démo :

Fenêtre de terminal
python -m scripts.ask "Can a customer cancel a pre-order for a full refund?" --tenant bramble
Ines (owner) at Bramble Books asks: Can a customer cancel a pre-order for a full refund?
Passages found: 311c86d6f6b4 special-orders v2, 9ff619b9c4c4 distributor-northwind-preorders v1, c7d77b28cdf0 events-and-room-hire v1, 08e4f08c1aa4 refund-approval-procedure v1, 863b6a08be18 special-orders v2
Answer (answerable): Yes. You can cancel a pre-order for a full refund until 7 days before its release date; after that, the returns policy applies. To cancel, reply to your order email or ask at the shop.
- A pre-order can be cancelled for a full refund until 7 days before its release date; after that, the returns policy applies. [Special orders and pre-orders, Pre-orders, v2]
- To cancel, reply to the order email or ask at the shop. [Special orders and pre-orders, Pre-orders, v2]
recorded chat-small | 3747 ms | tokens 904 in, 179 out | US$0.000180 | trace 54829346bba77a09f6699f9ab292c6d6

La réponse est bonne : elle cite la politique de Bramble et ignore l’instruction cachée du distributeur. La question sur la carte-cadeau fonctionne aussi. La question de Sam sur le rabais du personnel reçoit la réponse simulée, étiquetée « Aucun enregistrement pour cette question ». C’est parce que le script de démo ne donne aucune date. Une répétition de la démo aurait permis de le remarquer, mais c’est une erreur, pas un problème du produit.

Évaluation B : exécuter ce que la CI exécute. L’analyse statique, la vérification des données réservées et les tests :

Fenêtre de terminal
ruff check .
python -m scripts.holdout check
python -m pytest
All checks passed!
Held-out set: 38 questions (bramble 13, larkfield 25). SHA-256 matches the lock (647f0b8b75b8...).
Tuning set (dev.jsonl): 62 questions (bramble 20, larkfield 42).
...
106 passed, 2 skipped in 39.06s

Ce que cela nous apprend. Les deux évaluations réussissent. Un réviseur qui s’arrête ici marque chaque élément « démontré ». Hana invite alors Theo à parler d’un produit prêt pour la production. Gardez cette idée en tête. Deux petits détails sont étranges, et aucun n’est une preuve. Le script de démo se termine par « Conseil : utilisez seulement ces questions. Elles fonctionnent toujours. », et 2 tests sont ignorés.

Comment savoir si une méthode d’évaluation fonctionne? Une alarme incendie a un bouton de test : vous produisez volontairement de la fumée et vérifiez que l’alarme sonne. Une enseignante qui forme de nouveaux correcteurs fait la même chose. Elle leur donne une rédaction contenant cinq erreurs connues et compte combien chaque correcteur en trouve.

La même idée fonctionne pour les évaluations. Vous introduisez volontairement des problèmes dans un travail et notez chacun d’eux. Puis vous évaluez le travail et comptez ce que la méthode a trouvé. Ce sont des problèmes introduits volontairement (en test logiciel, fault seeding, ou introduction volontaire de défauts). Ces problèmes donnent un corrigé à une méthode d’évaluation, comme les questions réservées en donnent un à un assistant. Sans corrigé, « l’évaluation n’a rien trouvé » peut signifier « tout va bien » ou « l’évaluation ne détecte rien ». Vous ne pouvez pas distinguer les deux.

L’équipe du cours a introduit sept problèmes dans le dépôt de Theo, un par type d’erreur que la grille nomme. Cette page ne les énumère pas encore : trouvez-les d’abord avec les vérifications. La mesure est la même pour chaque méthode d’évaluation :

  • Trouvé : la sortie d’une commande montre le problème. Un autre réviseur pourrait l’exécuter et voir la même ligne.
  • Indice : quelque chose qu’un réviseur attentif pourrait remarquer, mais qui ne prouve rien à lui seul.
  • Manqué : rien dans la méthode ne le signale.

Seul « trouvé » compte : un indice justifie une vérification, pas un résultat d’évaluation. (Calibrer les évaluateurs, dans le cours sur l’évaluation, compare les personnes entre elles; ici, vous comparez une méthode à des réponses connues.)

Partie 4 : révision C, la grille avec les vérifications du cours

Section intitulée « Partie 4 : révision C, la grille avec les vérifications du cours »

Révisez maintenant le travail selon la grille : une preuve pour chaque élément. Suivez reviewer-kit/checklist.md. Il exécute six vérifications. Chacune utilise une commande déjà vue dans le cours ou un petit script de la trousse.

Vérification 1 : les données réservées et leur historique

Section intitulée « Vérification 1 : les données réservées et leur historique »

La révision B a vu « SHA-256 correspond au verrou », puis a continué. Mais un verrou prouve seulement que le fichier correspond au verrou. Si quelqu’un réécrit le verrou, la vérification réussit. La grille demande une chose de plus : les données ont-elles été réservées avant tout ajustement? Git peut répondre.

Fenêtre de terminal
python -m scripts.holdout check
git log --format="%h %ad %s" --date=short -- evaluation/heldout.jsonl evaluation/heldout.lock docs/tuning-log.md doc_assistant/config.py
wc -l evaluation/questions.jsonl evaluation/heldout.jsonl evaluation/dev.jsonl
Held-out set: 38 questions (bramble 13, larkfield 25). SHA-256 matches the lock (647f0b8b75b8...).
Tuning set (dev.jsonl): 62 questions (bramble 20, larkfield 42).
25945bd 2026-09-15 Held-out set: remove 3 broken questions
a62bd2e 2026-09-08 Tune: hybrid search (60 of 62 on the tuning set)
491336d 2026-09-01 Start my capstone on the standard track: data pack, questions, held-out set reserved
103 evaluation/questions.jsonl
38 evaluation/heldout.jsonl
62 evaluation/dev.jsonl
203 total

Ce que cela nous apprend. Le cours réserve 41 questions; 38 et 62 donnent 100 sur 103, donc trois questions ont quitté les deux ensembles. Le verrou a changé le 15 septembre, une semaine après le commit (enregistrement des modifications) d’ajustement. L’empreinte est 647f0b8b75b8…, et non celle du cours, e8eda11340d6…. Le fichier docs/tuning-log.md de Theo explique pourquoi :

- First run of the held-out set (hybrid): 36 of 41.
- Q13, Q28 and B12 fail in every run: the search never finds their passage. They look broken, so I removed them from `heldout.jsonl` and wrote the new SHA-256 into `heldout.lock`. Now 36 of 38 (94.7%).

Les trois questions n’étaient pas défectueuses. Ce sont les trois échecs de récupération que montre aussi l’exécution du cours sur les données réservées, dans Exécuter les tests sur des données réservées. Retirer les échecs après les avoir vus revient à ajuster le système sur les données réservées. Le résultat de 94,7 % ne mesure rien d’inédit. Problème trouvé : les données réservées ont changé après l’ajustement. Theo n’avait aucune mauvaise intention et l’a noté honnêtement. Le journal est exactement la preuve dont un réviseur a besoin.

L’isolation passe avant tout résultat de qualité, comme dans Exécuter les tests sur des données réservées. Si un commerce peut voir les données de l’autre, le reste ne compte pas encore.

Fenêtre de terminal
python -m scripts.isolation
Search: 103 questions asked in the other shop -> 0 passages of the first shop
Access: 11 staff-only questions asked by read-only members -> 0 staff-only passages
API: 298 requests with the other shop's IDs -> statuses {404: 258, 200: 40}, 40 leaks
Database: 8 unfiltered queries under row-level security -> 0 rows of the other shop
Isolation checks: 420 probes, 40 leaks.

Trois couches tiennent. Une échoue : 40 requêtes API avec les identifiants de l’autre commerce ont reçu 200, et non 404. python -m scripts.isolation --json donne des exemples :

"api_leak_examples": [
"GET /v1/tenants/bramble/chunks/d8438ab8b245 -> 200",
"GET /v1/tenants/bramble/chunks/196a7a8771ec -> 200",

Ines, membre de Bramble Books, a demandé un passage de Larkfield à la route de preuves de son propre commerce. Elle l’a reçu. Cette route est celle qu’utilise une citation. git show 9a5083d montre le changement :

with request.app.state.db.tenant(who.tenant_id) as conn:
# admin(): the evidence of an older version did not open under tenant(); a chunk ID is unique anyway
with request.app.state.db.admin() as conn:
...
" WHERE c.tenant_id = %s AND c.chunk_id = %s AND d.access = ANY(%s)",
(who.tenant_id, chunk_id, list(who.access_levels))).fetchone()
" WHERE c.chunk_id = %s AND d.access = ANY(%s)",
(chunk_id, list(who.access_levels))).fetchone()

Le même commit a supprimé une ligne de tests/test_deletion.py : l’assertion voulant que Sam reçoive 404 pour un passage de Bramble. Le test échouait. Theo a retiré la ligne du test, pas la cause. La transaction administrateur contourne la sécurité au niveau des lignes, donc les deux verrous étaient ouverts en même temps. « Un identifiant de segment est unique » est vrai, mais ce n’est pas une autorisation : chaque réponse montre ses identifiants.

Problème trouvé : une fuite entre commerces. La règle de la grille détermine immédiatement la note. Une vérification du contrôle d’accès a échoué. L’élément 3 est donc non démontré pour le moment, peu importe ce qui fonctionne ailleurs.

Le rapport de Theo dit « Citations valides : 100 % ». Le script d’évaluation confirme ce résultat sur les données d’ajustement :

hybrid, answer_v2, recorded: 62 questions | correct 0.968 | retrieval hit 0.962 | citations valid 1.000 | abstained when it should 0.889 | injection obeyed 0 of 4 | median 11.0 ms | US$0.000159 per question

Le pipeline du cours donne 0,963 sur les mêmes réponses enregistrées. Pourquoi 1,000 ici? L’évaluation compte les problèmes que le pipeline a enregistrés avec chaque affirmation. Si le pipeline cesse de vérifier, il n’enregistre aucun problème et chaque affirmation semble valide. Une mesure qui ne peut pas échouer n’est pas une mesure.

Le script citation_check.py de la trousse vérifie donc de l’extérieur. Il pose chaque question de la banque au pipeline de Theo, comme un vrai membre du commerce. Il exécute ensuite les vérifications du cours (doc_assistant/cite.py) sur ce que l’utilisateur voit. Il pose aussi les questions réservées au personnel avec des comptes de membres en lecture seule. Puis il compare son décompte aux signalements du pipeline :

Fenêtre de terminal
python ../reviewer-kit/citation_check.py
Staff: 103 questions, 86 answers with claims, 135 claims | flagged by the pipeline: 0 | this check: 2 hard problems, 10 clues
Q05 usr-sam no_citation: The customer had no purchases for two years, which is longer than 18 months.
B02 usr-ines no_citation: A $75 order is over $60.
Read-only: 11 questions, 1 answer with claims, 2 claims | flagged by the pipeline: 0 | this check: 0 hard problems, 0 clues
Citation check: 2 claims that the user cannot check; the pipeline flagged 0. It does not check what it shows.

Deux affirmations ne citent rien. Chacune est une étape de raisonnement que le modèle a écrite sans passage. Le pipeline du cours signale une telle réponse pour révision; celui de Theo l’affiche comme toute autre réponse. git show 1c8721f montre la cause : Theo a retiré l’appel à check_answer « pour aller plus vite ». Le même commit a modifié tests/test_pipeline.py, qui n’attend donc plus l’étape check (vérification). La ligne sur la lecture seule est une bonne nouvelle : aucun membre en lecture seule n’a reçu de réponse réservée au personnel.

Problème trouvé : la vérification des citations est ignorée. Le parcours fonctionne encore, donc l’élément 1 est partiellement démontré. La grille mentionne « une “absence de réponse” qui ressemble à une réponse ». Ici, une affirmation sans source ressemble à une affirmation avec citation.

Cette vérification demande une nouvelle idée. Pensez à une lettre que vous avez envoyée par erreur. Vous pouvez supprimer votre copie, mais la lettre est déjà dans la boîte aux lettres de quelqu’un. Un commit Git fonctionne de la même façon. Quand vous le poussez, chaque clone reçoit une copie complète de l’historique. Supprimer un fichier dans un commit ultérieur le retire seulement de la dernière version. L’ancien commit le contient toujours, et n’importe qui peut le lire avec une seule commande.

Neuf commits à la suite, de 491336d à 6423863. Le commit e3b34e7, « env ajouté : clé et 2 secrets », est rouge. Le commit 32a99bb, « .env supprimé », est ambré. En dessous, deux boîtes. À gauche, en rouge, avec une flèche pointillée depuis e3b34e7 portant l'étiquette « conservé dans chaque clone » : chaque clone, car git clone copie les 9 commits; le .env du commit e3b34e7 est toujours là, avec LLM_API_KEY, OIDC_CLIENT_SECRET et SESSION_SECRET. À droite, avec une flèche depuis 6423863 portant l'étiquette « extrait » : le dernier commit, ce qu'un lecteur voit sur GitHub : README, doc_assistant, docs, tests, et aucun .env. Une note : l'analyse des secrets lit chaque ligne ajoutée par n'importe quel commit.
Supprimer .env dans un commit ultérieur le masque seulement dans la dernière version. Chaque clone contient toujours le commit qui l'a ajouté.
Description textuelle du diagramme

Neuf commits vont de gauche à droite. Le deuxième, e3b34e7, a ajouté .env avec une clé de modèle et deux secrets. Le septième, 32a99bb, l’a supprimé. Le dernier commit, qu’un lecteur voit sur GitHub, n’a pas de .env. Mais un clone copie les neuf commits, donc le fichier de e3b34e7 est toujours dans chaque copie. Une analyse des secrets lit chaque ligne ajoutée par n’importe quel commit, pas seulement la dernière version.

C’est pourquoi une analyse des secrets lit l’historique, pas le dossier. Le script secret_scan.py de la trousse lit chaque ligne ajoutée par n’importe quel commit, sur chaque branche. Il signale notamment les fichiers à ne jamais enregistrer dans un commit, comme .env. Il signale aussi une affectation comme SESSION_SECRET= avec une valeur qui semble réelle. Il ignore les valeurs présentées comme des exemples, comme change-me-on-your-computer (à changer sur votre ordinateur). Il affiche seulement les quatre premiers caractères d’une valeur pour éviter de diffuser davantage le secret.

Fenêtre de terminal
python ../reviewer-kit/secret_scan.py .
Scanned 9 commits on every branch of theo-doc-assistant: 10,237 added lines.
e3b34e7 2026-09-03 Add my settings so that the live model works
.env a file that should never be committed
.env:17 LLM_API_KEY = dak-... (44 characters)
.env:35 OIDC_CLIENT_SECRET = 3964... (32 characters)
.env:36 SESSION_SECRET = 3119... (48 characters)
Found 4 possible secrets in 1 commit(s), in .env.
Not in the latest commit: .env. Deleted later, but every clone still has them.
Treat each one as public: revoke or replace it first, then clean the history.

Ce que cela nous apprend. .gitignore contient .env, donc Theo a dû forcer son ajout (git add -f). Quiconque clone le dépôt peut utiliser la clé du modèle et facturer des frais au compte de Theo. Tant que le secret de session est utilisé, n’importe qui peut signer un témoin (cookie) de session pour tout utilisateur. Les valeurs ici sont inventées; dans un vrai dépôt, elles seraient actives.

Problème trouvé : des secrets dans l’historique. La grille est explicite : « un secret […] est enregistré dans un commit » rend l’élément 2 non démontré pour le moment. La règle du cours de Git donne l’ordre de correction : révoquer d’abord, puis nettoyer l’historique.

L’analyseur de la trousse est un outil pédagogique d’environ 120 lignes. Dans une équipe, exécutez aussi un analyseur maintenu dans l’intégration continue (CI), par exemple gitleaks (licence MIT). L’équipe du cours n’a pas exécuté gitleaks pour cette page.

La fuite entre commerces aurait dû arrêter la CI. Pourquoi cela n’a-t-il pas été le cas? Comparez le flux de travail au premier commit :

Fenêtre de terminal
git diff 491336d HEAD -- .github/workflows/ci.yml
- name: Isolation checks (must be 0 leaks)
run: python -m scripts.isolation
- name: Evaluation smoke test (recorded answers, held-out set)
run: python -m scripts.evaluate --set heldout --min-correct 0.75

Et demandez aux tests pourquoi deux d’entre eux ont été ignorés :

Fenêtre de terminal
python -m pytest -rs -k holdout
SKIPPED [1] tests/test_holdout.py:18: held-out set cleaned up: 3 broken questions removed
SKIPPED [1] tests/test_holdout.py:25: held-out set cleaned up: 3 broken questions removed
2 passed, 2 skipped, 104 deselected in 0.42s

git log --stat -- tests/ révèle une tendance : quatre commits ont modifié du code protégé par un test. Chacun a aussi modifié ce test. tests/test_operations.py a même perdu scripts.isolation dans sa liste des étapes obligatoires de CI.

Problème trouvé : la CI a perdu deux de ses vérifications. Chaque changement semble petit. Ensemble, ils ont permis à une fuite d’atteindre main avec un pipeline au vert. C’est pourquoi la révision B n’a rien vu.

Vérification 6 : les chiffres du rapport, mesurés à nouveau

Section intitulée « Vérification 6 : les chiffres du rapport, mesurés à nouveau »

Exécutez l’évaluation sur les données réservées avec le dépôt tel quel. Comparez chaque chiffre au tableau des affirmations :

Fenêtre de terminal
python -m scripts.evaluate --set heldout --show-failures
hybrid, answer_v2, recorded: 38 questions | correct 0.947 | retrieval hit 0.969 | citations valid 1.000 | abstained when it should 0.833 | injection obeyed 0 of 2 | median 10.0 ms | US$0.000168 per question
...
WRONG Q37 (larkfield, table, hit False): Les documents ne précisent pas la durée de la garantie d’un barbecue.
WRONG B34 (bramble, other-shop, hit None): An agent can give up to $15 in goodwill credit, once per customer per year.

Remplissez maintenant la colonne des preuves :

Affirmation Preuve Confirmée?
« 97 % d’exactitude » 0,968 correspond à 60 sur 62 dans les données d’ajustement, les questions utilisées pour choisir la recherche hybride. Sur les 41 questions réservées, le résultat est 36 sur 41 (0,878, vérification 1 et nouvelle remise ci-dessous). contredite
« 94,7 % sur les questions réservées » 36 sur 38, après le retrait des trois échecs contredite
« 100 % fondé sur les sources » 2 affirmations sans citation; la vérification ne s’exécute pas contredite
« Isolation complète des locataires » 40 fuites; se connecter et consulter les listes ne teste pas une route qui accepte un identifiant contredite
« Utilisé par le personnel de soutien de deux commerces » les commerces et les personnes viennent de l’ensemble synthétique du cours aucune preuve
« Prêt pour la production » un portable, une connexion d’exercice, des documents synthétiques, une fuite, des secrets enregistrés dans des commits contredite
« Injection suivie : 0 » 0 sur 2 oui
« Temps médian : 12 ms » vrai pour les réponses enregistrées, récupérées dans un fichier. Une réponse en direct a pris environ 1,3 s lors des exécutions de l’équipe du cours. trompeuse

Problème trouvé : des affirmations sans preuve. Les commandes du dépôt contredisent cinq affirmations, et une n’a aucune preuve. La grille nomme ce cas précis : « affirmations sans preuve (par exemple “prêt pour la production”, “sécuritaire”, affirmations sur l’emploi ou les utilisateurs) ». L’élément 4 est non démontré pour le moment.

Le script de démo suit la même tendance. Ses quatre questions fonctionnent, et sa dernière ligne dit « il ne confond jamais les commerces ». Il ne présente aucun cas d’échec ni compromis, bien que l’exécution du rapport montre des erreurs pour Q37 et B34. Le récit de la démo demande les deux. Problème trouvé : la démo cache les échecs.

Erreur courante

La vérification des citations dit « no module named doc_assistant » (aucun module nommé doc_assistant)

Symptôme : python ../reviewer-kit/citation_check.py s’arrête avec ModuleNotFoundError: No module named 'doc_assistant' (aucun module nommé « doc_assistant »).

Cause : vous l’avez exécuté depuis reviewer-kit/ ou weak-capstone-review/. Le script utilise volontairement le code du dossier où vous l’exécutez : il doit vérifier le pipeline de la remise.

Correction : utilisez cd pour entrer dans theo-doc-assistant/, activez .venv, puis relancez le script. La base de données doit fonctionner et l’ensemble de données doit être chargé.

Trois révisions du même dépôt, par la même personne, avec la même grille. Seule la méthode a changé. Voici ce que chacune a montré face aux sept problèmes introduits :

Une grille de sept lignes, une par problème introduit, et quatre colonnes. Lignes : données réservées réduites après l'ajustement (élément 3 de la grille); route de preuves montrant les passages de l'autre commerce (3); vérification des citations ignorée (1 et 3); secrets enregistrés dans un commit, puis supprimés (2); CI ayant perdu deux vérifications (2); démo montrant seulement les réussites (4); affirmations sans preuve (4). Colonne A, suivre le README et la démo : manqué pour cinq, indice pour la démo et les affirmations; total de 0 trouvé, 2 indices. Colonne B, exécuter ce que la CI exécute : indice pour les données réservées (2 tests ignorés), manqué pour le reste; total de 0 trouvé, 1 indice. Colonne C, la grille avec les vérifications du cours : trouvé pour les sept, chacun avec sa preuve : 38 questions, 3 perdues et verrou réécrit après l'ajustement; 40 fuites sur 420 essais; 2 affirmations sans citation contre 0 signalée par le pipeline; 4 problèmes détectés dans un .env supprimé; 2 vérifications retirées de ci.yml; Q37 et B34 erronées, mais évitées par la démo; 97 % correspond au 0,968 des données d'ajustement. Total de 7 trouvés. Colonne C sur la nouvelle remise : réussite pour les sept.
Seule la révision avec les vérifications du cours a trouvé les problèmes introduits. Les mêmes vérifications réussissent sur la nouvelle remise corrigée.
Description textuelle du diagramme

La grille a une ligne pour chacun des sept problèmes introduits et une colonne pour chaque révision. La révision A, qui suit le README et la démo, n’en a trouvé aucun et a donné deux indices : l’astuce de la démo et les mots « prêt pour la production ». La révision B, qui exécute ce que la CI exécute, n’en a trouvé aucun et a donné un indice : deux tests ignorés. La révision C, avec les vérifications du cours, a trouvé les sept, chacun avec la sortie d’une commande. La dernière colonne exécute à nouveau la révision C sur la nouvelle remise de Theo : les sept vérifications réussissent.

Révision Trouvés (sur 7) Indices Temps sur l’ordinateur de l’auteur
A. Suivre le README et la démo 0 2 environ 15 secondes de commandes, après la préparation
B. Exécuter ce que la CI exécute 0 1 environ 40 secondes, surtout les tests
C. La grille avec les vérifications du cours 7 – environ 35 secondes de commandes, plus la lecture

Ce que cela nous apprend.

  • Un pipeline au vert prouve ce qu’il vérifie, et rien de plus. La révision B a exécuté les vérifications de la remise. La remise avait retiré celles qui échoueraient. Un réviseur doit exécuter les vérifications demandées par la grille, depuis l’extérieur de la remise.
  • Le coût vient de la lecture, pas du calcul. Les commandes de la révision C ont été plus rapides que la suite de tests. La lecture prend du temps : comparer les affirmations aux sorties, et chaque différence à sa raison.
  • Les indices ne sont pas des notes. Les indices de la révision A étaient réels. Mais « la démo semble prudente » n’est pas une raison sur laquelle Theo peut agir. Chaque indice devient une vérification, et la sortie de cette vérification devient la raison.
  • La comparaison est-elle équitable? Le même dépôt, le même réviseur et la même grille. Une faiblesse : l’équipe du cours a introduit les problèmes, donc elle savait où chercher. C’est pourquoi la mesure compte seulement ce que montre la sortie d’une commande. Un réviseur sans le corrigé exécuterait les mêmes commandes et verrait les mêmes lignes.

Maintenant, et seulement maintenant, écrivez les notes. Chaque raison correspond à ce que vous avez vu. Chaque preuve est quelque chose que Theo peut exécuter.

Élément de la grille Note Raison Preuve
1. Parcours utilisateur fonctionnel Partiellement démontré Le parcours fonctionne à partir du README, avec des citations qui s’ouvrent et une « absence de réponse » claire. Mais les affirmations sans source s’affichent comme celles avec citation, et aucune réponse n’est signalée pour révision. citation_check.py : 2 contre 0; commit 1c8721f
2. Dépôt et déploiement reproductibles Non démontré pour le moment Des secrets ont été enregistrés dans des commits. La CI a perdu les vérifications d’isolation et d’évaluation. secret_scan.py : 4 problèmes détectés dans e3b34e7; les différences de ci.yml
3. Évaluation sur des données réservées et vérifications d’isolation Non démontré pour le moment 40 fuites par la route de preuves. Les données réservées ont été réduites après l’ajustement. scripts.isolation; git log -- evaluation/
4. Démo, architecture et limites claires Non démontré pour le moment Cinq affirmations contredites par le dépôt, une sans preuve; une démo sans cas d’échec ni compromis; des limites génériques. le tableau des affirmations; docs/demo-script.md

Puis vient le plan de correction. Classez-le selon les dommages possibles : d’abord ce qui peut nuire à un commerce ou coûter de l’argent. Ensuite, les preuves, puis la présentation. Chaque correction nomme la vérification qui la prouve.

Ordre Correction Vérification qui la prouve
1 Exécutez à nouveau la route de preuves dans la transaction du commerce, avec le commerce dans la requête. Rétablissez la ligne de test supprimée. scripts.isolation : 0 fuite
2 D’abord, révoquez la clé du modèle et créez de nouveaux secrets. Publiez ensuite un dépôt dont l’historique ne contient aucun .env. secret_scan.py : aucun secret trouvé
3 Rétablissez les deux étapes de CI et remettez scripts.isolation dans le test du flux de travail. le test du flux de travail réussit
4 Appelez à nouveau check_answer et signalez pour révision les réponses ayant un problème bloquant. citation_check.py : les deux décomptes concordent
5 Restaurez les 41 questions réservées et le premier verrou. Rapportez 36 sur 41 et nommez les échecs. Dites que ces résultats ont été vus. holdout check : 41, e8eda11340d6…
6 Réécrivez le README, le rapport et la démo à partir des preuves. chaque ligne du tableau des affirmations : « oui »

La correction 2 suit un ordre interne, tiré du cours de Git : révoquer d’abord. Un nouvel historique n’aide pas si quelqu’un a déjà copié la clé.

La correction 5 a une limite honnête. Theo a maintenant vu les 41 résultats. Les restaurer rend le rapport exact, mais les données ne sont plus inédites. Le prochain changement de Theo demande de nouvelles questions réservées, mises de côté avant l’ajustement.

Avant d’envoyer la révision, relisez-la une fois en vous mettant à la place de Theo. Chaque phrase porte sur le travail, pas sur la personne. Commencez par ce qui fonctionne : le parcours s’exécute à partir du README, et le journal d’ajustement est honnête. Dites à Theo de continuer à écrire ce journal : il a facilité la confirmation du problème des données réservées. La révision du corrigé dans le téléchargement terminé, reviewer-kit/review.md, montre le texte complet.

Partie 7 : de bout en bout sur de nouvelles données, la nouvelle soumission

Section intitulée « Partie 7 : de bout en bout sur de nouvelles données, la nouvelle soumission »

Theo lit la revue et soumet une nouvelle version deux semaines plus tard. Le téléchargement terminé contient theo-doc-assistant-resubmitted/ : un nouveau dépôt, créé à partir de l’historique de Theo sans les commits (validations) contenant .env, plus cinq commits correctifs. Exécutez de nouveau la revue C, sur une base de données vierge. Les étapes de préparation sont les mêmes. Voici les sorties, réduites aux lignes décisives :

$ python -m scripts.holdout check
Held-out set: 41 questions (bramble 14, larkfield 27). SHA-256 matches the lock (e8eda11340d6...).
$ python -m scripts.isolation
Isolation checks: 420 probes, 0 leaks.
$ python ../reviewer-kit/citation_check.py
Staff: 103 questions, 86 answers with claims, 135 claims | flagged by the pipeline: 2 | this check: 2 hard problems, 10 clues
Citation check: the pipeline flags the same 2 claims as this check, and marks their answers for review.
$ python ../reviewer-kit/secret_scan.py .
No secret found in the history.
$ python -m scripts.evaluate --set heldout --show-failures
hybrid, answer_v2, recorded: 41 questions | correct 0.878 | retrieval hit 0.886 | citations valid 1.000 | abstained when it should 0.833 | injection obeyed 0 of 2 | median 10 ms | US$0.000167 per question
WRONG Q13 (larkfield, answerable, hit False): …
WRONG Q28 (larkfield, version, hit False): …
WRONG Q37 (larkfield, table, hit False): …
WRONG B12 (bramble, answerable, hit False): …
WRONG B34 (bramble, other-shop, hit None): …

Ce que cela nous apprend.

  • La méthode n’invente pas de problèmes. Dans un dépôt corrigé, toutes les vérifications réussissent. Une méthode de revue qui signale aussi le bon travail serait aussi inutile qu’une méthode qui ne signale rien.
  • Le score a baissé, et c’est correct. 36 sur 41 (0,878) est inférieur au premier score de 94,7 %, et c’est le vrai résultat. Le nouveau rapport nomme les cinq échecs. Le scénario de démo mentionne maintenant B34 à voix haute pour montrer honnêtement un échec.
  • Les deux affirmations sans citation sont toujours là. Le correctif ne les a pas cachées : le pipeline les marque maintenant pour révision, comme le fait la version du cours. L’objectif était « les nombres concordent », pas « 0 ».
  • Certaines choses ne se prouvent pas avec une commande. La clé a-t-elle vraiment été révoquée? Theo peut-il expliquer la transaction d’administration et pourquoi elle était incorrecte? Ajoutez ces questions à la liste de Hana pour l’entrevue.

Avec ces résultats, les éléments 1 à 3 sont démontrés. L’élément 4 est démontré sur papier : les affirmations ont des preuves, et la démo présente un échec et un compromis. Sa dernière condition, « l’apprenant peut expliquer n’importe quelle partie du code », sera vérifiée vendredi.

  • Exécutez les vérifications; ne vous fiez pas aux badges. Un pipeline vert, un fichier de verrouillage concordant et des tests réussis peuvent tous coexister avec une fuite. Ils prouvent seulement ce qu’ils vérifient, et l’auteur choisit ce qu’ils vérifient.
  • Lisez les différences de chaque modification de test. Quatre des sept problèmes s’accompagnaient d’une modification correspondante d’un test. Un test modifié dans le même commit que le code qu’il protège est le meilleur indice qu’une revue puisse trouver.
  • Une seule fuite compte plus que tous les bons chiffres. La règle de la grille existe parce qu’une fuite est un autre type d’échec : elle nuit à une boutique, pas à un score.
  • Évaluez aussi le réviseur. Les problèmes introduits volontairement donnent un corrigé à une méthode de revue. Utilisez-les pour former de nouveaux réviseurs, ou avant de faire confiance à une liste de vérification.
  • Limites de cette étude. La soumission est construite, et des personnes connaissant les vérifications y ont introduit les problèmes. Dans un vrai travail faible, les problèmes sont moins bien rangés. Certains problèmes n’ont aucune vérification : une conception inadaptée à l’utilisateur, ou du code que l’auteur ne peut pas expliquer. Un réviseur, un dépôt et un ordinateur. Windows et Linux ne sont pas testés.
  • Évaluez le travail, pas la personne. Écrivez « la route des preuves ignore la boutique », pas « Theo ne comprend pas la sécurité ». La personne peut être un débutant compétent qui a pris un raccourci par manque de temps.
  • Signalez un secret exposé en privé, et rapidement. Prévenez directement l’auteur, jamais dans un signalement public ni dans un commentaire sur le dépôt. N’utilisez jamais le secret pour « prouver » qu’il fonctionne.
  • Une revue n’est pas une publication. Elle est destinée à Hana, qui l’a demandée, et à Theo. Ne la publiez pas.
  • N’exécutez pas les vérifications sur le service actif d’une autre personne. Clonez le dépôt et exécutez-le sur votre ordinateur, comme ici. Sonder un service déployé qui ne vous appartient pas ressemble à une attaque, pour son propriétaire et pour la loi.
  • Appliquez la même grille à chaque candidat. Si vous évaluez cinq candidats, utilisez les mêmes vérifications dans le même ordre pour chacun. Une vérification supplémentaire pour une seule personne n’est pas équitable.
  • Construit, pas réel. Theo et Hana sont inventés. Ne présentez pas cette revue comme celle du travail d’une personne réelle.

La revue de code appuyée par des preuves est une compétence que les équipes recherchent à l’embauche. Cette étude de cas la montre : une grille appliquée avec des commandes, un plan de correction classé par préjudice et une vérification de la méthode elle-même.

Quoi mettre dans un dépôt (le vôtre, pas celui de Theo) :

capstone-review/
README.md what you reviewed (constructed, and by whom), the method, the results grid
review.md your marks, claims table, findings and fix plan
fix-plan.md the fixes in order, each with its check
method.md the three review methods and the seven seeded problems, with what each found
secret_scan.py the scanner, with any rule that you added and why
outputs/ the outputs of your checks, as text files
  1. Créez un nouveau dépôt pour la revue. N’incluez pas le dépôt de Theo : ajoutez plutôt un lien vers le téléchargement du cours, et précisez qu’il est construit.
  2. Mettez la grille de la partie 5 dans le README, sous forme de tableau, avec vos propres temps.
  3. Exécutez encore une fois votre revue sur votre propre projet intégrateur. Ajoutez une section : ce que les vérifications ont trouvé dans votre travail, et ce que vous avez corrigé.

En entrevue, trois phrases : « J’ai évalué un projet intégrateur avec une grille et les vérifications du projet. Elles ont trouvé sept problèmes introduits volontairement que sa CI verte cachait, dont une fuite entre boutiques et une clé dans l’historique Git. J’ai classé les correctifs par préjudice, et les mêmes vérifications ont réussi sur la version corrigée. »

Pour aller plus loin :

  • Ajoutez à secret_scan.py une règle pour un type de secret qu’il ne détecte pas, et un test correspondant.
  • Faites aussi signaler par citation_check.py les affirmations dont les nombres sont absents du passage cité (les « indices »), et lisez-en cinq manuellement.
  • Introduisez un problème supplémentaire dans une copie de votre projet intégrateur, et voyez si la revue d’un ami le trouve.

Vérifiez votre compréhension

La commande `python -m scripts.holdout check` de Theo affiche « SHA-256 matches the lock » (SHA-256 correspond au fichier de verrouillage). Pourquoi cela ne suffit-il pas à considérer les données réservées comme démontrées?

Afficher la réponse

La vérification prouve seulement que le fichier correspond au fichier de verrouillage. Quiconque modifie le fichier peut réécrire le fichier de verrouillage, et Theo l’a fait. La grille demande si les données ont été réservées avant l’ajustement. L’historique Git répond : le fichier de verrouillage a changé dans 25945bd, une semaine après le commit d’ajustement a62bd2e, et le nombre est passé de 41 à 38. Le journal d’ajustement indique que les trois questions retirées étaient les échecs. L’élément est donc, au mieux, partiellement démontré, et la fuite le fait passer à « pas encore ».

Vérifiez votre compréhension

Theo a supprimé `.env` dans un commit ultérieur, et `.gitignore` le contient. Un ami dit : « Le secret a disparu, donc l'élément 2 est correct. » Que répondez-vous, et que doit faire Theo en premier?

Afficher la réponse

Le secret n’a pas disparu. Un clonage copie chaque commit, donc le fichier .env de e3b34e7 est dans chaque copie, et git show e3b34e7:.env l’affiche. La grille attribue « pas encore » à un secret enregistré dans un commit, peu importe ce que montre le dernier commit. Theo doit d’abord révoquer la clé du modèle et créer de nouveaux secrets : seule cette étape empêche leur utilisation abusive. Ensuite, il faut un historique sans le fichier, par exemple dans un nouveau dépôt.

Vérifiez votre compréhension

Dans la nouvelle soumission, `citation_check.py` signale encore 2 problèmes graves. Le correctif est-il incomplet?

Afficher la réponse

Non. Les deux affirmations (Q05 et B02) sont des étapes de raisonnement que le modèle a écrites sans source. Le pipeline du cours les produit aussi. Dans la première soumission, le problème était que le pipeline en signalait 0 et les affichait comme des affirmations citées. Maintenant, le pipeline signale les mêmes 2 que la vérification et marque ces réponses pour révision. L’objectif était « les nombres concordent », pas « zéro problème ». Cacher les deux affirmations serait un nouveau problème.

Récapitulatif

  • Deux revues courantes, suivant le README et exécutant la CI, n’ont trouvé aucun des sept problèmes introduits volontairement. Leurs résultats verts prouvaient seulement ce que la soumission avait choisi de vérifier.
  • La grille accompagnée des vérifications du cours a trouvé les sept problèmes, chacun avec la sortie d’une commande. Trois étaient des données réservées réduites, une fuite entre boutiques et une vérification des citations omise. Les autres étaient des secrets dans l’historique, une CI affaiblie, un échec caché et des affirmations non prouvées.
  • L’échec d’une vérification du contrôle d’accès détermine la note de son élément, peu importe ce qui fonctionne ailleurs. Les notes étaient : partiellement, pas encore, pas encore, pas encore.
  • Le plan de correction suivait l’ordre des préjudices, et chaque correctif nommait sa vérification. Dans la nouvelle soumission, toutes les vérifications réussissaient, et le vrai score était inférieur : 36 sur 41.
  • Les problèmes introduits volontairement donnent un corrigé à une méthode de revue, comme les questions réservées en donnent un à un assistant.

Ensuite, le travail final : créez votre propre projet intégrateur et évaluez-le avec cette méthode avant de le soumettre.

Leçon suivante : Travail final