project_catala_review_plan_2026_04_25

Catala /review-plan 2026-04-25

Triggered by Rich directive after 11th session auto-deep-dive win (library-web-research pattern): “begin an immediate /review-plan of how these 3 discoveries impact all other Catala aspects of the inherit v2 & inheritkit project.”

Three discoveries underlying the plan

1. catala-explain production module (github.com/CatalaLang/catala-explain) — Catala ecosystem already separates explanation-trace into dedicated module producing .docx documents with execution traces + user inputs + hyperlinks to source code definitions. Validates CatalaResult-as-first-class-component choice (δ).
2. Catala v1.0.0 (Nov 2024) + v1.1.0 “bac d’Eloka” (Jan 2026) production stable — v1.1.0 key features: VSCode LSP Testing pane, JSON I/O debugging, external modules with externally-defined types, enumerations with hundreds of cases, “Allow access to intermediate variable states” (maps directly to CatalaResult trace), #[error.message] attributes, markdown file recognition. Risks previously noted (“dependency on 5-person research group”) substantially mitigated.
3. catleg French legislative tooling (github.com/CatalaLang/catleg) + [Q-MERI-238A72AA6D] pre-existing French inheritance Catala work — provides official Catala+Akoma Ntoso integration prior-art pattern for Phase-C Step 2.

14 improvement opportunities identified

Priority 1 (HIGHEST commercial impact)

IMPROVEMENT-1 — Reframe AI-vendor commercial pitch around .docx explanation artifacts:

• Prior framing: “AI-vendors pay for schema + rules access”
• New framing: “AI-vendors pay for Catala-backed legal reasoning + per-query .docx explanation artifacts that satisfy AI-safety requirements for legal reasoning transparency”
• Tiered commercial model:
  • Free: raw CatalaResult (JSON values)
  • Pro: CatalaResult + catala-explain .docx per query
  • Enterprise: above + custom InheritKit-branded .docx templates + partner-crate jurisdictional-localisation
  • AI-Vendor: above + programmatic .docx streaming API + audit-pack for AI-safety-review
• Rationale: AI-safety teams at OpenAI/Anthropic need exactly explainability-for-legal-reasoning; .docx with hyperlinked statutory anchors + applied-rule traces directly serves this need
• Affects: Phase-C Step 4 Commercial-model spec; project_ai_vendor_commercial_model memory

IMPROVEMENT-2 — Phase-C Step 3 SSI introduces CatalaBackedClaim pattern:

• Prior: VCs are signed static assertions
• New: VCs carry dynamic claims backed by per-evaluation Catala reasoning
• Example: AttorneyshipCredential carries evaluateWithCatala(lpa-s-10-conditions, donor.currentCapacityState) → {valid: true, scope: [financial, health], explanation: $catala-explain-trace}
• VCs become auditable-per-evaluation rather than static assertions
• Affects: Phase-C Step 3 SSI spec brief

Priority 2 (HIGH architectural impact)

IMPROVEMENT-3 — Phase-C Step 2 Akoma Ntoso spec references catleg as prior art:

• catleg URI conventions become normative precedent for Catala+Akoma Ntoso integration
• Extend pattern to legislation.gov.uk (E&W) ELI URIs + Scottish legislation + Swiss Bundesrecht-Sammlung + other jurisdictions
• Reduces Akoma Ntoso spec invention surface; accelerates Phase-1 adoption
• Affects: Phase-C Step 2 Akoma Ntoso spec brief

IMPROVEMENT-4 — Catala spec brief v1.0 → v1.1 with research-grounded ecosystem context:

• Expand library_evidence_registered with catala-explain + v1.0/v1.1 + catleg
• Reframe from “language-introduction” to “ecosystem-integration”
• Update scope-approval section reflecting δ lock
• Update anticipated-decisions (Topic 5 + 6 may lock via ratification)
• Affects: Catala spec brief

IMPROVEMENT-5 — Phase-C Step 1 gains optional Catala POC deliverable:

• Minimal Catala module (ew-intestacy-aea-1925-pt4) demonstrating:
  • Declaration binding to probate:IntestacyResolution (Topic 5 γ 9-field spec)
  • 3-5 test cases anchored to AEA 1925 Part IV prose
  • catala-explain .docx rendering
  • TypeScript SDK binding demonstration
