[stephrobert]

Summary

Engine part of #201. An inventory of the catalogues, run read-only on 2026-11-14, found the following:

• 446 versioned Markdown files outside labs/;
• 113 of them re-describe the engine;
• 50 of them, in 21 catalogues, say something false today.

Most of these were born from the new catalog skeleton, which copied the contract and a lab's lifecycle on the day the catalogue was created.

• The skeleton links instead of copying. The generated README section "The declarative contract" and "The lab lifecycle" become one section, "The engine, documented where it lives", in EN and FR. It links to contract-v1, commands, learner and catalog-author. The generated CI workflow comment no longer says that validate-structure only sees what loaded, which has been false since 0.1.97.

• New validate-structure family: stale_doc. It finds known false sentences in versioned Markdown outside labs/ and solution/. CHANGELOGs are excluded, since a dated log may legitimately quote old behaviour. Four rules:

  • doc_perimee_list_labs_avant: "run list-labs before validate-structure", or that the validator misses unloadable or missing labs. False since 0.1.97.
  • doc_perimee_status_joignabilite: dsoxlab status presented as the host reachability test. That is dsoxlab infra status.
  • doc_perimee_runtime_host: "every runtime.host points to a host". That field was never read.
  • doc_perimee_fixtures_a_plat: fixtures "copied flat". They keep their declared path since 0.1.37.

  Measured on every catalogue on disk: 38 files in 18 catalogues, no false positive. The first version of the runtime_host rule hit an iam note that states the truth ("runtime.host does not exist"). It was narrowed, and that case is now a test.

• Two false statements in the engine's own docs are fixed:

  • lab.<lang>.yaml also overrides each criterion's label, not only title and description;
  • in docs/machine-output, dsoxlab status is the state of a lab, while reachability is dsoxlab infra status.

• validate-structure --json: counts gains stale_doc (an additive key). The doc said "six families" while there were seven; it now says eight.

Merge order matters. Catalogue CIs install the latest engine. As soon as 0.9.3 is published, the 18 catalogues that carry these sentences turn red. The per-catalogue doc PRs (second half of #201) must therefore be merged before the 0.9.3 tag.

Type of change

• Bug fix (false docs)
• New feature (stale_doc family)
• Refactor
• Documentation
• Chore / tooling
• Security / supply chain

Checklist

Always

• ruff check src/dsoxlab tests tests_e2e fuzz scripts: passed
• mypy src/dsoxlab: no issues in 124 files
• pytest: 2,300 passed.
  • tests/test_doc_moteur_perimee.py (9 tests) covers each rule, a sentence cut by a line break, a true sentence never reported, the exclusion of labs/, solution/ and CHANGELOGs, and the rule that only versioned files count. It also checks that a brand-new new catalog scaffold is clean.
  • test_socle_du_catalogue.py now expects 13 sections and adds a test that the README links to the engine instead of copying it. Both fail on the previous scaffold.
• pytest tests_e2e: run by CI
• generer-doc.py --verifier and complexite.py --verifier: passed
• Domain-agnostic: the sentences are about dsoxlab itself, and no catalogue name appears in src/

When behavior changes

• CHANGELOG.md / CHANGELOG.fr.md: [Unreleased], Changed and Fixed, to ship in 0.9.3

When a command or option is added, removed or changed

• i18n keys for the new header and the four messages, in EN and FR
• Every new key is documented in docs/catalog-author(.fr).md (the coverage test enforces it)
• fullhelp: N/A, no command or option changed

Workflows / contract

N/A: no workflow touched; meta.yml and lab.yaml are unchanged.

🤖 Generated with Claude Code