feat: native mergiraf tool — syntax-aware merge conflict resolution

[trotsky1997]

PRD: Native mergiraf Support

Overview / Problem Statement

Ra agents frequently trigger git operations (merge, rebase, cherry-pick) that produce conflict markers in files. Today agents fall back to generic bash to invoke mergiraf — forfeiting structured error handling, missing-binary guidance, and argv safety. Adding a native mergiraf tool brings syntax-aware merge conflict resolution into Ra's built-in tool catalog with the same reliability guarantees as jq, git, and other native wrappers.

Goals & Success Metrics

• Agents can invoke syntax-aware merge conflict resolution through a native Ra tool without using bash for the happy path.
• Agents receive structured, actionable error output when mergiraf is absent from PATH.
• All mergiraf invocations are argv-safe — no shell interpolation.
• Focused tests cover catalog registration, allow-list behavior, CLI argument construction, and error envelope behavior.
• README.md and spec/tools.md are updated to document the new tool.

User Personas & Stories

• As an autonomous coding agent, I want a structured mergiraf tool so that I can resolve merge conflicts without memorizing command syntax or relying on brittle shell pipelines.
• As an agent operator, I want mergiraf invocations to be bounded and argv-safe so that unattended agents cannot produce injection bugs through file paths.
• As a Ra maintainer, I want the tool to wrap the upstream binary narrowly so that Ra stays compatible with mergiraf updates without becoming a second implementation.

Functional Requirements

Priority	Requirement
Must	Add a built-in mergiraf tool supporting merge, solve, and languages actions.
Must	Execute all actions via argv-safe process spawning with no shell interpolation.
Must	Return a stable JSON envelope: ok, tool, action, exit_code, stdout, stderr, truncated, optional error.
Must	Return error.kind: "missing_mergiraf" with install guidance when the binary is absent.
Must	Bound all output via max_output_bytes; set truncated: true when clipped.
Must	Register via default_builtins; obey [tools].builtin allow-list semantics.
Must	Spawn locally even when an ACP host is attached (matching mise/just/wrkflw behavior).
Should	Accept --language, --compact, --allow-parse-errors flags on the merge action.
Won't	Implement mergiraf's tree-sitter parsing or conflict resolution logic in Rust.
Won't	Expose arbitrary args — keep the schema narrow in v1.

Non-Functional Requirements

• Keep the tool narrow and argv-safe, following existing native CLI wrapper conventions.
• Avoid unbounded output; large responses should be truncated with truncated: true.
• Do not make mergiraf a hard runtime dependency; missing binary must not break catalog startup.
• Maintain deterministic tests without requiring network access.

Design Notes

The tool adds src/tools/mergiraf.rs beside other built-ins, defines a typed MergirafAction enum, spawns the upstream mergiraf binary with Command::arg, and registers MergirafTool through default_builtins. The merge action invokes mergiraf merge <base> <ours> <theirs> (the git merge-driver invocation path); solve handles files with existing conflict markers; languages is read-only.

Implementation Split (suggested)

1. Tool contract — schema definition and result envelope types
2. Core implementation — MergirafTool with all three actions, output bounding, missing-binary guidance
3. Catalog registration — default_builtins + allow-list wiring
4. Documentation — README.md table row, spec/tools.md entry, spec/ra.toml.example
5. Tests — catalog, argv construction, envelopes, missing-binary, truncation

Related

OpenSpec change: openspec/changes/mergiraf-native-support/

[trotsky1997]

Completed by merged PR #38 (native mergiraf tool, docs, tests, and catalog registration).