@sylad/cadence 1.1.0 → 1.2.0

package/templates/fiche-back.yaml

@@ -0,0 +1,75 @@
+# Gabarit de fiche back (lot sans écran, étape spec back d'orchestrate, L187). Copier dans docs/specs/<sujet>/fiche.yaml,
+# remplacer les valeurs, puis `cadence spec check docs/specs/<sujet>/fiche.yaml`.
+# Chaque clé et les invariants vérifiés sont décrits dans la section « spec » du README de cadence.
+# Un lot qui a aussi un écran (screen:) ajoute à ce fichier la partie écran du gabarit templates/fiche.yaml
+# (ecran, etats, champs, actions) : sujet.id et ecran.id sont alors le nom du dossier.
+sujet:
+  id: mon-sujet                # kebab-case ; nom du dossier docs/specs/<id>/
+  titre: Mon sujet
+  lot: L0                      # le lot d'implémentation
+  perimetre:                   # ce que le lot touche : au moins un module, un endpoint ou un job
+    modules: [backend/src/modules/mon-module]
+    endpoints: ["GET /api/elements"]
+    jobs: []
+    hors_perimetre: ["l'affichage dans le frontend (un lot d'écran à part)"]   # facultatif : ce que le lot ne fait pas
+
+cas:                           # C1, C2… dans l'ordre, sans trou
+  - id: C1
+    titre: Le client lit la liste alors que la source est en panne
+    acteur: un client de l'API
+    declencheur: GET /api/elements     # un appel de contrat, un job ou une commande
+    preconditions:
+      - la source externe ne répond pas
+    nominal:                   # les étapes du cas passant
+      - Le service interroge la source.
+      - L'appel échoue.
+      - Le service renvoie la dernière liste connue et écrit un warning.
+    alternatives:              # { si, alors, regles } : chaque alternative cite au moins une règle
+      - { si: la source répond, alors: la réponse est fraîche, regles: [R2] }
+    resultat: La dernière liste connue au lieu d'une erreur.
+  - id: C2
+    titre: Le planificateur rafraîchit la liste
+    acteur: le planificateur
+    declencheur: job elements-refresh
+    preconditions:
+      - une liste est en cache
+    nominal:
+      - Le job appelle la source.
+      - Le cache est réécrit.
+    alternatives: []
+    sans_alternative: le seul échec du job est celui de C1 (R1) ; il n'a pas d'autre branche   # obligatoire quand alternatives est vide
+    resultat: Le cache porte l'horodatage du dernier succès.
+
+regles:                        # R1, R2… dans l'ordre, sans trou
+  - id: R1
+    cas: [C1, C2]              # une règle back est rattachée à au moins un cas (une règle d'écran à un état : etat)
+    enonce: Quand la source échoue, l'API sert la dernière liste connue au lieu d'une erreur.
+    statut: sourcee            # sourcee : dit d'où elle vient (source) ; hypothese : dit ce qui changerait (si_faux)
+    source: "demande du lot : « servir le dernier cache connu au lieu d'une erreur »"   # une ligne du lot, un fichier:ligne, un contrat existant…
+    tests: ["R1 — source en panne : la dernière liste est servie"]   # chaque test nommé « Rn — … »
+  - id: R2
+    cas: [C1]
+    enonce: Une réponse fraîche ne porte pas le champ ageSecondes.
+    statut: hypothese
+    si_faux: Si le champ doit toujours être présent, seul son contenu change (aucune donnée en jeu).
+    tests: ["R2 — réponse fraîche : ageSecondes absent"]
+
+contrats:                      # A1, A2… dans l'ordre (dans une fiche mixte, communs avec les actions de l'écran)
+  - id: A1
+    appel: GET /api/elements   # VERBE /chemin, job <nom> ou commande <nom>
+    entree: aucune
+    sortie: "la liste, ou une liste vide (HTTP 200)"
+    erreurs:                   # { code, message } : code « HTTP <n> » ou « log <niveau> », message = le texte exact
+      - { code: log warn, message: "Serving cached list: source unavailable" }
+    regles: [R1, R2]
+  - id: A2
+    appel: job elements-refresh
+    entree: "cron 0 */15 * * * *"
+    sortie: "cache réécrit après un succès, inchangé après un échec"
+    erreurs: []
+    sans_erreur: le job ne répond à aucun appelant ; son échec est un warning déjà couvert par A1   # obligatoire quand erreurs est vide
+    regles: [R1]
+
+donnees:                       # D1… : les données touchées ([] si aucune)
+  - { id: D1, objet: "data/elements-cache.json ({ ts, data })", existant: true, modification: aucune, note: "relu en secours, format et écriture inchangés" }
+  # existant: true avec modification: ajout|changement exige  decision: <la réponse du lead à la question ciblée>

package/templates/orchestrate/accept-back.md

@@ -0,0 +1,16 @@
+Acceptance tests of the behaviour of lot `{{lot}}` in `{{chemin}}`, as the acceptance writer: you write the tests BEFORE any code, from the sheet only, so that the implementer has an independent oracle. You are not the implementer: you do not write, read-to-copy or guess the implementation.
+{{repos}}
+{{accept}}
+
+Rules:
+- One or more cases per rule of the sheet, named exactly as the sheet plans it (`regles[].tests`, e.g. `R5 — une entrée de 14 jours est refusée : null`); the tests call the contracts of `contrats[]` as close as possible (the controller or the service for an HTTP call, the method of the job for a `job`), and simulate the external sources from `entree`. What cannot be automated is out of scope.
+- Every test must FAIL for now, because the feature is missing (not because of a typo or a broken setup): the program runs the dedicated command and refuses tests that pass.
+- Do not touch the sheet, the plan or any application code. Do not push, deliver, run `raf done`, `raf ux` or `raf review`.
+- Commit with explicit paths (never `git add -A` or `commit -a`), ONE commit citing the lot (`test({{lot}}): acceptation R1–Rn (rouge)`) with the test files, the acceptation file and the runner configuration, and leave the working tree clean. The program seals the acceptation file afterwards (it adds the fingerprint of each test file): never write `empreintes` or `vert: true` yourself.
+Decide minor interpretation questions yourself and list each one under "choix" with the alternative you did not take. Leave "questions" empty rather than writing a placeholder such as "no question".
+{{commits}}
+{{reponse}}
+Report: `commits`, `nonVerifie` (what you could not run or check), `choix`, `questions`, `resume`.
+
+You are one short session of an orchestrated wave: do not launch subagents (the Agent tool is disabled).
+Give your final report as the structured output, not as free text.

package/templates/orchestrate/fiche.md

@@ -0,0 +1,14 @@
+Sheet review of lot `{{lot}}` — "{{titre}}" — of the repository `{{chemin}}`, following your agent instructions (sheet mode).
+Goal of the lot: {{objectif}}
+{{repos}}
+{{fiche}}
+
+You review the sheet BEFORE any code is written: the later steps (acceptance tests, implementation, code review) take it as their reference. This is NOT the review of the code of the lot, and not the `raf review` verdict.
+Read the project's CLAUDE.md first, then the sheet, then the code and the tests of the modules of `sujet.perimetre`, and every source the sheet cites. Check, with a measurement for each finding (the file:line you opened, the command you ran):
+1. Sourced or hypothesis. Each `sourcee` rule cites a source that exists: open the file:line or the note and read what it says. Each `hypothese` carries a `si_faux` and does not hide one of the four expensive categories (data model or storage; public or shared API contract or published route; destructive or irreversible action; contradiction with a sourced rule) — such a hypothesis is a *major* finding.
+2. No contradiction. With a rule already coded (search the modules of the perimeter, open the existing tests that assert the opposite) and with an existing API contract (field, error code, route).
+3. Errors and limits. For each contract: the empty, absent, expired, oversized and duplicate inputs and each failure of an external source have a rule, or a motivated `sans_alternative` / `sans_erreur`.
+4. One test per rule. Each rule has at least one planned test whose name says what is checked and could fail (the program already checks that a test is planned).
+Rank the findings blocking / major / minor, never on taste: a blocking or major finding sends the sheet back to the spec writer (one more pass only), a minor one becomes a note of the lot.
+You are read-only: do not modify, commit, push or run `raf review|ux|done`. Do not launch subagents. Leave `sousTaches` empty: a sheet has no bug to sub-task.
+Give your report as the structured output: counts of blocking / major / minor findings, each finding (severity, file, line, text), what you could not verify, and a one-line verdict.

