feat(ops): PR Hedge Trim skill — automated CodeRabbit thread resolution

[POWERFULMOVES]

Summary

• New /pr-trim skill with 4-way thread classification (actionable / design-decision / false-positive / nitpick) and GraphQL resolveReviewThread mutation
• Core Python tool (pmoves/tools/pr_hedge_trim.py) with analyze, resolve, and report subcommands
• Make targets: pr-trim-analyze, pr-trim-resolve, pr-trim-report, pr-trim-batch
• NATS event schema (ops.pr.trim.completed.v1), FlOO$ chain integration, agent registry entry
• Gitignore pattern for runtime trim logs

Test plan

• py -3 pmoves/tools/pr_hedge_trim.py --help — CLI parses
• make -C pmoves -n pr-trim-analyze PR=1 — Make target resolves
• py -3 -c "import json; json.load(open('pmoves/contracts/topics.json'))" — Topics valid JSON
• py -3 -c "import yaml; yaml.safe_load(open('pmoves/configs/skill-pairings.yaml'))" — FlOO$ chain valid
• Battle-tested: 36 threads resolved across PRs feat(agentgym): EvoSwarm → AgentGym-RL → HuggingFace publisher pipeline #935-938 in batch trim session

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features

  • PR Hedge Trim CLI: analyze, classify, resolve, and report on PR review threads (full cycle and dry-run support)
  • New make targets to run analyze, resolve, report, and the complete trim cycle

• Documentation

  • Comprehensive PR Hedge Trim workflow docs with CLI usage and examples

• Chores

  • Registered PR Hedge Trim agent and added new event topics/schemas; integrated trim step into PR processing pipeline

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

[coderabbitai]

📝 Walkthrough

Walkthrough

Adds a PR Hedge Trim feature: new CLI tool to classify/fix PR review threads, NATS topic and JSON schemas for trim completion, agent and skill registry entries, make targets, docs, and packaging for producing JSON/Markdown trim artifacts and publishing ops.pr.trim.completed.v1 events.

Changes

Cohort / File(s)	Summary
Docs & NATS subjects .claude/commands/pr-trim.md, .claude/context/nats-subjects.md	Added PR Hedge Trim user documentation and NATS subject documentation for ops.pr.trim.completed.v1 (note: duplicated block present in nats-subjects.md).
Contracts & Topics pmoves/contracts/schemas/ops/pr.trim.completed.v1.schema.json, pmoves/contracts/schemas/ops/pr.monitor.completed.v1.schema.json, pmoves/contracts/topics.json	Added JSON Schema for PR trim completion and PR monitor completion events; registered new topics ops.pr.trim.completed.v1 and ops.pr.monitor.completed.v1 in topics.json.
Agent & Skill registry pmoves/config/agent_registry.yaml, pmoves/configs/skill-pairings.yaml	Registered pr_hedge_trim agent with publish/subscribe topics and resilience/invocation settings; inserted pr-hedge-trim skill into pr-monitor pipeline and updated downstream dependencies and skill_sources mapping.
Tooling & Build pmoves/tools/pr_hedge_trim.py, pmoves/mk/preflight.mk, .gitignore	Added new CLI tool implementing classification, fetch/resolve GraphQL operations, report serialization, and subcommands (analyze/resolve/report); added make targets pr-trim-analyze, pr-trim-resolve, pr-trim-report, pr-trim; added ignore pattern for pmoves/docs/logs/pr_trim_*.json.

Sequence Diagram

sequenceDiagram
    autonumber
    participant User as "User"
    participant Make as "Make Target\n(pr-trim)"
    participant CLI as "PR Hedge Trim CLI\npr_hedge_trim.py"
    participant GH as "GitHub GraphQL API"
    participant NATS as "NATS Broker"

    User->>Make: make pr-trim PR=123 REPO=org/repo
    Make->>CLI: analyze --pr 123
    CLI->>GH: Query unresolved review threads
    GH-->>CLI: Threads + comments
    CLI->>CLI: Classify threads
    CLI-->>Make: Save JSON artifact / show summary

    Make->>CLI: resolve --pr 123
    CLI->>GH: Mutation: resolve selected threads
    GH-->>CLI: Mutation responses
    CLI-->>Make: Resolved count

    Make->>CLI: report --pr 123
    CLI->>CLI: Generate Markdown report
    CLI-->>Make: Report output

    CLI->>NATS: Publish ops.pr.trim.completed.v1 (JSON payload)
    NATS-->>Make: Deliver event to subscribers

Loading

Estimated Code Review Effort

🎯 4 (Complex) | ⏱️ ~50 minutes

Poem

🐇 I hop through threads both long and slim,
I sort the nitpicks, find what's grim,
False flags pruned, design notes kept,
Actionable tasks neatly swept,
A tidy hedge, a signed-off whim. 🌿

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately describes the main feature: a new PR Hedge Trim skill for automated CodeRabbit thread resolution with classification capabilities.
Description check	✅ Passed	The description covers all required sections: Summary with key changes, Testing with validated commands and batch results, Required Checks checklist, and Reviewer Notes placeholder.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

• 📝 Generate docstrings (stacked PR)
• 📝 Generate docstrings (commit on current branch)

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch feat/pr-hedge-trim-skill

📝 Coding Plan

• Generate coding plan for human review comments

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 6

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@pmoves/config/agent_registry.yaml`:
- Around line 720-723: Agent registry subscribes to the subject
ops.pr.monitor.completed.v1 but that subject is missing from the contracts
mapping; open pmoves/contracts/topics.json and add a new topic entry for
"ops.pr.monitor.completed.v1" following the same shape as other topics (subject
name, version, schema/description/owner fields used in your JSON contract
conventions) so the nats subscription in agent_registry.yaml (nats.subscribes
entry) is declared in the contracts mapping and passes validation.

In `@pmoves/contracts/schemas/ops/pr.trim.completed.v1.schema.json`:
- Around line 7-59: The schema
pmoves/contracts/schemas/ops/pr.trim.completed.v1.schema.json currently requires
agent_id and resolved and forbids extra fields, but _serialize_report in
pmoves/tools/pr_hedge_trim.py emits resolved_count, unresolved_threads, and
threads and omits agent_id; fix by aligning the serializer to the schema: modify
_serialize_report to emit "resolved" (map from resolved_count), include
"agent_id" (use the agent identity available in the function/context), and stop
emitting unknown fields "unresolved_threads" and "threads" (or if those fields
are required for consumers, instead add them to the schema and update "required"
and "properties"); ensure the final payload validates against the schema before
publishing via services/common/events.py.

In `@pmoves/contracts/topics.json`:
- Around line 222-226: The topic "ops.pr.trim.completed.v1" lists
"publisher-discord" as a subscriber but that subject is not included in the
default DISCORD_SUBJECTS used by the publisher-discord service; either add
"ops.pr.trim.completed.v1" to the default DISCORD_SUBJECTS list used in the
publisher-discord startup (ensure the DISCORD_SUBJECTS env var or DEFAULT list
in publisher-discord main.py includes this string and that docker-compose.yml
sets the matching default), or remove "publisher-discord" from the subscriber
array for "ops.pr.trim.completed.v1" in topics.json so the config and defaults
stay consistent.

In `@pmoves/tools/pr_hedge_trim.py`:
- Around line 336-345: The resolve_thread function currently assumes
result["data"]["resolveReviewThread"] is always a dict and will crash when
GraphQL returns null; update resolve_thread to check that result is a dict, then
that data.get("resolveReviewThread") is not None before accessing
.get("thread"), log the full result/error including thread_id when
resolveReviewThread is null or the mutation failed, and return False on any
failure; then update cmd_resolve to inspect the boolean returned by
resolve_thread (instead of treating the subprocess as success) and exit non-zero
when resolve_thread returns False so batch jobs can detect failed mutations;
reference symbols: resolve_thread, cmd_resolve, _run_json, thread_id.
- Around line 162-181: The default branch in classify_comment always returns
"nitpick" because it never knows whether the author is a bot; change the
classify_comment signature to accept an is_bot: bool (e.g., def
classify_comment(body: str, is_bot: bool) -> str), preserve the existing token
checks using FALSE_POSITIVE_TOKENS, DESIGN_TOKENS, NITPICK_TOKENS,
ACTIONABLE_TOKENS, and replace the final return with return "nitpick" if is_bot
else "actionable"; update all call sites to pass the caller's is_bot value so
human comments default to "actionable".
- Around line 236-250: The loop currently uses `break` when `_run_json(cmd)` or
nested keys (`payload`, `data`, `repository`, `pr`, `review_threads`) are
missing, which masks errors as "0 threads"; instead, fail fast by replacing
those `break` statements with raising a descriptive exception (e.g.,
RuntimeError or ValueError) that includes the `cmd` and the malformed
`payload`/missing-key name; apply the same change in the second occurrence (the
block around `review_threads` at the later location) so both pagination checks
surface malformed GraphQL responses or auth issues immediately.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 74c5651c-d421-4cf0-a5d1-e32a9cdbe8a9

📥 Commits

Reviewing files that changed from the base of the PR and between b9d4eec and 9179e2e.

📒 Files selected for processing (9)

• .claude/commands/pr-trim.md
• .claude/context/nats-subjects.md
• .gitignore
• pmoves/config/agent_registry.yaml
• pmoves/configs/skill-pairings.yaml
• pmoves/contracts/schemas/ops/pr.trim.completed.v1.schema.json
• pmoves/contracts/topics.json
• pmoves/mk/preflight.mk
• pmoves/tools/pr_hedge_trim.py

[coderabbitai]

Actionable comments posted: 2

♻️ Duplicate comments (1)

pmoves/tools/pr_hedge_trim.py (1)

311-313: ⚠️ Potential issue | 🟠 Major

Raise on missing pageInfo.

Most of fetch_threads() now fails fast on malformed GraphQL responses, but this last break still turns a bad payload into a partial-success analysis/report.

🛠️ Proposed fix

         page_info = review_threads.get("pageInfo")
         if not isinstance(page_info, dict):
-            break
+            raise RuntimeError("unexpected GraphQL response: missing 'pageInfo'")

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@pmoves/tools/pr_hedge_trim.py` around lines 311 - 313, fetch_threads
currently breaks out of the loop when page_info is not a dict, turning a
malformed GraphQL response into a silent partial success; replace the break with
an explicit exception (e.g., raise ValueError or RuntimeError) so callers fail
fast. In the fetch_threads function, where page_info =
review_threads.get("pageInfo") and the code checks isinstance(page_info, dict),
raise a descriptive error that includes context (e.g., the offending
review_threads or its keys) instead of using break so upstream code can
handle/log the malformed payload.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@pmoves/contracts/schemas/ops/pr.trim.completed.v1.schema.json`:
- Around line 62-68: The "threads" array items are currently unconstrained
(items: { "type": "object" }), allowing malformed thread objects; update
pmoves/contracts/schemas/ops/pr.trim.completed.v1.schema.json to precisely
validate the shape emitted by the serializer in pmoves/tools/pr_hedge_trim.py:
replace the loose items schema with an object schema that lists the exact
per-thread properties (and types), marks required fields, and validates nested
comment fields (with their properties) so downstream consumers get strict
contract protection. Ensure property names and nesting match the fields produced
by pr_hedge_trim.py and include any enums/format constraints used by the
serializer.

In `@pmoves/tools/pr_hedge_trim.py`:
- Around line 595-599: The post-check treats any remaining targeted threads as a
failure even during a dry run; update the return logic in the block that calls
cmd_resolve so that when args.dry_run is True the function returns 0 (success)
even if target_threads exist; specifically modify the code using cmd_resolve,
fetch_threads and target_threads to return 1 only when not args.dry_run and
target_threads is non-empty, otherwise return 0.

---

Duplicate comments:
In `@pmoves/tools/pr_hedge_trim.py`:
- Around line 311-313: fetch_threads currently breaks out of the loop when
page_info is not a dict, turning a malformed GraphQL response into a silent
partial success; replace the break with an explicit exception (e.g., raise
ValueError or RuntimeError) so callers fail fast. In the fetch_threads function,
where page_info = review_threads.get("pageInfo") and the code checks
isinstance(page_info, dict), raise a descriptive error that includes context
(e.g., the offending review_threads or its keys) instead of using break so
upstream code can handle/log the malformed payload.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 96548749-40be-4762-be60-48eb3581fa3e

📥 Commits

Reviewing files that changed from the base of the PR and between 9179e2e and 5de064b.

📒 Files selected for processing (4)

• pmoves/contracts/schemas/ops/pr.monitor.completed.v1.schema.json
• pmoves/contracts/schemas/ops/pr.trim.completed.v1.schema.json
• pmoves/contracts/topics.json
• pmoves/tools/pr_hedge_trim.py