Add CLARA agent workflow - triggered on request on PR.

[dosumis]

Functional spec:

Core CLARA workflow

• test atomic assertions against lit. Use ASTA snippet search + fallback to full text ASTA fails. Assertions only need validation against one of the refs (Lazy evaluation is good). Report - fails at top of report. - table of passing assertions under that. If any fails, report on papers that could not be accessed (if any).

• REquest on PR triggers:

  • ROBOT DIFF edit file changes on branch
  • Agent decides what to test:
    • If NTR - decompose def & relationships --> set of atomic assertions. --> core workflow
    • If new or changes relationships --> Check these relationships against refs with core workflow
    • If new or changed synonyms AND synonyms have refs on them - check synonyms against refs.

TBA: Link to draft implementation fro @dosumis

[ubyndr]

Background on the planned CLARA workflow rollout for this ticket.

The target behavior in this issue is broader than a single workflow change. The end state we are working toward is:

• trigger CLARA review on request from a PR
• run ROBOT diff on the branch edit-file changes
• decide what to validate from the PR diff
• for new term requests, decompose definitions and relationships into atomic assertions
• for changed relationships, validate those assertions against refs
• for changed synonyms that carry refs, validate those synonyms against refs
• run the core CLARA validation loop:
  • ASTA snippet search first
  • full-text fallback when needed
  • one supporting cited reference is sufficient
• produce a PR report with:
  • failures first
  • passing assertions in a table
  • inaccessible papers listed when failures remain

To make this manageable, the implementation is being phased.

Planned phases

Phase 1: Workflow scaffold and stage-1 extraction

This phase adds the GitHub Actions entry point and validates that we can run CLARA stage 1 on a PR. #3629

Scope:

• add a dedicated clara-review.yml workflow
• support /clara on PR comments
• support manual workflow_dispatch
• resolve PR refs
• check out the PR head
• install ROBOT and Python
• install clara_workflow
• run stage-1 extraction on src/ontology/cl-edit.owl
• upload changes.json
• post a minimal stage-1 summary comment to the PR

This phase is advisory only and does not yet perform literature validation.

Phase 2: Ticket-specific routing from stage-1 output

This phase will add logic that reads changes.json and selects what should actually be sent into CLARA validation.

Planned routing:

• detect NTR terms
• identify changed relationships, subclass axioms, and equivalent-class content
• identify changed synonyms that have attached refs
• ignore housekeeping and non-reviewable changes

This is the layer that translates a PR diff into the review rules described in this issue.

Phase 3: Core CLARA validation execution

This phase will add the actual CLARA review behavior.

Planned scope:

• decompose NTR definitions into atomic assertions
• convert relevant NTR relationships into atomic assertions
• validate changed relationships directly as atomic claims
• validate changed synonyms with refs directly against cited refs
• apply one-reference-is-enough semantics

Phase 4: Literature-access runtime

This phase will wire the workflow runtime to the literature-checking tools required by CLARA.

Planned scope:

• ASTA snippet search
• full-text retrieval fallback
• logging of tool calls
• explicit handling of unresolved access failures

Phase 5: Final PR report format

This phase will build the PR-facing CLARA report in the format requested here.

Planned output:

• failing assertions at the top
• passing assertions in a table
• inaccessible papers listed when failures remain

Phase 6: Hardening and cleanup

Final cleanup phase.

Planned scope:

• move routing/report logic into helper scripts where needed
• add tests for routing and report rendering
• refine permissions and failure handling
• clarify any remaining scope questions around which change types should enter CLARA review

Why phase the work

This ticket spans:

• GitHub Actions trigger design
• ontology diff extraction
• PR-to-review routing logic
• literature-validation tooling
• PR reporting

Phasing the work lets us validate the workflow wiring first, then add the CLARA-specific review behavior incrementally on top of a working base.