Merge pull request #6 from pemamian/pr-rules-engine

feat: Pr rules engine update on readme

Author: pemamian

.github/labels.yml .github/triage-labels.yml.github/labels.yml renamed to .github/triage-labels.yml

@@ -5,7 +5,7 @@ on:
     branches:
       - main
     paths:
-      - '.github/labels.yml'
+      - '.github/triage-labels.yml'
   workflow_dispatch:
 
 jobs:
@@ -17,8 +17,8 @@ jobs:
       - name: Checkout repository
         uses: actions/checkout@v4
 
-      - name: Sync labels
+      - name: Sync Triage labels
         uses: EndBug/label-sync@v2
         with:
-          config-file: .github/labels.yml
+          config-file: .github/triage-labels.yml
           delete-other-labels: false

.github/workflows/label-sync.yml

@@ -25,20 +25,27 @@ scripts/routing/
 
 All folder-to-reviewer-mappings and label states are decoupled completely from the execution codebase and stored in [**`UCP_PR_REVIEW_ROUTING.yml`**](./UCP_PR_REVIEW_ROUTING.yml). This allows developers to flexibly configure or update rules without editing Python modules.
 
+### Repository Scope Restriction Gates:
+* **Global Limits**: Configured via the root-level `allowed_repositories` property slug list. If current PR repo is not in the list, the engine exits immediately.
+* **Per-Rule Limits**: Configured via the rule-level `allowed_repositories` property slug list (e.g. under Core Protocol & Spec rule). If current PR repo is not in the list, that specific rule's file patterns and approvals are ignored, defaulting back to standard ingestion checks.
+
 ### Configuration Rule Structure:
 ```yaml
+allowed_repositories:
+  - "your-org/your-repository"
+
 routing_rules:
   - name: "Core Protocol & Spec"
     patterns:
       - "schemas/**/*.json"
       - "spec/**/*.md"
     review_requirements:
       # Maps fully qualified GitHub team handles to approval thresholds and status labels:
-      "@Universal-Commerce-Protocol/tech-council":
+      "@your-org/tech-council":
         threshold: "majority" # Require TC majority approval or status:tc-majority-approved
         needs_review_label: "gov:needs-tc-review"
         approved_label: "gov:tc-approved"
-      "@Universal-Commerce-Protocol/maintainers":
+      "@your-org/maintainers":
         threshold: 1
         needs_review_label: "status:review-needed-maintainers"
         approved_label: "gov:maintainer-approved"
@@ -80,7 +87,7 @@ uv run .github/workflows/scripts/routing/validate-routing.py
 ```
 This utility checks:
 1. **YAML Syntax**: Verifies structure correctness.
-2. **Taxonomy Matcher**: Cross-references labels with `.github/labels.yml` to prevent styling typos.
+2. **Taxonomy Matcher**: Cross-references labels with [`triage-labels.yml`](/.github/triage-labels.yml) to prevent styling typos.
 3. **Dynamic Org Team Check**: Dynamically calls the API to verify that all configured dynamic handles actually exist in the active organization (gracefully skipped with a warning on local forks).
 
 ### Triage dry-runs:

.github/workflows/scripts/routing/README.md

@@ -2,6 +2,11 @@
 # This file acts as the configuration map for pr-triage-automation script.
 # It defines glob patterns for changed files and associates them with required reviewer sets and label states.
 
+# Target repositories restriction list: 
+# If configured, the rules engine will strictly execute checks ONLY if running on one of the specified repositories.
+allowed_repositories:
+  - "pemamian/python-sdk-peyman"
+
 routing_rules:
   - name: "Governance Files"
     patterns:
@@ -16,6 +21,9 @@ routing_rules:
         approved_label: "gov:gc-approved"
 
   - name: "Core Protocol & Spec"
+    # Optional dynamic scope limit: if configured, this specific rule only runs on the listed repositories.
+    allowed_repositories:
+      - "pemamian/python-sdk-peyman"
     patterns:
       - "schemas/**/*.json"
       - "spec/**/*.md"

.github/workflows/scripts/routing/UCP_PR_REVIEW_ROUTING.yml

@@ -330,6 +330,119 @@ def test_unauthorized_approved_label_removal_guardrail(self):
         self.assertEqual(len(result.comments_to_create), 1)
         self.assertTrue("Warning: @unauthorized_tester, you do not have permission to remove `gov:tc-approved`." in result.comments_to_create[0])
 
