claude-math/README.md
boyreau f672241e9c Fix subscripted-variable false positives; finalize plugin metadata
verify-calculations.sh mistook subscripted/numbered variables (x_1, x1,
3x_1) for bare numeric equations, flagging e.g. "x_1 = 0" as the false
claim "1 = 0". The single-letter variable regex only excluded adjacent
letters, not trailing digits/underscores, and the prose segment
extractor could start a fresh match right after such a break, mining a
free digit out of the identifier.

Also carries over the author/repository metadata and the SSH-vs-HTTP
install note for the Forgejo marketplace (DISABLE_HTTP_GIT blocks the
https URL; the ssh:// path has no /forgejo/ segment).

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-11-08 12:22:18 +01:00

103 lines
4.2 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# claude-math
Plugin Claude Code pour un cours de **mathématiques pour la cryptographie** :
génération d'exercices calibrés, correction, suivi de progression, et
vérification automatique des calculs tapés dans les messages.
| Composant | Chemin | Rôle |
|---|---|---|
| Skill | `skills/math-exercises/SKILL.md` | Génère des séries de 4 exercices progressifs sur le prochain sujet non maîtrisé, corrige les réponses, et tient à jour `PROGRESS.md` / `REVISIONS.md`. |
| Commande | `commands/exos.md` | `/exos` — lance le skill en forçant Opus via son frontmatter `model:`. |
| Hook | `hooks/verify-calculations.sh` | `UserPromptSubmit` : vérifie automatiquement toute affirmation mathématique tapée dans un message et renvoie un verdict ✅/❌ ligne par ligne. |
## Installation
> **Prérequis : Nix.** Le hook de vérification lance Python + sympy via
> `nix-shell -p python3 python3Packages.sympy`. Sans Nix sur la machine, le
> skill et la commande fonctionnent normalement mais le hook échoue
> silencieusement — aucun calcul n'est vérifié (il ne bloque jamais l'envoi
> d'un message). Voir [Se passer de Nix](#se-passer-de-nix) pour l'adapter.
```bash
/plugin marketplace add https://zospace.freeboxos.fr/forgejo/zo/claude-math
/plugin install claude-math@claude-math
```
L'instance Forgejo refuse actuellement le git en HTTP (`DISABLE_HTTP_GIT`), si
bien que l'URL ci-dessus ne sert qu'à consulter le dépôt. Pour que
`/plugin marketplace add` fonctionne en HTTPS, passer `DISABLE_HTTP_GIT =
false` dans `app.ini` ; sinon, installer par SSH :
```bash
/plugin marketplace add ssh://forgejo@zospace.freeboxos.fr/zo/claude-math
/plugin install claude-math@claude-math
```
Noter que le chemin diffère entre les deux protocoles : le segment `/forgejo/`
est celui du reverse-proxy web et n'existe pas côté SSH.
Le dépôt est à la fois le plugin (`.claude-plugin/plugin.json`) et une
marketplace à entrée unique (`.claude-plugin/marketplace.json`), donc les deux
commandes suffisent.
## Ce que le skill attend du projet où il tourne
Le plugin ne transporte **pas** les données du cours. Dans le dossier de
travail, il s'attend à trouver :
- `CLAUDE.md` — le plan du cours (TD1/TD2/TD3 et leurs sous-sections) ; c'est
la source de la liste des sujets ;
- `NOTATIONS_REFERENCE.md` — les notations telles qu'elles apparaissent en
cours ;
- `PROGRESS.md` — suivi par sujet (créé par le skill s'il manque) ;
- `REVISIONS.md` — notions non réussies du premier coup, pour re-test espacé
(créé par le skill s'il manque) ;
- les PDF des TD et de leurs corrections, pour calibrer notation et difficulté.
## Le hook de vérification
À chaque message, le hook extrait les énoncés vérifiables et les contrôle :
- chaînes d'égalités et de congruences — `8^6 mod 15 = 64*8^4 = … = 4` ;
- divisibilité — `7 | 28` ;
- primalité — `13 est premier` ;
- `pgcd` / `ppcm` / `φ(n)` ;
- équations à une inconnue — `2x + 3 = 7`.
**Règle de portée du modulus :** un `mod N` écrit sur *n'importe quel* maillon
d'une chaîne porte sur **tous** les maillons. C'est la convention du cours :
le modulus est énoncé une fois et reste implicite ensuite. Si deux moduli
différents apparaissent dans la même chaîne, le hook se tait plutôt que
d'accuser à tort.
Notations acceptées : exposants Unicode (`4²²`), `≡`, `(mod 15)`, `φ`, `×`,
`·`, `pgcd`/`ppcm`, et le LaTeX courant (`$…$`, `\equiv`, `\pmod{15}`,
`8^{6}`). Les maths noyées dans de la prose française sont extraites et
vérifiées ligne par ligne.
### Se passer de Nix
Remplacer dans `hooks/verify-calculations.sh` la ligne :
```bash
nix-shell -p python3 python3Packages.sympy --run python3 << 'PYTHON_EOF' 2>/dev/null
```
par un interpréteur disposant de sympy, par exemple :
```bash
python3 << 'PYTHON_EOF' 2>/dev/null
```
## Développement
Le hook est un script bash qui encapsule un programme Python en heredoc. Pour
le tester sans passer par Claude Code, lui envoyer sur stdin le JSON de
l'évènement :
```bash
printf '{"prompt": "8^6 mod 15 = 64 * 8^4 = 4"}' | bash hooks/verify-calculations.sh
```
Il répond sur stdout un JSON `{"systemMessage": …}` contenant les verdicts, et
les écrit en direct sur `/dev/tty` quand un terminal est disponible.