• De-risks Phase-1 execution; provides AI-vendor demo artifact
• Affects: Phase-C Step 1 deliverables

Priority 3 (MEDIUM — memory saves)

IMPROVEMENT-6 — Update project_ai_vendor_commercial_model memory with explanation-artifact reframing (keep prior framing as superseded context).

IMPROVEMENT-7 — Save project_catala_ecosystem_maturity_2026_04_25 memory: captures 3 discoveries + architectural framing shift.

IMPROVEMENT-8 — Save feedback_library_web_research_narrow_margins memory: captures 11th auto-deep-dive win pattern (library+web research on narrow-margin architecture-critical decisions).

Priority 4 (MEDIUM — within Catala decision round)

IMPROVEMENT-9 — Topic 5 (Certification model) may LOCK A-55 reuse via ratification (not full 5-option scorecard). v1.0.0 stability + catala-explain ecosystem maturity argue for A-55 reuse.

IMPROVEMENT-10 — Topic 6 (Backend targets) may LOCK OCaml (CatalaLang native) + TypeScript (InheritKit SDK) as primary via ratification. v1.0.0 stable Python/OCaml/JS/R backends remove target-selection ambiguity.

Priority 5 (LOW — Phase-1 authoring)

IMPROVEMENT-11 — A-21 CI chain extension documented for Phase-1 (18 → 21+ gates): Catala compilation gate + test-coverage gate + catala-explain-rendering gate + intermediate-state-inspection gate.

IMPROVEMENT-12 — Probate brief retroactive: catala-explain as VestingTransition explanation surface. A-98 can be Catala-encoded with catala-explain producing per-jurisdiction .docx vesting-transition explanations.

IMPROVEMENT-13 — Phase-1 authoring timeline may accelerate: production-stable Catala → Phase-1 Catala authoring in parallel with Phase-1 T-Box/SHACL authoring.

IMPROVEMENT-14 — Testing discipline inherits VSCode LSP + Testing pane as primary IDE for test-first authoring workflow.

Execution sequence (priority-ordered)

1. Save 3 new memories (IMPROVEMENT-7 + 8 + this review-plan memory) — 5-10 min
2. Update project_ai_vendor_commercial_model (IMPROVEMENT-6) — 10 min
3. Catala spec brief v1.0 → v1.1 (IMPROVEMENT-4) — 20 min
4. Commit + push — 2 min
5. Proceed to Topic 2 CatalaRuleCategoryScheme scorecard with updated baseline

Deferred to downstream specs

• IMPROVEMENT-1 + 6 → Phase-C Step 4 Commercial-model spec
• IMPROVEMENT-2 → Phase-C Step 3 SSI spec
• IMPROVEMENT-3 → Phase-C Step 2 Akoma Ntoso spec
• IMPROVEMENT-5 → Phase-C Step 1 wave close or Phase-1 authoring
• IMPROVEMENT-11 + 13 + 14 → Phase-1 authoring plan refinement

Why

All 14 improvements are derived from 3 ecosystem discoveries, not invention. The commercial reframing (IMPROVEMENT-1) alone justifies the research investment — shifts value prop from data-licensing to legal-explanation-as-a-service, aligning with AI-safety-team explanation-requirements at OpenAI/Anthropic/Google/Meta/xAI.

How to apply

At each Phase-C spec authoring checkpoint, cross-reference this review-plan to ensure the relevant improvements are incorporated. Specifically:

• Before Phase-C Step 2 Akoma Ntoso brief authoring: check IMPROVEMENT-3 (catleg reference)
• Before Phase-C Step 3 SSI brief authoring: check IMPROVEMENT-2 (CatalaBackedClaim)
• Before Phase-C Step 4 Commercial brief authoring: check IMPROVEMENT-1 (explanation-artifact reframing)
• Before Phase-1 execution: check IMPROVEMENT-5 + 11 + 13 + 14
• Before Topic 5 + 6 Catala decisions: check IMPROVEMENT-9 + 10 (possible ratification shortcuts)

Related memories

• project_catala_ecosystem_maturity_2026_04_25 — the 3 discoveries
• project_catala_explain_as_commercial_artifact — .docx commercial framing
• feedback_library_web_research_narrow_margins — 11th auto-deep-dive win pattern
• project_ai_vendor_commercial_model — pre-existing; updated with explanation-artifact reframing