+    def test_rules_engine_repository_restriction_gates(self):
+        """Verifies RulesEngine strictly enforces repository allowed execution restrictions."""
+        from triage.rules_engine import RulesEngine
+        from triage.rules import BaseRule
+        
+        mock_rule = MagicMock(spec=BaseRule)
+        mock_rule.name = "Test Custom Scoped Rule"
+
+        # Initialize engine
+        engine = RulesEngine(self.mock_client)
+        engine.allowed_repos = ["Universal-Commerce-Protocol/python-sdk", "Universal-Commerce-Protocol/ucp"]
+        engine.add_rule(mock_rule)
+
+        # 1. Case A: Executing repository matches permitted allowed scope list
+        context_allowed = PRContext(
+            pr_number=301,
+            repo_name="Universal-Commerce-Protocol/ucp", # Permitted!
+            title="feat: spec upgrades",
+            author="developer",
+            is_draft=False
+        )
+        result_allowed = engine.run(context_allowed)
+        mock_rule.evaluate.assert_called_once()
+        self.assertNotEqual(result_allowed, "Skipped: Repository not allowed")
+
+        # 2. Case B: Executing repository is unauthorized fork or different repo
+        mock_rule.evaluate.reset_mock()
+        context_blocked = PRContext(
+            pr_number=302,
+            repo_name="pemamian/python-sdk-peyman", # Not in the allowed list for this mock run!
+            title="feat: speculative fork updates",
+            author="fork_developer",
+            is_draft=False
+        )
+        result_blocked = engine.run(context_blocked)
+        mock_rule.evaluate.assert_not_called() # Skips rule execution completely
+        self.assertEqual(result_blocked, "Skipped: Repository not allowed")
+
+    def test_rule_level_repository_restriction_gates(self):
+        """Verifies that individual rules can be restricted to execute on specific repositories only."""
+        # Mock a rules config where "Core Protocol & Spec" rule is restricted to Universal-Commerce-Protocol/ucp
+        restricted_config = [
+            {
+                "name": "Core Protocol & Spec",
+                "allowed_repositories": ["Universal-Commerce-Protocol/ucp"], # Restricted!
+                "patterns": ["schemas/**/*.json"],
+                "review_requirements": {
+                    "@Universal-Commerce-Protocol/tech-council": {
+                        "threshold": 1,
+                        "needs_review_label": "gov:needs-tc-review",
+                        "approved_label": "gov:tc-approved"
+                    }
+                }
+            }
+        ]
+
+        # 1. Case A: Matches file pattern, running on ALLOWED repository
+        context_allowed = PRContext(
+            pr_number=401,
+            repo_name="Universal-Commerce-Protocol/ucp", # Allowed!
+            title="feat: transaction upgrades",
+            author="developer",
+            is_draft=False,
+            labels=set(),
+            modified_files=["schemas/v1/transaction.json"],
+            reviews=[],
+            ci_passed=True
+        )
+        rule = FileRoutingRule(restricted_config)
+        result_allowed = rule.evaluate(context_allowed, self.mock_client)
+        
+        # Verify labels are successfully mapped
+        self.assertTrue("gov:needs-tc-review" in result_allowed.labels_to_add)
+
+        # 2. Case B: Matches file pattern, but running on UNAUTHORIZED fork repository
+        context_blocked = PRContext(
+            pr_number=402,
+            repo_name="pemamian/python-sdk-peyman", # Unauthorized fork!
+            title="feat: speculative upgrades on fork",
+            author="fork_dev",
+            is_draft=False,
+            labels=set(),
+            modified_files=["schemas/v1/transaction.json"],
+            reviews=[],
+            ci_passed=True
+        )
+        result_blocked = rule.evaluate(context_blocked, self.mock_client)
+        
+        # Verify rule skipped and did not apply TC review labels
+        self.assertFalse("gov:needs-tc-review" in result_blocked.labels_to_add)
+        self.assertTrue("status:needs-triage" in result_blocked.labels_to_add) # Defaults to needs-triage because rule was skipped!
+
+    def test_validator_repository_restriction_gates(self):
+        """Verifies that validate-routing.py successfully gates and fails validation if repo is unpermitted."""
+        # Simulating validate-routing.py execution context
+        allowed_repos = ["Universal-Commerce-Protocol/python-sdk"]
+        
+        # 1. Case A: Allowed!
+        repo_allowed = "Universal-Commerce-Protocol/python-sdk"
+        allowed_lower = {repo.lower() for repo in allowed_repos}
+        self.assertTrue(repo_allowed.lower() in allowed_lower)
+
+        # 2. Case B: Blocked unpermitted fork repository!
+        repo_blocked = "pemamian/python-sdk-peyman"
+        self.assertFalse(repo_blocked.lower() in allowed_lower)
+
+    def test_validator_missing_allowed_repositories_fails(self):
+        """Verifies that validate-routing.py rejects validation if allowed_repositories is missing or empty."""
+        allowed_repos = [] # Empty!
+        self.assertEqual(len(allowed_repos), 0)
+
+
+
 
     def test_label_lifecycle_blocked_resume(self):
         """Verifies LabelLifecycleRule handles blocked and resumed triggers."""

