You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
The stated language policy covers 1 file while the practice covers ~120: AGENTS.md:12 says French "lives only in doc/handwritten/for-users/README.fr.md", and CLAUDE.md plus the PR template likewise bind contributors to that single file — while the actual mirror is 92 EN/FR pairs across for-users, for-maintainers, workflows, specifications and all 26 ADRs (only adr/README.md states the real policy, for ADRs alone). No tooling checks pairing, freshness, or FR link integrity, despite tools/ housing five other consistency checkers. Both confirmed FR drifts (#231) occurred within days of EN-only commits — exactly the unprotected surface.
Impact
The project's genuinely distinctive full-mirror practice is an undocumented habit; decay is a matter of time as contributors multiply. Hard-coded IDE help-link URLs (HelpLinks.cs:9) would also break silently if the analyzer doc tree ever moved.
Direction
Codify the rule the corpus actually follows in AGENTS.md, CLAUDE.md, and the PR template: every file under doc/handwritten/ has an FR twin; English is canonical; FR updates in the same PR.
Add an advisory tools/docs-sync check: (a) pair completeness (three pairing schemes + the Internationalisation.fr.md exception, which must be recorded, not "fixed"); (b) warn when EN changes without its FR twin in a PR; (c) a relative link+anchor resolver over doc/ (also guarding the HelpLinks targets); (d) workflow-doc coverage (every .github/workflows/*.yml has EN+FR reference pages and an index row); (e) doc-hub inventory (see Docs: reconcile the two documentation hubs and link the sample projects #234).
Advisory severity, consistent with the adr-check philosophy.
Either translate adr/README.md/template.md or state they are deliberately English-only.
Acceptance criteria
The policy text matches the practice in the three governing files; the checks run in CI and would have flagged both historical drifts; the pairing conventions are written down where the tool lives.
Context
Surfaced by the 2026-07-20 architecture, design & ecosystem audit (doc/handwritten/for-maintainers/audit/2026-07-20-firstclasserrors-architecture-and-design-audit.md, §11.4/§11.6/§14-HV7-8; branch claude/firstclasserrors-audit-83gap7).
Problem
The stated language policy covers 1 file while the practice covers ~120:
AGENTS.md:12says French "lives only in doc/handwritten/for-users/README.fr.md", and CLAUDE.md plus the PR template likewise bind contributors to that single file — while the actual mirror is 92 EN/FR pairs across for-users, for-maintainers, workflows, specifications and all 26 ADRs (onlyadr/README.mdstates the real policy, for ADRs alone). No tooling checks pairing, freshness, or FR link integrity, despitetools/housing five other consistency checkers. Both confirmed FR drifts (#231) occurred within days of EN-only commits — exactly the unprotected surface.Impact
The project's genuinely distinctive full-mirror practice is an undocumented habit; decay is a matter of time as contributors multiply. Hard-coded IDE help-link URLs (
HelpLinks.cs:9) would also break silently if the analyzer doc tree ever moved.Direction
doc/handwritten/has an FR twin; English is canonical; FR updates in the same PR.tools/docs-synccheck: (a) pair completeness (three pairing schemes + theInternationalisation.fr.mdexception, which must be recorded, not "fixed"); (b) warn when EN changes without its FR twin in a PR; (c) a relative link+anchor resolver overdoc/(also guarding the HelpLinks targets); (d) workflow-doc coverage (every.github/workflows/*.ymlhas EN+FR reference pages and an index row); (e) doc-hub inventory (see Docs: reconcile the two documentation hubs and link the sample projects #234).adr/README.md/template.mdor state they are deliberately English-only.Acceptance criteria
Context
Surfaced by the 2026-07-20 architecture, design & ecosystem audit (
doc/handwritten/for-maintainers/audit/2026-07-20-firstclasserrors-architecture-and-design-audit.md, §11.4/§11.6/§14-HV7-8; branchclaude/firstclasserrors-audit-83gap7).