Add Watchflow governance rules (4 rules, 3 high-priority)

[dkargatzis]

Add Watchflow Governance Rules

This PR adds automated governance rules for warestack/watchflow based on repository analysis of recent PR history and codebase patterns.

Repository Health Analysis Report: warestack/watchflow

This report provides a data-driven assessment of the current health of the warestack/watchflow repository based on hygiene metrics from the last 30 merged pull requests and repository context. The goal is to identify key problems and risks, and to highlight actionable areas for improvement.

Metric	Value	Severity	Category	Explanation
Unlinked Issue Rate	40.0%	High	Issue Management	A high rate of PRs not linked to issues indicates poor traceability between code changes and tracked work, increasing risk of undocumented changes and reducing accountability.

|
| Average PR Size | 428 lines| Medium | Code Review | Large PR sizes can hinder effective code review, increasing the chance of overlooked defects and slowing down the review process.
|
| First-Time Contributors| 0 | Medium | Community Health | No contributions from first-time contributors may suggest barriers to entry or lack of community engagement, potentially limiting project growth and diversity.
|
| Codeowner Bypass Rate | 35.0% | High | Code Review | A significant portion of PRs bypass codeowner reviews, risking unvetted changes to critical code areas and reducing code quality assurance.
|
| New Code Test Coverage | 0.0% | Critical | Testing | Absence of test coverage on new code is a critical risk, leading to potential regressions and reduced confidence in code stability.
|
| Issue-Diff Mismatch Rate| 15.0% | Medium | Issue Management | Mismatches between issues and code diffs indicate inconsistencies that can cause confusion and reduce traceability.

Summary and Recommendations

• Improve Issue Linking: Enforce linking PRs to issues to enhance traceability and accountability.
• Reduce PR Size: Encourage smaller, incremental PRs to facilitate thorough reviews.
• Engage New Contributors: Implement onboarding and contribution guidelines to attract first-time contributors.
• Enforce Codeowner Reviews: Strengthen policies to minimize codeowner bypasses, ensuring critical code is reviewed by experts.
• Increase Test Coverage: Mandate adding tests for new code to improve reliability and maintainability.
• Align Issues and Diffs: Improve processes to ensure code changes correspond accurately to issues.

Addressing these areas will significantly enhance the repository's health, maintainability, and community engagement.

Recommended Rules

require_linked_issue: Block PRs without issue references to improve traceability and accountability given the 40% unlinked issue rate. - High

Rationale: The rule to require linked issues for PRs directly addresses the high unlinked issue rate of 40%, which undermines traceability and accountability by ensuring every code change is connected to a tracked issue, thereby reducing undocumented changes and improving project oversight.

max_pr_size: Limit lines changed per PR to 500 to reduce review complexity and improve code quality given the average PR size of 428 lines. - Medium

Rationale: The recommended rule to limit PR size to 500 lines directly addresses the medium-severity problem of large average PR sizes (428 lines), which hinder effective code review and increase the risk of overlooked defects, thereby improving review efficiency and code quality.

code_owners: Enforce CODEOWNERS approval for critical paths to prevent unvetted changes, addressing the 35% codeowner bypass rate. - High

Rationale: The rule to enforce CODEOWNERS approval directly addresses the high (35%) codeowner bypass rate identified, ensuring that critical code changes receive expert review to maintain code quality and reduce risks from unvetted modifications.

required_workflows: Ensure CI passes before merge to maintain code stability and quality given the presence of CI/CD workflows. - High

Rationale: Requiring CI workflows to pass before merging directly addresses the critical issue of 0% test coverage on new code by ensuring automated tests run and pass, thereby improving code stability and quality despite the presence of large PRs and codeowner bypasses.

Changes

• Adds .watchflow/rules.yaml with the recommended governance rules

Next Steps

1. Review the rules in .watchflow/rules.yaml
2. Adjust parameters if needed
3. Install the Watchflow GitHub App to enable automated enforcement
4. Merge this PR to activate the rules

---

Generated by Watchflow repository analysis.

Summary by CodeRabbit

• Chores
  • Updated pull request validation controls with new requirements: linked issues, PR size limits, code owner approvals, and required workflow completion before merge. These controls replace previous push protection rules.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

📝 Walkthrough

Walkthrough

The watchflow rules configuration is updated, replacing five existing rules (descriptive PR titles, new contributor approvals, tests requirement, code owners for critical files, and no direct pushes to main) with four new PR-focused controls: require_linked_issue, max_pr_size, code_owners, and required_workflows. All new rules target pull_request events.

Changes

Cohort / File(s)	Summary
Workflow Rules Configuration .watchflow/rules.yaml	Removed 5 legacy rules (PR title validation, contributor checks, test requirements, push restrictions). Added 4 new PR controls with high/medium severity targeting pull_request events using empty parameters.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Poem

🐰 Old rules hop away, new ones take their place,
Four controls now guard the PR race,
Linked issues bloom, code owners stand tall,
Workflows required—we've answered the call! ✨

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main change: adding four Watchflow governance rules with three marked as high-priority. It directly reflects the content of the changeset.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

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

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch watchflow/rules

---

🧹 Recent nitpick comments

.watchflow/rules.yaml (1)

23-29: Consider specifying required workflow names.

The rule enforces CI workflow passage but parameters: {} doesn't specify which workflows are required. If Watchflow supports it, explicitly listing required workflows (e.g., workflows: ["ci", "lint", "test"]) would make the rule's scope clearer and prevent unexpected behavior if new optional workflows are added.

📜 Recent review details

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between f5a3be1 and ecc22db.

📒 Files selected for processing (1)

• .watchflow/rules.yaml

🔇 Additional comments (3)

.watchflow/rules.yaml (3)

16-22: Consider specifying critical paths in parameters.

The description mentions enforcing CODEOWNERS for "critical paths," but parameters: {} is empty. If Watchflow supports path-based filtering, consider specifying which paths are considered critical (e.g., src/core/**, config/**) to match the rule's intent.

---

2-8: LGTM!

The require_linked_issue rule configuration is appropriate for a boolean-style check. Empty parameters are reasonable here since the rule simply checks for issue reference presence.

---

9-15: Verify whether max_pr_size is a supported Watchflow rule.

The original comment assumes max_pr_size is a built-in Watchflow rule requiring a max_lines parameter. However, search of the official Watchflow documentation and repository found no evidence that max_pr_size is a standard rule or that a max_lines parameter exists. Watchflow uses AI-powered evaluation of natural-language rule descriptions with custom parameters (e.g., min_approvals, restricted_days), but the specific rule and parameter names for PR size limits are not documented. Before adding parameters, confirm that this rule is actually supported and what parameter name(s) it expects.

_{✏️ Tip: You can disable this entire section by setting review_details to false in your review settings.}

---

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.}