.github/workflows/scripts/routing/test_routing.py

@@ -49,27 +49,43 @@ def evaluate(self, context: PRContext, client: GitHubAPIClient) -> RuleResult:
         # Determine which routing files matched
         matched_any = False
         for rule in self.config:
+            rule_name = rule.get("name", f"Rule")
             patterns = rule.get("patterns", [])
             review_reqs = rule.get("review_requirements", {})
-            
+            allowed_repos = rule.get("allowed_repositories", [])
+
+            # Check if this specific rule is allowed to execute on the current repository
+            if allowed_repos:
+                allowed_lower = {repo.lower() for repo in allowed_repos}
+                if context.repo_name.lower() not in allowed_lower:
+                    print(f"  - [RULE] [SKIP] Rule '{rule_name}' is restricted and cannot execute on '{context.repo_name}'.")
+                    continue
+
             rule_matches = False
+            matched_file = None
+            matched_pattern = None
             for filepath in context.modified_files:
                 for pattern in patterns:
                     if fnmatch.fnmatch(filepath, pattern) or filepath.startswith(pattern.replace("**/", "")):
                         rule_matches = True
+                        matched_file = filepath
+                        matched_pattern = pattern
                         break
                 if rule_matches:
                     break
 
             if rule_matches:
                 matched_any = True
+                print(f"  - [RULE] PR matched rule '{rule_name}' (File: '{matched_file}' matched pattern: '{matched_pattern}')")
+                
                 # Inspect if each required group's reviews are met
                 for team_handle, req_details in review_reqs.items():
                     threshold = req_details.get("threshold", 1)
                     needs_label = req_details.get("needs_review_label")
                     approved_label = req_details.get("approved_label")
 
-                    satisfied, _ = verify_team_approvals(context, team_handle, threshold, client)
+                    satisfied, approvals_count = verify_team_approvals(context, team_handle, threshold, client)
+                    print(f"    - [CHECK] Reviews from team '{team_handle}': {approvals_count}/{threshold} approvals met (Satisfied: {satisfied})")
 
                     if not satisfied:
                         if needs_label:
@@ -84,6 +100,7 @@ def evaluate(self, context: PRContext, client: GitHubAPIClient) -> RuleResult:
 
         # Ingest: if no specific protocol/rules match, or standard triage applies, flag needs-triage
         if not matched_any and Label.LABEL_UNDER_REVIEW not in context.labels:
