feat(python): Research Hive v0 roles + capability policy (#93)

Merged
RM
2mo ago
+3550-37

User description

Summary

Implements GitHub rmems/worktrees-hives#93: declarative Research Hive roles as fail-closed capabilities, not model personas.

  • Versioned ResearchRole / ResearchRoleCapabilities (schema v1)
  • Four v0 catalog roles: research_coordinator, experiment_agent, verification_agent, artifact_agent
  • assert_role_command_allowed composes with existing assert_command_allowed (never-merge still wins)
  • Tests: a read-only verifier cannot git commit / add / apply
  • RoleBinding lets two model/provider identities share one role; binding_metadata records role + model

No CLI, no lab run wiring, no Rust. Later orchestration (rmems/worktrees-hives#94/rmems/worktrees-hives#95) must call the gate.

Built with superpowers subagent-driven-development (one implementer + spec review + quality review per task).

Issue

Fixes rmems/worktrees-hives#93
Linear: rmems/worktrees-hives#93

Test plan

  • python3 -m pytest -q — 780 passed
  • python3 -m ruff check src tests
  • python3 -m mypy --config-file pyproject.toml
  • CI on this PR

Notes for babysit

  • Known residuals: command classification is an explicit list (git commit/add/apply/...); unclassified wrappers such as sh -c 'git commit' add no extra role capability (lab/Rust still apply). #94 should call the gate on structured argv, not raw shells.
  • Agent: grok-4.6 (controller + SDD subagents)
  • Head SHA: b913b87ac3104008d6539541e4dccb7ff9372d08

< />!NOTE< /> Medium Risk
New policy surface for agent command authorization; enforcement is opt-in until orchestration calls the gate, and classification is an explicit argv list (shell wrappers may bypass role checks).

Overview
Introduces versioned Research Hive role contracts (schema v1) as declarative capability limits—not model personas—via new worktrees_hives.research_roles, with ResearchRoleValidationError and RoleCapabilityError (ROLE_CAPABILITY_DENIED).

Adds a v0 catalog of four roles (research_coordinator, experiment_agent, verification_agent, artifact_agent) plus docs/examples/research-roles-v0.json. Omitted capability keys default to denied; verification_agent records must_be_independent_of: experiment_author.

assert_role_command_allowed runs existing lab_run.assert_command_allowed first, then classify_command maps argv (git mutators, pytest/cargo test, hive lab subcommands) to required capabilities. Read-only verifiers are blocked from git commit/add/apply and from launching lab runs.

RoleBinding and binding_metadata attach provider/model/agent identity to the same role contract. Public exports land in worktrees_hives.__init__; docs/json-contract.md documents data.research_role and data.role_binding. No CLI or lab run wiring yet—rmems/worktrees-hives#94/rmems/worktrees-hives#95 must call the gate.

Reviewed by Cursor Bugbot for commit 336d3f86b7828c1a34f466321d82f11b2d31cc46. Bugbot is set up for automated code reviews on this repo. Configure here.

Summary by cubic

Adds a versioned Research Hive role contract and a fail-closed capability gate so v0 roles declaratively restrict what agents can run (rmems/worktrees-hives#93 / rmems/worktrees-hives#93). Previously there were no role-based limits; now disallowed capabilities are denied while unclassified commands still follow existing lab/Rust rules.

  • Schema v1: ResearchRole and ResearchRoleCapabilities with JSON parse/serialize; omitted capability keys default to false.
  • v0 catalog: research_coordinator, experiment_agent, verification_agent, artifact_agent with a fixed capability matrix.
  • Enforcement: assert_role_command_allowed calls lab_run.assert_command_allowed first, then checks capabilities from classify_command:
    • git add/commit/apply/... and patch → modify_code; pytest/python -m pytest/python -m unittest/cargo test → execute_tests; hive lab invocations → launch_experiments.
    • Fixes: match only the hive CLI subcommand lab (after globals) and treat abbreviated --state prefixes (e.g., --s, --sta) as value-taking when skipping globals to avoid false positives and ensure correct denials.
  • Binding: RoleBinding pairs a role with (provider, model_id, agent_id); binding_metadata emits schema_version, role_id, model/provider/agent ids, and full capabilities for run records.
  • Exports/docs: public exports in worktrees_hives.__init__; docs/json-contract.md documents data.research_role and data.role_binding; example fixture docs/examples/research-roles-v0.json.
  • Rollout: no CLI/orchestration wiring; follow-ups must call assert_role_command_allowed before granting commands (rmems/worktrees-hives#94/rmems/worktrees-hives#95). Rust remains authoritative for git/gh.

Written for commit 336d3f86b7828c1a34f466321d82f11b2d31cc46. Summary will update on new commits.

Review in cubic

CodeAnt-AI Description

Add versioned Research Hive roles with fail-closed command permissions

What Changed

  • Adds four built-in roles with explicit permissions for reading, testing, modifying code, and launching experiments
  • Validates and preserves versioned role documents, defaults omitted permissions to denied, and records model/provider/agent binding metadata
  • Prevents restricted roles from using code-changing, test-running, or experiment-launching commands, including common shell, wrapper, Python, Cargo, and Git paths
  • Keeps existing merge and force-push policy denials authoritative and documents the future orchestration enforcement point
  • Adds comprehensive validation, command-policy, binding, fixture, and export coverage

Impact

✅ Read-only verifiers cannot modify repository contents
✅ Unauthorized experiment launches and test execution are denied
✅ Role and model provenance is available in run metadata

💡 Usage Guide

Checking Your Pull Request

Every time you make a pull request, our system automatically looks through it. We check for security issues, mistakes in how you're setting up your infrastructure, and common code problems. We do this to make sure your changes are solid and won't cause any trouble later.

Talking to CodeAnt AI

Got a question or need a hand with something in your pull request? You can easily get in touch with CodeAnt AI right here. Just type the following in a comment on your pull request, and replace "Your question here" with whatever you want to ask:

@codeant-ai ask: Your question here

This lets you have a chat with CodeAnt AI about your pull request, making it easier to understand and improve your code.

Example

@codeant-ai ask: Can you suggest a safer alternative to storing this secret?

Preserve Org Learnings with CodeAnt

You can record team preferences so CodeAnt AI applies them in future reviews. Reply directly to the specific CodeAnt AI suggestion (in the same thread) and replace "Your feedback here" with your input:

@codeant-ai: Your feedback here

This helps CodeAnt AI learn and adapt to your team's coding style and standards.

Example

@codeant-ai: Do not flag unused imports.

Retrigger review

Ask CodeAnt AI to review the PR again, by typing:

@codeant-ai: review

Check Your Repository Health

To analyze the health of your code repository, visit our dashboard at https://app.codeant.ai. This tool helps you identify potential issues and areas for improvement in your codebase, ensuring your repository maintains high standards of code health.