package/templates/orchestrate/spec-back.md

@@ -0,0 +1,25 @@
+Spec of the behaviour of lot `{{lot}}` — "{{titre}}" — in `{{chemin}}`, as the spec writer: you write a machine-readable sheet (use cases, rules, contracts, data) BEFORE any code, so that the later steps (review of the sheet, acceptance tests, implementation) share one reference. There is no screen part: only the sheet.
+Goal of the lot: {{objectif}}
+{{repos}}
+Read the lot, its notes and sub-tasks in the plan (`docs/plan/raf.yaml`, or the file named by `plan:` in `cadence.yaml`), the project's CLAUDE.md, and the code and tests of the modules the lot touches (the services, controllers or jobs, their tests, the API contracts and error messages already present): the rules already coded are sources, and a new rule must not contradict them.
+{{spec}}
+
+What you produce, in `<dir>/<sujet>/`:
+- `fiche.yaml`, in the format of the template below (`sujet`, `cas`, `regles`, `contrats`, `donnees`). Check it with `cadence spec check <fiche>` until it is valid.
+
+Sheet rules:
+- Every use case (`cas`) names its trigger (a contract call, a job, a command), its preconditions, its nominal steps, and its alternatives and error cases, each pointing to the rules that govern it — or says `alternatives: []` with its reason in `sans_alternative`.
+- Every rule is `sourcee` (it says where it comes from: a line of the lot, a note, a rule already coded as **file:line** — the review opens it —, an existing API contract, an existing test, a requirement of a reference document) or `hypothese` (you chose it for lack of a source; `si_faux` says what would change if it were wrong). Never present a guess as sourced. Every rule is attached to at least one case and has at least one planned test, named `Rn — …`, whose name says what is checked and could fail.
+- Every contract (`contrats`) gives the call (`VERBE /chemin`, `job <nom>` or `commande <nom>`), the input, the output and the errors with the exact code (`HTTP <n>` or `log <level>`) and the exact message; for each, think of the empty, absent, expired, oversized and duplicate inputs and of every failure of an external source, and give each a rule — or say `sans_erreur` with the reason.
+- Every datum the lot touches is in `donnees`; an existing datum whose model changes needs the lead's `decision`: that is a question (below).
+- A rule you invent is not a free choice: **a hypothesis whose `si_faux` involves an expensive-to-undo choice is a question, not a hypothesis.** The four expensive categories: a data model or storage (key, column, table, file or cache format, migration); a public or shared API contract, or an already published route or job name (renaming, removing or changing the type or the meaning of a field, an error code, a route); a destructive or irreversible action (deletion, purge, sending a mail or a notification, payment, one-way migration); a rule that contradicts an existing sourced rule or a rule already coded. In those cases do not write the hypothesis: stop and put the question under "questions" (the lead answers and the step is resumed). Everything else (wording, order, a default) is a written hypothesis, cheap to correct later. **An optional field added to an existing response is not a break** when the sheet proves the old response is unchanged (a rule says so): write it as a hypothesis with its `si_faux`.
+- If, after reading the lot and the code, you find that the lot changes NO behaviour (nothing a user, an API client or another service can observe: a lint, a rename, a move, a doc, a CI or cache setting without observable effect), write one line with the reason in `sousSeuil`, create no sheet, and finish: the lot then follows the usual path.
+
+Commit the sheet with explicit paths (never `git add -A` or `commit -a`), a message that cites the lot (`spec({{lot}}): …`), and leave the working tree clean. Do not implement the behaviour, do not write application code or tests, do not push, deliver, run `raf done`, `raf ux` or `raf review`.
+Decide minor interpretation questions yourself and list each one under "choix" with the alternative you did not take. Leave "questions" empty rather than writing a placeholder such as "no question".
+{{commits}}
+{{reponse}}
+Report: `fiche` (path of the sheet relative to the repository, e.g. `docs/specs/<sujet>/fiche.yaml`, or empty under the threshold), `sousSeuil` (the reason, or empty), `commits`, `nonVerifie` (what you could not check), `choix`, `questions`, `resume`.
+
+You are one short session of an orchestrated wave: do not launch subagents (the Agent tool is disabled).
+Give your final report as the structured output, not as free text.