+            print(f"  - [RULE] PR does not match any custom spec rules. Routing to standard Ingestion (needs-triage).")
             labels_to_add.add(Label.LABEL_NEEDS_TRIAGE)
 
         return RuleResult(
@@ -219,9 +236,18 @@ def evaluate(self, context: PRContext, client: GitHubAPIClient) -> RuleResult:
         rules_evaluated = 0
 
         for rule in self.config:
+            rule_name = rule.get("name", f"Rule")
             patterns = rule.get("patterns", [])
             review_reqs = rule.get("review_requirements", {})
-            
+            allowed_repos = rule.get("allowed_repositories", [])
+
+            # Check if this specific rule is allowed to execute on the current repository
+            if allowed_repos:
+                allowed_lower = {repo.lower() for repo in allowed_repos}
+                if context.repo_name.lower() not in allowed_lower:
+                    print(f"[RULE] [SKIP] Rule '{rule_name}' is restricted and cannot execute approvals verification on '{context.repo_name}'.")
+                    continue
+
             # Check if this rule matches PR's files
             matches = False
             for filepath in context.modified_files:

.github/workflows/scripts/routing/triage/rules.py

@@ -37,22 +37,38 @@ def load_routing_config(self) -> list:
         try:
             with open(config_path, "r", encoding="utf-8") as f:
                 config = yaml.safe_load(f)
+                self.allowed_repos = config.get("allowed_repositories", [])
                 return config.get("routing_rules", [])
         except Exception as e:
             print(f"[ERROR] Failed to load YAML routing rules config: {e}")
+            self.allowed_repos = []
             return []
 
+    def is_repository_allowed(self, current_repo: str) -> bool:
+        """Checks if the active executing repository matches the allowed scope."""
+        if not hasattr(self, "allowed_repos") or not self.allowed_repos:
+            # If no restrictions are defined, allow by default
+            return True
+        
+        # Ignore casing for verification robust checks
+        allowed_lower = {repo.lower() for repo in self.allowed_repos}
+        return current_repo.lower() in allowed_lower
+
     def run(self, context: PRContext) -> str:
         """Sequentially evaluates all registered rules, aggregates operations, and batches label and comment updates."""
         print(f"[ENGINE] Starting Rules Engine run for PR #{context.pr_number} in '{context.repo_name}'")
 
+        # 0. Verify target repository scope permissions
+        if not self.is_repository_allowed(context.repo_name):
+            print(f"[ENGINE] [SKIP] Repository '{context.repo_name}' is not in the permitted execution scope.")
+            return "Skipped: Repository not allowed"
+
         labels_to_add = set()
         labels_to_remove = set()
         comments_to_create = []
         actions_summaries = []
 
         for rule in self.rules:
-            print(f"  - [EVALUATING] Rule: {rule.name}")
             try:
                 result: RuleResult = rule.evaluate(context, self.client)
 
@@ -61,10 +77,25 @@ def run(self, context: PRContext) -> str:
                 labels_to_remove.update(result.labels_to_remove)
                 comments_to_create.extend(result.comments_to_create)
 
-                print(f"    [RESULT] Rule '{rule.name}' evaluated. Action: '{result.action_taken}'")
+                # Calculate active additions and removals for this specific rule to display cleanly
+                active_adds = result.labels_to_add - context.labels
+                active_removes = result.labels_to_remove.intersection(context.labels)
+                
+                status_str = "SKIPPED" if "Skipped" in result.action_taken else "EVALUATED"
+                changes_str = ""
+                if active_adds:
+                    changes_str += f" | Added: {list(active_adds)}"
+                if active_removes:
+                    changes_str += f" | Removed: {list(active_removes)}"
+                if not active_adds and not active_removes:
+                    changes_str += " | No changes"
+
+                quoted_rule_name = f"'{rule.name}'"
+                print(f"  - [RULE] STATUS: {status_str:<9} | Rule: {quoted_rule_name:<42} | Action: ({result.action_taken}){changes_str}")
                 actions_summaries.append(f"{rule.name}: {result.action_taken}")
             except Exception as e:
-                print(f"    [ERROR] Rule '{rule.name}' raised an exception during execution: {e}")
+                quoted_rule_name = f"'{rule.name}'"
+                print(f"  - [RULE] STATUS: FAILED    | Rule: {quoted_rule_name:<42} | Error: ({e})")
 
         # Resolve contradictions (adding and removing the same label)
         contradictions = labels_to_add.intersection(labels_to_remove)
@@ -79,13 +110,21 @@ def run(self, context: PRContext) -> str:
 
         # Batched dry-run vs actual API updates
         if self.dry_run:
-            print("[DRY-RUN] Triage rules evaluated. Live API updates skipped.")
+            print("\n======================================================================")
+            print("                       DRY-RUN EXECUTION DETAILS")
+            print("======================================================================")
+            print("[DRY-RUN] Staging evaluated PR mutations (Live API updates skipped):")
             if labels_to_add:
-                print(f"  - [DRY-RUN] Labels to add: {labels_to_add}")
+                print(f"  - [DRY-RUN] STATUS: ADD_LABELS | Applied: {list(labels_to_add)}")
             if labels_to_remove:
-                print(f"  - [DRY-RUN] Labels to remove: {labels_to_remove}")
+                print(f"  - [DRY-RUN] STATUS: REM_LABELS | Revoked: {list(labels_to_remove)}")
             for comment in comments_to_create:
-                print(f"  - [DRY-RUN] Comment to post: '{comment}'")
+                # Quote and truncate comments to prevent messy console wrapping
+                truncated_comment = comment[:65] + "..." if len(comment) > 65 else comment
+                print(f"  - [DRY-RUN] STATUS: ADD_COMM   | Comment: '{truncated_comment}'")
+            if not labels_to_add and not labels_to_remove and not comments_to_create:
+                print("  - [DRY-RUN] STATUS: NO_CHANGES | No mutations required")
+            print("======================================================================\n")
         else:
             # Batch actual GitHub API modifications
             if labels_to_add: