Add CLARA review workflow (issue #3778)

[ubyndr]

Summary

Ports cell-ontology's /clara PR-review workflow to uberon, using the external Cellular-Semantics/clara_workflow package for stage-1 extraction (robot diff → changes.json) and stage-2/3 literature verification of routed targets. Closes/addresses #3778.

• New .github/workflows/clara-review.yml, triggered by a /clara PR comment or manual dispatch.
• New src/scripts/clara_select_targets.py, copied unchanged from cell-ontology — it's ontology-agnostic routing logic over changes.json, no CL-specific assumptions.
• New .github/clara-mcp.json, a minimal MCP config scoped to just Asta_semanticscholar + artl-mcp for this workflow (kept separate from the root dev .mcp.json, which also declares ols4/playwright that we don't want an unattended CI agent to have, and which needs browser binaries not on the runner).

Deviations from the CL original (and why)

• --edit-file src/ontology/uberon-edit.obo (OBO, not OWL). robot diff/robot convert detect format from content, not file extension, so the extractor works against OBO input without modification.
• --catalog src/ontology/catalog-v001.xml passed to the stage-1 extractor. Required here, not just a nice-to-have: one of uberon's owl:imports PURLs currently 404s, and ROBOT resolves every import over the network by default. The catalog (ODK-managed, already checked into this repo) redirects every import to the locally-committed file it maps to, so resolution is fully offline and immune to the broken PURL. This also happens to fix definition_refs() for OBO edit files (see "Upstream fixes" below) — it needs the same catalog to convert the edit file to functional syntax without hitting the same broken import.
• ROBOT's wrapper script now honors $ROBOT_JAVA_ARGS (set to -Xmx9G on the extractor step), matching the heap size uberon's own diff.yml/qc.yml already use for robot on this ontology. The CL wrapper hardcodes no heap flag at all, which risks OOM here given how much larger uberon is than CL.
• CLARA_WORKFLOW_REF pinned to a commit rather than tracking main, per that repo's own adoption guidance.

Upstream fixes (Cellular-Semantics/clara_workflow#8, merged)

Both gaps originally flagged in this PR are now fixed upstream, and CLARA_WORKFLOW_REF is pinned to the merge commit:

1. definition_refs() returning nothing for OBO edit files — fixed by converting the edit file to OWL functional syntax (via robot convert, using the same catalog) before parsing, instead of reading raw OBO text.
2. The import-resolution failure found while testing this PR (not originally listed as a known gap — discovered afterward) — fixed by the catalog support above.

Still outstanding, not fixed: agent_instructions.md still uses cell-type-specific wording (core = "the subject is the cell type itself", "Preserve the cell-type subject...") that will show up in reports/verdicts for uberon's anatomical terms. The cell_id/term_id duplication was cleaned up (verdicts.json now uses a single term_id field, matched in this PR's summary-comment step), but the prose itself wasn't re-addressed after an earlier rollback. Tracked as a follow-up.

Validation done so far

• Manually verified robot diff correctly parses OBO content regardless of file extension.
• Ran the real, merged clara_workflow package's stage-1 CLI (python -m clara_workflow.stage1.extract ... --catalog src/ontology/catalog-v001.xml) against real pushed commits on this branch, including a throwaway definition edit + fabricated DOI on UBERON:0004177 (added, tested, then reverted — see commit history). Confirmed: catalog resolves all of uberon's real imports offline (including the one with the broken PURL), changes.json/routing.json come out correct, and definition_refs is now populated for OBO input.
• Not yet done: an actual GitHub Actions run. workflow_dispatch and the /clara comment trigger both require the workflow file to exist on the default branch, so this can't be exercised live until this PR merges. Planning a workflow_dispatch dry run against a small test PR right after merging, before treating /clara as generally available.

Before this can run

• ASTA_API_KEY secret still needs to be added to this repo — not set by this PR. Without it, stage-2/3 verification will fail; stage-1 extraction and routing will still work and still post a summary comment.

Test plan

• Workflow YAML, MCP JSON, and Python script all validated to parse correctly.
• robot diff/robot convert with --catalog validated against the real uberon repo, including its actual broken import.
• Full stage-1 extractor + routing script run via the real merged clara_workflow package against real git commits on this branch.
• ASTA_API_KEY secret added to repo settings.
• Live workflow_dispatch run right after merge, against a small test PR, to confirm stage 1 → routing → stage 2/3 → summary comment end-to-end in actual GitHub Actions.

Signed-off-by: @ai4c-agent

🤖 Generated with Claude Code

[github-actions]

This PR modifies some logical definitions. See details below:

Number of classes with modified logical definitions: 3

http://purl.obolibrary.org/obo/UBERON_8930105

No changes in inferred subclasses.

http://purl.obolibrary.org/obo/UBERON_8930106

No changes in inferred subclasses.

http://purl.obolibrary.org/obo/UBERON_8930191

Removed subclasses: 2

• ring fiber
• splenic red pulp stroma

[ai4c-reviewer]

Claude finished @ubyndr's task in 43s —— View job

---

PR review complete

I submitted a REQUEST_CHANGES review on this PR. I reviewed the diff by reading the files only and did not run the workflow.

• 🔴 Author gate: the /clara comment trigger has no author_association check. Anyone can start a run that has the OAuth and Asta secrets and reads untrusted PR content.
• 🟡 Concurrency: the group is set at workflow level with cancel-in-progress: true. Any comment on the PR, even a non-/clara one, can cancel a running review.
• 🟡 --left ref: it uses the base branch tip (baseRefOid) instead of the merge-base. If the branch is behind master, unrelated master changes show up in the diff.
• 🔵 Suggestions:
  • Pass inputs.pr through env: instead of interpolating it into the shell.
  • Fix the uv tool dir bin path.
  • Pin the ROBOT, uv and artl-mcp versions.

I made no code changes. The ontology-specific checks don't apply, because the PR touches no terms.

[ai4c-reviewer]

• Hierarchy and parents are consistent (n/a, no ontology changes)
• Definitions and supporting references look adequate (n/a)
• Obsolete or replacement handling is safe (n/a)
• OBO and ODK conventions appear preserved
• No obvious CI, auth, or workflow regression

🔴 CRITICAL: /clara can be triggered by anyone, with secrets, over untrusted PR content

clara-review.yml:49-53 only checks that the comment starts with /clara. Any GitHub user can comment on any PR, including fork PRs, and start a run that has CLAUDE_CODE_OAUTH_TOKEN, ASTA_API_KEY and a write-scoped GITHUB_TOKEN.
The job then checks out the PR head (line 91) and gives Claude Code the PR's content. That includes the PR's own CLAUDE.md and ontology text, which is a prompt-injection surface. The run also shells out to gh.
Gate the job on github.event.comment.author_association being OWNER, MEMBER or COLLABORATOR. Also consider refusing PRs whose head repo differs from the base repo.

🟡 IMPORTANT: concurrency group cancels running reviews on any comment

clara-review.yml:43-45 builds the concurrency group from github.event.issue.number at workflow level. Any comment on the PR, even a non-/clara one, joins the group.
With cancel-in-progress: true, an ordinary comment posted mid-run cancels the CLARA run. That is because the workflow starts before the job-level if skips it. Either scope the group to the job so only /clara runs join it, or use cancel-in-progress: false.

🟡 IMPORTANT: --left is the base branch tip, not the merge-base

clara-review.yml:127 and :81 use baseRefOid, which is the current master tip. If the PR branch is behind master, the diff includes unrelated master changes as reverse edits. Use git merge-base <base> <head> for --left. Full history is already fetched.

🔵 Suggestions

• clara-review.yml:59: ${{ inputs.pr }} is interpolated directly into the shell. Pass it via env: and validate that it is numeric. The same applies to the other ${{ }} values inside run: blocks.
• clara-review.yml:176: $(uv tool dir)/bin is not the tool bin directory. uv tool dir --bin is. This is harmless today because the MCP config uses uv tool run, but the line is misleading.
• clara-review.yml:96: ROBOT is downloaded from releases/latest. Pin a version, as you did for CLARA_WORKFLOW_REF. Pin uv and artl-mcp versions too.
• clara-review.yml:225: if-no-files-found: warn is fine. The summary step already tolerates a missing runs/.
• The follow-up you already noted (cell-type wording in agent_instructions.md) is worth tracking as an issue.

Merge recommendation: fix the author gate and the concurrency group before merge. The ASTA_API_KEY secret and the live dispatch run remain outstanding, as noted in the PR description.

Signed: @ai4c-agent

[ai4c-reviewer]

Claude finished @ubyndr's task in 29s —— View job

---

Re-review of the CLARA workflow after 385e5b9

I read the current clara-review.yml. I did not run the workflow. The PR touches no ontology terms, so the hierarchy, definition and obsoletion checks don't apply. I can't submit a formal PR review, so this comment is the review.

• Hierarchy and parents are consistent (n/a)
• Definitions and supporting references look adequate (n/a)
• Obsolete or replacement handling is safe (n/a)
• OBO and ODK conventions appear preserved
• No obvious CI, auth, or workflow regression (one 🟡 left, see below)

Previous findings

• Author gate: fixed. check-authorization (lines 48-119) checks the commenter against .github/ai-controllers.json, which exists. It also refuses fork PRs, and the checkout in that job is the default branch only.
• Concurrency: fixed. The group is now on the review job (lines 130-132), and check-authorization skips non-/clara comments before they reach it.
• inputs.pr: now passed through env: and checked as an integer.
• uv tool dir --bin: fixed.

Remaining

🟡 IMPORTANT: --left is still the base branch tip, not the merge-base.

• Lines 150-153 and 198 use baseRefOid.
• If the PR branch is behind master, unrelated master changes show up in the diff as reverse edits. That misroutes targets and wastes Asta and Claude calls.
• Full history is already fetched (fetch-depth: 0), so it's a small change. Compute mb=$(git merge-base "$base" "$head"), use it for --left, and report it as the base SHA in the summary.

🔵 Suggestions

• Line 168: ROBOT is downloaded from releases/latest. Pin a version.
• Lines 180 and 245: pin uv and artl-mcp versions.
• Line 249: the --help | head check can pass or fail on head's exit status, not on artl-mcp's. Consider set -o pipefail.
• The agent_instructions.md cell-type wording follow-up is worth its own issue.

Merge recommendation

🟡 Fix the merge-base before merge. Everything else in the earlier review is addressed. The ASTA_API_KEY secret and the live workflow_dispatch run are still outstanding, as the PR description says.

Signed: @ai4c-agent

[ai4c-reviewer]

Claude finished @ubyndr's task in 30s —— View job

---

Re-review after d1cb998 (merge-base fix)

I read clara-review.yml lines 125-215. I did not run the workflow. The PR touches no ontology terms, so the hierarchy, definition and obsoletion checks don't apply. I can't submit a formal PR review, so this comment is the review.

• Hierarchy and parents are consistent (n/a)
• Definitions and supporting references look adequate (n/a)
• Obsolete or replacement handling is safe (n/a)
• OBO and ODK conventions appear preserved
• No obvious CI, auth, or workflow regression

Previous findings

• Author gate, concurrency, inputs.pr, uv tool dir --bin: fixed in 385e5b9, as noted in the last re-review.
• --left merge-base: fixed.
  • Lines 150-165 take the base tip and head SHA from gh pr view. They then call compare/${base_tip}...${head_sha} and use .merge_base_commit.sha as steps.refs.outputs.base.
  • That is the correct merge-base for a three-dot compare.
  • Line 207 passes it as --left, and fetch-depth: 0 means the commit is available locally.

Remaining 🔵 suggestions (non-blocking)

• Line 177: ROBOT comes from releases/latest. Pin a version.
• Lines 189 and 254: pin the uv and artl-mcp versions.
• Line 260: uv tool run artl-mcp --help 2>&1 | head -5 reports head's exit status, not artl-mcp's. Add set -o pipefail.
• The agent_instructions.md cell-type wording follow-up is worth its own issue.

Merge recommendation

🟢 No blocking issues remain, so I would approve. The ASTA_API_KEY secret and the live workflow_dispatch run are still outstanding, as the PR description says. I can't submit the approval myself.

Signed: @ai4c-agent
· branch issue-3778

[ai4c-reviewer]

Claude finished @ubyndr's task in 45s —— View job

---

Re-review after d6da5ab (track_progress: false)

I read the diff of d6da5ab only. It changes one line in clara-review.yml, plus a comment. I did not run the workflow. I can't submit a formal PR review or approval, so this comment is the review.

• Hierarchy and parents are consistent (n/a, no ontology terms touched)
• Definitions and supporting references look adequate (n/a)
• Obsolete or replacement handling is safe (n/a)
• OBO and ODK conventions appear preserved
• No obvious CI, auth, or workflow regression

Findings

• track_progress: false: no security or auth impact. The author gate (check-authorization), the job-level concurrency group and the merge-base --left from earlier commits are unchanged. The explanatory comment in the file is accurate and useful. I did not check the claude-code-action mode-detector claim against its source. The commit message reports a stage 2/3 failure that this fixed, but I did not confirm that.
• One thing to check on the first live run: with track_progress: false, the action won't post its own progress comment. The workflow's summary-comment step should be the only PR feedback. That matches the PR description.

Remaining 🔵 suggestions (non-blocking, unchanged)

• Pin the ROBOT download (releases/latest), uv and artl-mcp versions.
• Add set -o pipefail to the artl-mcp --help | head check.
• Open a separate issue for the cell-type wording in agent_instructions.md.

Merge recommendation

🟢 No blocking issues, so I would approve. The ASTA_API_KEY secret and the live workflow_dispatch run are still outstanding, as the PR description says.

Signed: @ai4c-agent
· branch issue-3778

[ai4c-reviewer]

Claude finished @ubyndr's task in 30s —— View job

---

Re-review after 6c46aff (TEMP DEBUG show_full_output)

I read the diff of 6c46aff only. It adds show_full_output: true to the claude-code-action step in clara-review.yml, plus a comment. I did not run the workflow. I can't submit a formal PR review or approval, so this comment is the review.

• Hierarchy and parents are consistent (n/a, no ontology terms touched)
• Definitions and supporting references look adequate (n/a)
• Obsolete or replacement handling is safe (n/a)
• OBO and ODK conventions appear preserved
• No obvious CI, auth, or workflow regression (one 🟡 left, see below)

Findings

🟡 IMPORTANT: show_full_output: true must not be merged.

• It prints the full agent transcript to the Actions log. That includes tool inputs and outputs, PR content, and MCP responses. Logs on a public repo are readable by anyone.
• The step has the OAuth token and ASTA_API_KEY in its environment. The action masks known secrets, but the transcript still includes untrusted PR content and whatever the tools return.
• The change is clearly marked TEMP and is fine for a debugging run. Please revert it before merge, ideally in the same push that fixes the stage 2/3 failure. Only trigger runs while it is on from trusted PRs, which the check-authorization gate already enforces.

🔵 Debugging hint (non-blocking). The claude subprocess fails in about 500 ms with no turns. Two things are worth checking in the full output:

• Whether --mcp-config .github/clara-mcp.json fails to start. The artl-mcp server is launched via uv tool run, and a missing ASTA_API_KEY could break the Asta server on startup.
• Whether the claude_args model or tool flags are rejected by the CLI.

Remaining 🔵 suggestions (non-blocking, unchanged)

• Pin the ROBOT download (releases/latest), uv and artl-mcp versions.
• Add set -o pipefail to the artl-mcp --help | head check.
• Open a separate issue for the cell-type wording in agent_instructions.md.

Merge recommendation

🟡 Not ready while the debug flag is on. Once it is removed and stage 2/3 works, I would approve. The ASTA_API_KEY secret and the live workflow_dispatch run are still outstanding, as the PR description says.

Signed: @ai4c-agent
· branch issue-3778

[ai4c-reviewer]

Claude finished @ubyndr's task in 25s —— View job

---

Re-review after 70dfeea (--model claude-sonnet-5 pin)

I read the diff of 70dfeea and grepped the current clara-review.yml. I did not run the workflow. I can't submit a formal PR review or approval, so this comment is the review.

• Hierarchy and parents are consistent (n/a, no ontology terms touched)
• Definitions and supporting references look adequate (n/a)
• Obsolete or replacement handling is safe (n/a)
• OBO and ODK conventions appear preserved
• No obvious CI, auth, or workflow regression (one 🟡 left, see below)

Findings

🟡 IMPORTANT: the TEMP DEBUG show_full_output: true is still on (clara-review.yml:282-285). The commit message says the real error is now known, so the flag has done its job. It prints the full agent transcript to a public Actions log, including PR content and tool and MCP output. Remove it in this PR before merge.

🔵 Model pin is unverified.

• The commit message says claude-sonnet-5-5 doesn't exist and claude-sonnet-5 is the valid id. I can't confirm that. My environment lists claude-sonnet-5-5 as a valid Sonnet 5.5 id.
• The logged error says the model "may not exist or you may not have access to it". So the cause may be that the OAuth token has no access to that model, not that the id is wrong.
• If claude-sonnet-5 also returns model_not_found on the next run, check the token's model access. Don't keep changing the id.
• Pinning a model is reasonable for reproducibility. Consider adding a comment saying why the id was chosen.

Remaining 🔵 suggestions (non-blocking, unchanged)

• Pin the ROBOT download (releases/latest), uv and artl-mcp versions.
• Add set -o pipefail to the artl-mcp --help | head check.
• Open a separate issue for the cell-type wording in agent_instructions.md.

Merge recommendation

🟡 Not ready while the debug flag is on. Once it's removed and a stage 2/3 run succeeds, I would approve. The ASTA_API_KEY secret and the live workflow_dispatch run are still outstanding, as the PR description says.

Signed: @ai4c-agent
· branch issue-3778

[ai4c-reviewer]

Claude finished @ubyndr's task in 19s —— View job

---

Re-review after 1ca3b41 (remove show_full_output)

I read the diff of 1ca3b41 and grepped the current clara-review.yml. I did not run the workflow. I can't submit a formal PR review or approval, so this comment is the review.

• Hierarchy and parents are consistent (n/a, no ontology terms touched)
• Definitions and supporting references look adequate (n/a)
• Obsolete or replacement handling is safe (n/a)
• OBO and ODK conventions appear preserved
• No obvious CI, auth, or workflow regression

Findings

• Debug flag: fixed. show_full_output is gone from the workflow (grep finds no match), so the agent transcript no longer goes to the public Actions log. That was the last 🟡.
• Model pin: --model claude-sonnet-5 is still at line 285. I can't confirm from here that this id is valid. If the next run returns model_not_found again, check the OAuth token's model access rather than changing the id again.

Remaining 🔵 suggestions (non-blocking, unchanged)

• Pin the ROBOT download (releases/latest), uv and artl-mcp versions.
• Add set -o pipefail to the artl-mcp --help | head check.
• Open a separate issue for the cell-type wording in agent_instructions.md.

Merge recommendation

🟢 No blocking issues remain, so I would approve. The ASTA_API_KEY secret and the live workflow_dispatch run are still outstanding, as the PR description says.

Signed: @ai4c-agent
· branch issue-3778

[ai4c-reviewer]

Claude finished @ubyndr's task in 37s —— View job

---

Re-review after eb020bf (bump CLARA_WORKFLOW_REF)

I read the diff of eb020bf only. It changes one line, the pinned CLARA_WORKFLOW_REF in clara-review.yml. I did not run the workflow, and I did not check that 5c61100b… is the merge commit of clara_workflow#9. I can't submit a formal review or approval, so this comment is the review.

• Hierarchy and parents are consistent (n/a, no ontology terms touched)
• Definitions and supporting references look adequate (n/a)
• Obsolete or replacement handling is safe (n/a)
• OBO and ODK conventions appear preserved
• No obvious CI, auth, or workflow regression

Findings

• The ref is still a full 40-character commit SHA, so the pin stays immutable. The change fits the commit message: the fix is for CURIE colons in runs/{term_id}/ artifact paths, which made upload-artifact fail.
• The author gate, the job-level concurrency group, the merge-base --left and the removal of the debug flag are all unchanged from earlier reviews.
• Check on the first live run: confirm that the artifact upload succeeds and that the summary-comment step runs. The commit says that step was silently skipped before.

Remaining 🔵 suggestions (non-blocking, unchanged)

• Pin the ROBOT download (releases/latest), uv and artl-mcp versions.
• Add set -o pipefail to the artl-mcp --help | head check.
• Open a separate issue for the cell-type wording in agent_instructions.md.
• If the next run returns model_not_found for --model claude-sonnet-5, check the OAuth token's model access rather than changing the id again.

Merge recommendation

🟢 No blocking issues, so I would approve. The ASTA_API_KEY secret and the live workflow_dispatch run are still outstanding, as the PR description says.

Signed: @ai4c-agent
· branch issue-3778

[ai4c-reviewer]

Claude finished @ubyndr's task in 37s —— View job

---

Re-review after 2988955 (port CL fixes: MCP config, track_progress)

I read the diff of 2988955 and grepped clara-review.yml. I did not run the workflow and did not open the external .mcp.json at the pinned ref. I can't submit a formal review or approval, so this comment is the review.

• Hierarchy and parents are consistent (n/a, no ontology terms touched)
• Definitions and supporting references look adequate (n/a)
• Obsolete or replacement handling is safe (n/a)
• OBO and ODK conventions appear preserved
• No obvious CI, auth, or workflow regression (one 🔵 note below)

Findings

• CLARA_WORKFLOW_REF is still a full 40-char SHA, so the pin stays immutable. I did not verify that 234ac67… includes clara_workflow#10.
• MCP config now comes from clara_workflow_ref/.mcp.json. The checkout at line 196 uses path: clara_workflow_ref, so the file should exist at that path when the step runs. The pinned SHA keeps it versioned, and the old .github/clara-mcp.json is removed with no remaining references.
• 🔵 Trust note: the MCP servers, and so the commands the action launches, are now defined by an external repo. That is acceptable because the ref is pinned, but bumping the ref should be reviewed as a code change. Check on the first live run that the file still declares artl-mcp (installed at line 254) and reads ASTA_API_KEY (env at line 268).
• track_progress is back to ${{ github.event_name == 'issue_comment' }}. This reverses d6da5ab. I did not verify the cell-ontology run cited in the comment. The author gate, job-level concurrency and merge-base --left are unchanged. With tag mode, the action may post its own progress comment in addition to the summary step, which is only cosmetic.

Remaining 🔵 suggestions (non-blocking, unchanged)

• Pin the ROBOT download (releases/latest), uv and artl-mcp versions.
• Add set -o pipefail to the artl-mcp --help | head check (line 260).
• Open a separate issue for the cell-type wording in agent_instructions.md.

Merge recommendation

🟢 No blocking issues, so I would approve. The ASTA_API_KEY secret and the live workflow_dispatch run are still outstanding, as the PR description says.

Signed: @ai4c-agent
· branch issue-3778

[ai4c-reviewer]

Claude finished @dosumis's task in 29s —— View job

---

Re-review of the CLARA workflow (current HEAD, c586f3f)

I checked the diff stat and grepped clara-review.yml. I did not run the workflow. I can't submit a formal PR review or approval, so this comment is the review.

• Hierarchy and parents are consistent (n/a, no ontology terms touched)
• Definitions and supporting references look adequate (n/a)
• Obsolete or replacement handling is safe (n/a)
• OBO and ODK conventions appear preserved
• No obvious CI, auth, or workflow regression

Findings

• The author gate still reads .github/ai-controllers.json (clara-review.yml:90).
• CLARA_WORKFLOW_REF is still a full commit SHA (line 25).
• The MCP config still comes from the pinned clara_workflow_ref/.mcp.json (line 290).
• The PR changes only the two expected files: the workflow and clara_select_targets.py. The latest commit is a merge of master, so I found nothing new to flag.

Remaining 🔵 suggestions (non-blocking, unchanged)

• Pin the ROBOT download (releases/latest, line 177), uv and artl-mcp versions.
• Add set -o pipefail to the artl-mcp --help | head check.
• Open a separate issue for the cell-type wording in agent_instructions.md.
• If a run returns model_not_found for --model claude-sonnet-5 (line 289), check the OAuth token's model access.

Merge recommendation

🟢 No blocking issues, so I would approve. dosumis has already approved. The ASTA_API_KEY secret and the live workflow_dispatch run are still outstanding, as the PR description says.

Signed: @ai4c-agent
· branch issue-3778