Improve safety gates signals to start work to make work more interactive

[max-tet]

Instead of the current workflow and safety gates, the following rules should apply. The overall goal is to make collaboration more interactive and iterative.

Planning:

• Any issue you are assigned to is a candidate to start work on.
• If an issue is blocked by another issue (in terms of an issue relationship), ignore it.
• Safety: you can only see issues and comments that were created by or have a thumbs-up from a whitelisted user. All other issues and comments are filtered out before they are fed to the LLM.
• Make a short preliminary plan first, asking any questions that you may have and give a rough overview. If the preliminary plan is approved with thumbs-up, create the thorough plan.
• If new comments on an issue become visible, you should process them and update the preliminary plan or the thorough plan (whichever is under discussion) and answer with a new comment containing a short summary of your changes.
• As before: if the thorogh plan comment gets a thumbs-up from a whitelisted user, you will move to implementation phase.

Executing:

• After creating the PR, assign the author of the issue as a reviewer.
• If a review is done and comments were made, work on those comments and refine the PR. Continue for every review that is made.

[ClaydeCode]

Implementation Plan

Now I have a thorough understanding of the codebase. Let me produce the plan:

Implementation Plan for Issue #23: Improve Safety Gates & Interactive Workflow

Summary

This issue fundamentally restructures how Clayde decides what to work on and how it collaborates on issues. The changes fall into five areas:

1. Remove the old authorization gate — any assigned issue is a candidate (no more is_issue_authorized check).
2. Add blocked-issue detection — skip issues that are blocked by other open issues.
3. Introduce content filtering — before feeding issue data to the LLM, strip out comments/issues not created by or approved (👍) by a whitelisted user.
4. Two-phase planning — first post a short "preliminary plan" with questions, and on 👍 approval produce a thorough plan. New comments trigger plan updates.
5. Post-PR review handling — after creating a PR, assign the issue author as reviewer; when review comments appear, address them and push updates.

Files to Create or Modify

Modified Files

File	Changes
src/clayde/state.py	Expand state machine with new statuses
src/clayde/safety.py	Replace is_issue_authorized() with filter_comments() and is_comment_visible() helpers; keep is_plan_approved() and _has_whitelisted_reaction()
src/clayde/github.py	Add is_blocked_by_open_issue(), get_issue_timeline_events(), add_pr_reviewer(), get_pr_reviews(), get_pr_review_comments(), edit_comment()
src/clayde/orchestrator.py	Rewrite dispatch logic: remove is_issue_authorized gate; add blocked-issue check; add handlers for new states (awaiting_preliminary_approval, awaiting_plan_approval, pr_open); handle new-comments detection
src/clayde/tasks/plan.py	Split into preliminary plan and thorough plan phases; add update-on-new-comments logic
src/clayde/tasks/implement.py	After PR creation, assign issue author as reviewer; add review-handling phase
src/clayde/prompts/plan.j2	Rename to preliminary_plan.j2 — short overview + questions
src/clayde/prompts/implement.j2	Minor updates for review-handling instructions
CLAUDE.md	Update state machine docs, safety gates section, task descriptions
tests/test_safety.py	Rewrite for new filtering functions
tests/test_orchestrator.py	Update for new dispatch logic and states
tests/test_tasks_plan.py	Update for two-phase planning
tests/test_tasks_implement.py	Add tests for reviewer assignment and review handling
tests/test_github.py	Add tests for new GitHub helper functions

New Files

File	Purpose
src/clayde/prompts/preliminary_plan.j2	Template for the short preliminary plan with questions
src/clayde/prompts/thorough_plan.j2	Template for the detailed thorough plan (replaces current plan.j2)
src/clayde/prompts/update_plan.j2	Template for updating a plan when new comments arrive
src/clayde/prompts/address_review.j2	Template for addressing PR review comments
src/clayde/tasks/review.py	New task: fetch PR review comments, invoke Claude to address them, push updates

Implementation Approach & Key Decisions

1. New State Machine

(none) → preliminary_planning → awaiting_preliminary_approval
       → planning → awaiting_plan_approval → implementing → pr_open → done
                                                                    ↘ failed

New statuses:

• preliminary_planning — Claude invocation for short preliminary plan in progress
• awaiting_preliminary_approval — preliminary plan posted, waiting for 👍
• planning — Claude invocation for thorough plan in progress (unchanged name but different trigger)
• awaiting_plan_approval — thorough plan posted, waiting for 👍 (rename of awaiting_approval)
• pr_open — PR exists, monitoring for review comments
• addressing_review — Claude is working on review comments

State entries gain additional fields:

• preliminary_comment_id — comment ID of the preliminary plan
• last_seen_comment_id — highest comment ID processed (for detecting new comments)
• last_seen_review_id — highest PR review ID processed

2. Blocked-Issue Detection (github.py)

Use the GitHub timeline API (GET /repos/{owner}/{repo}/issues/{number}/timeline) to detect "cross-referenced" events that indicate issue relationships. Specifically, look for issues referenced in the body with patterns like "blocked by #N" or "depends on #N". If any referenced issue is still open, treat the current issue as blocked.

Decision: Parse the issue body for "blocked by #N" / "depends on #N" patterns rather than relying on timeline events (which don't reliably indicate blocking relationships). This is simpler and more predictable.

def is_blocked(g, owner, repo, issue) -> bool:
    """Return True if issue body references another open issue as a blocker."""
    # Parse body for patterns like "blocked by #123", "depends on #45"
    # Check if those referenced issues are still open

3. Content Filtering (safety.py)

Replace the current is_issue_authorized() gate with a filtering approach:

def filter_comments(comments: list, issue_author: str) -> list:
    """Return only comments created by or 👍'd by a whitelisted user."""

def is_visible_issue(issue) -> bool:
    """Return True if issue was created by or 👍'd by a whitelisted user."""

The key insight: we no longer skip issues — we filter content. Every assigned issue is worked on, but the LLM only sees sanitized/approved content. Comments from non-whitelisted users without a whitelisted 👍 are removed before building prompts.

Decision: Filter at the prompt-building stage, not at the GitHub fetch stage. This keeps the GitHub layer clean and makes the filtering testable in isolation.

4. Two-Phase Planning (tasks/plan.py)

Split the current run() into two entry points:

def run_preliminary(issue_url: str) -> None:
    """Post a short preliminary plan with questions."""

def run_thorough(issue_url: str) -> None:
    """Post a thorough implementation plan."""

def run_update(issue_url: str) -> None:
    """Process new comments and update the current plan."""

Preliminary plan prompt asks Claude for:

• A brief overview of the approach (a few paragraphs, not an exhaustive plan)
• Any clarifying questions
• Rough scope estimate

Thorough plan prompt includes the preliminary plan + any discussion and asks for the full detailed plan (like the current plan.j2).

Update plan detects new visible comments since the last processed comment, passes them to Claude with the current plan, and posts an updated summary.

5. New-Comment Detection

On each orchestrator tick, for issues in awaiting_preliminary_approval or awaiting_plan_approval:

1. Fetch all comments
2. Filter to visible ones only
3. Compare against last_seen_comment_id in state
4. If new visible comments exist, trigger run_update()

This reuses the existing comment-fetching infrastructure. The last_seen_comment_id field prevents reprocessing.

6. Post-PR Review Handling (tasks/review.py + tasks/implement.py)

After PR creation in implement.py:

• Use add_pr_reviewer() to request review from the issue author
• Set status to pr_open

New tasks/review.py:

def run(issue_url: str) -> None:
    """Check for new PR reviews, address comments, push updates."""

On each tick for pr_open issues:

1. Fetch PR reviews and review comments via PyGitHub
2. Compare against last_seen_review_id
3. If new reviews with comments exist, invoke Claude with address_review.j2 to make changes
4. Push updates to the existing branch
5. Post a summary comment on the issue

7. Reviewer Assignment (github.py)

def add_pr_reviewer(g, owner, repo, pr_number, reviewer_login) -> None:
    """Request a review from the specified user on a PR."""

def get_pr_reviews(g, owner, repo, pr_number) -> list:
    """Return all reviews on a PR."""

def get_pr_review_comments(g, owner, repo, pr_number) -> list:
    """Return all review comments (inline) on a PR."""

For add_pr_reviewer, we need to extract the PR number from the stored PR URL.

8. Orchestrator Changes

The main dispatch loop becomes:

if status is None:
    if is_blocked(g, owner, repo, issue):
        continue
    _handle_new_issue(g, issue, url)  # → preliminary plan
elif status == "awaiting_preliminary_approval":
    _handle_awaiting_preliminary(g, url, entry)  # check 👍 or new comments
elif status == "awaiting_plan_approval":
    _handle_awaiting_plan(g, url, entry)  # check 👍 or new comments
elif status == "pr_open":
    _handle_pr_open(g, url, entry)  # check for reviews

The is_issue_authorized check is removed entirely from _handle_new_issue. The safety model shifts from "gate before starting" to "filter content before LLM sees it."

Edge Cases and Risks

1. Blocked-issue false positives: The body-parsing approach may match text that isn't actually a blocking reference (e.g., "this is not blocked by Fix #4: Cleanup and refactoring #5"). Mitigation: use strict regex patterns (blocked by #\d+, depends on #\d+).

2. Comment visibility lag: A whitelisted user may 👍 a comment between ticks. This is fine — the next tick will pick it up.

3. Plan update loops: If updating a plan triggers a new comment from Clayde, and that comment triggers another update... Mitigation: ignore comments from Clayde's own username (ClaydeCode) when checking for "new comments."

4. Review cycles: Could loop indefinitely if reviewer keeps requesting changes. This is by design — the issue says "continue for every review that is made." But we should log each cycle clearly.

5. State migration: Existing state.json entries with awaiting_approval status need to work with the new code. Handle this with a compatibility mapping: treat awaiting_approval as awaiting_plan_approval.

6. Filtering removes all content: If no comments pass the filter, the LLM gets (none) for comments, which is the current behavior for issues with no comments. Not a problem.

7. PR reviewer assignment failure: The issue author may not have permissions. Wrap in try/except and log a warning.

8. edit_comment vs new comment for plan updates: The issue says "answer with a new comment containing a short summary of your changes." So we post a new comment rather than editing the existing plan. The state tracks the latest plan comment ID.

Verification

1. Unit tests: Update all existing tests and add new ones for:

   • filter_comments() with various visibility scenarios
   • is_blocked() with different body patterns
   • New orchestrator states and transitions
   • Two-phase planning flow
   • Review detection and handling
   • Backward compatibility with awaiting_approval state

2. Integration test pattern: Each task can be tested with mocked GitHub + Claude, verifying:

   • Correct state transitions
   • Correct comment posting
   • Filtered content in prompts (assert non-whitelisted content is absent)

3. Run full test suite: uv run pytest — all existing and new tests must pass.

4. Manual verification: Deploy to container, create a test issue, verify:

   • Preliminary plan is posted
   • 👍 triggers thorough plan
   • New comments trigger plan updates
   • Implementation assigns reviewer
   • Review comments trigger rework

Questions

1. Blocked-by detection: Should we only parse the issue body for "blocked by" / "depends on" patterns, or should we also check GitHub's sub-issue / tracked-by relationships (which require the GraphQL API)? The plan above uses body-text parsing for simplicity.

2. Issue visibility filtering: The issue says "you can only see issues and comments that were created by or have a thumbs-up from a whitelisted user." Does "issues" here mean we should also skip assigned issues if they weren't created by / approved by a whitelisted user? That would conflict with "any issue you are assigned to is a candidate." I'm interpreting this as: the issue itself is always processed if assigned, but the content (body, comments) fed to the LLM is filtered. If the issue body itself is from a non-whitelisted user with no 👍, the LLM would see (filtered) for the body — which seems problematic. Clarification would help.

3. "Blocked by" scope: Should we check issue relationships across all repos, or only within the same repo?

Branch: clayde/issue-23-interactive-safety-gates

---

React with 👍 to approve this plan and start implementation.

[max-tet]

Regarding 2: I can set an explicit "blocked by" relationship in GitHub. That should be used to detect a blocked issue, not a text in the issue body.

Regarding 3: Consider the case that the original issue and all contents could be filtered out and nothing is left. E.g. an issue by a non-whitelisted user and not approved by a whitelisted user that has no comments. In a case like that, no work at all should be started.

Regarding edge-case 8 (edit_comment vs new comment for plan updates): do both. Update the original plan comment AND make a new and short comment describing what you changed.

Regarding Question 1: see above, use the explicit relationship between GitHub issues only.

Regarding Quesion 2: see above, issues where all content is filtered and none is visible are not considered for work.

Regarding question 3: across all repos.

[ClaydeCode]

Implementation complete — PR opened: #27