docs: add rationale docs for CrewAI, AutoGen/AG2, Vercel AI SDK, Pydantic AI

.github/workflows/rulebook.yml

@@ -25,10 +25,30 @@ jobs:
       - name: Checkout rulebook
         uses: actions/checkout@v4
 
+      # A coordinated rules change ships as paired PRs (one here, one in
+      # trustabl-rules). Validate this PR's docs against the matching production
+      # PR before either merges: check out trustabl-rules at a branch of the SAME
+      # name as this PR's head branch when it exists; otherwise fall back to main
+      # (push to main has an empty head_ref, so main always validates against the
+      # real production pack).
+      - name: Resolve trustabl-rules ref
+        id: rulesref
+        env:
+          RULES_TOKEN: ${{ secrets.RULES_REPO_TOKEN || github.token }}
+        run: |
+          ref="${{ github.head_ref }}"
+          if [ -n "$ref" ] && git ls-remote --exit-code --heads \
+              "https://x-access-token:${RULES_TOKEN}@github.com/trustabl/trustabl-rules.git" "$ref" >/dev/null 2>&1; then
+            echo "ref=$ref" >> "$GITHUB_OUTPUT"
+          else
+            echo "ref=main" >> "$GITHUB_OUTPUT"
+          fi
+
       - name: Checkout trustabl-rules
         uses: actions/checkout@v4
         with:
           repository: trustabl/trustabl-rules
+          ref: ${{ steps.rulesref.outputs.ref }}
           path: .rules
           token: ${{ secrets.RULES_REPO_TOKEN || github.token }}
 
@@ -59,10 +79,30 @@ jobs:
       - name: Checkout rulebook
         uses: actions/checkout@v4
 
+      # A coordinated rules change ships as paired PRs (one here, one in
+      # trustabl-rules). Validate this PR's docs against the matching production
+      # PR before either merges: check out trustabl-rules at a branch of the SAME
+      # name as this PR's head branch when it exists; otherwise fall back to main
+      # (push to main has an empty head_ref, so main always validates against the
+      # real production pack).
+      - name: Resolve trustabl-rules ref
+        id: rulesref
+        env:
+          RULES_TOKEN: ${{ secrets.RULES_REPO_TOKEN || github.token }}
+        run: |
+          ref="${{ github.head_ref }}"
+          if [ -n "$ref" ] && git ls-remote --exit-code --heads \
+              "https://x-access-token:${RULES_TOKEN}@github.com/trustabl/trustabl-rules.git" "$ref" >/dev/null 2>&1; then
+            echo "ref=$ref" >> "$GITHUB_OUTPUT"
+          else
+            echo "ref=main" >> "$GITHUB_OUTPUT"
+          fi
+
       - name: Checkout trustabl-rules
         uses: actions/checkout@v4
         with:
           repository: trustabl/trustabl-rules
+          ref: ${{ steps.rulesref.outputs.ref }}
           path: .rules
           token: ${{ secrets.RULES_REPO_TOKEN || github.token }}
 

autogen/POLICY_INDEX.md

@@ -0,0 +1,21 @@
+<!-- Generated by tools/gen_index.py. Do not edit by hand. -->
+# AutoGen / AG2 policy index
+
+12 rules — 6 tool · 5 agent · 1 repo
+
+Risk score = `severity_weight × confidence × 100` (engine formula; weights: low=0.15, medium=0.40, high=0.70). Higher = worse.
+
+|    | Id      | SDK/ADK | Scope | Applies To                                          | Policy                                                                   | Severity | Confidence | Risk | Source                                                                                                    |
+| -- | ------- | ------- | ----- | --------------------------------------------------- | ------------------------------------------------------------------------ | -------- | ---------- | ---- | --------------------------------------------------------------------------------------------------------- |
+| 1  | AG2-001 | AutoGen | agent | autogen_conversable_agent, autogen_user_proxy_agent | AutoGen executor runs code on the host without Docker                    | high     | 0.90       | 63.0 | [agent_safety.yaml](https://github.com/trustabl/trustabl-rules/blob/main/autogen/agent_safety.yaml)       |
+| 2  | AG2-002 | AutoGen | agent | autogen_conversable_agent, autogen_user_proxy_agent | AutoGen executor runs code with no human review (human_input_mode=NEVER) | high     | 0.85       | 59.5 | [agent_safety.yaml](https://github.com/trustabl/trustabl-rules/blob/main/autogen/agent_safety.yaml)       |
+| 3  | AG2-004 | AutoGen | agent | autogen_group_chat_manager                          | AutoGen GroupChatManager has no max_round bound                          | medium   | 0.80       | 32.0 | [agent_safety.yaml](https://github.com/trustabl/trustabl-rules/blob/main/autogen/agent_safety.yaml)       |
+| 4  | AG2-005 | AutoGen | agent | autogen_assistant_agent                             | AutoGen AssistantAgent enables code execution on the LLM agent           | medium   | 0.70       | 28.0 | [agent_safety.yaml](https://github.com/trustabl/trustabl-rules/blob/main/autogen/agent_safety.yaml)       |
+| 5  | AG2-006 | AutoGen | agent | autogen_conversable_agent, autogen_user_proxy_agent | AutoGen executor with code execution has no auto-reply cap               | medium   | 0.70       | 28.0 | [agent_safety.yaml](https://github.com/trustabl/trustabl-rules/blob/main/autogen/agent_safety.yaml)       |
+| 6  | AG2-007 | AutoGen | tool  | autogen_tool                                        | AutoGen tool has no description                                          | low      | 0.90       | 13.5 | [tool_definition.yaml](https://github.com/trustabl/trustabl-rules/blob/main/autogen/tool_definition.yaml) |
+| 7  | AG2-008 | AutoGen | tool  | autogen_tool                                        | AutoGen tool parameters are not type-annotated                           | medium   | 0.85       | 34.0 | [tool_definition.yaml](https://github.com/trustabl/trustabl-rules/blob/main/autogen/tool_definition.yaml) |
+| 8  | AG2-009 | AutoGen | tool  | autogen_tool                                        | AutoGen tool body spawns a subprocess                                    | high     | 0.85       | 59.5 | [shell_safety.yaml](https://github.com/trustabl/trustabl-rules/blob/main/autogen/shell_safety.yaml)       |
+| 9  | AG2-010 | AutoGen | tool  | autogen_tool                                        | AutoGen tool body evaluates dynamic code                                 | high     | 0.85       | 59.5 | [code_execution.yaml](https://github.com/trustabl/trustabl-rules/blob/main/autogen/code_execution.yaml)   |
+| 10 | AG2-011 | AutoGen | tool  | autogen_tool                                        | AutoGen tool fetches a caller-controlled URL (SSRF)                      | high     | 0.80       | 56.0 | [ssrf.yaml](https://github.com/trustabl/trustabl-rules/blob/main/autogen/ssrf.yaml)                       |
+| 11 | AG2-012 | AutoGen | tool  | autogen_tool                                        | AutoGen tool network call has no timeout                                 | medium   | 0.80       | 32.0 | [network.yaml](https://github.com/trustabl/trustabl-rules/blob/main/autogen/network.yaml)                 |
+| 12 | AG2-201 | AutoGen | repo  | autogen                                             | AutoGen project ships no agent-guidance doc (AGENTS.md/CLAUDE.md)        | low      | 0.90       | 13.5 | [repo_hygiene.yaml](https://github.com/trustabl/trustabl-rules/blob/main/autogen/repo_hygiene.yaml)       |

crewai/POLICY_INDEX.md

@@ -0,0 +1,23 @@
+<!-- Generated by tools/gen_index.py. Do not edit by hand. -->
+# CrewAI policy index
+
+14 rules — 7 tool · 6 agent · 1 repo
+
+Risk score = `severity_weight × confidence × 100` (engine formula; weights: low=0.15, medium=0.40, high=0.70). Higher = worse.
+
+|    | Id       | SDK/ADK | Scope | Applies To   | Policy                                                           | Severity | Confidence | Risk | Source                                                                                                   |
+| -- | -------- | ------- | ----- | ------------ | ---------------------------------------------------------------- | -------- | ---------- | ---- | -------------------------------------------------------------------------------------------------------- |
+| 1  | CREW-001 | CrewAI  | tool  | crewai_tool  | CrewAI tool has no description                                   | low      | 0.90       | 13.5 | [tool_definition.yaml](https://github.com/trustabl/trustabl-rules/blob/main/crewai/tool_definition.yaml) |
+| 2  | CREW-002 | CrewAI  | tool  | crewai_tool  | CrewAI tool parameters are not type-annotated                    | medium   | 0.85       | 34.0 | [tool_definition.yaml](https://github.com/trustabl/trustabl-rules/blob/main/crewai/tool_definition.yaml) |
+| 3  | CREW-003 | CrewAI  | tool  | crewai_tool  | CrewAI tool body evaluates dynamic code                          | high     | 0.85       | 59.5 | [code_execution.yaml](https://github.com/trustabl/trustabl-rules/blob/main/crewai/code_execution.yaml)   |
+| 4  | CREW-004 | CrewAI  | tool  | crewai_tool  | CrewAI tool body spawns a subprocess                             | high     | 0.85       | 59.5 | [shell_safety.yaml](https://github.com/trustabl/trustabl-rules/blob/main/crewai/shell_safety.yaml)       |
+| 5  | CREW-005 | CrewAI  | tool  | crewai_tool  | CrewAI tool fetches a caller-controlled URL (SSRF)               | high     | 0.80       | 56.0 | [ssrf.yaml](https://github.com/trustabl/trustabl-rules/blob/main/crewai/ssrf.yaml)                       |
+| 6  | CREW-006 | CrewAI  | tool  | crewai_tool  | Mutating CrewAI tool has no idempotency key                      | medium   | 0.55       | 22.0 | [idempotency.yaml](https://github.com/trustabl/trustabl-rules/blob/main/crewai/idempotency.yaml)         |
+| 7  | CREW-101 | CrewAI  | agent | crewai_agent | CrewAI agent enables built-in code execution                     | high     | 0.90       | 63.0 | [agent_safety.yaml](https://github.com/trustabl/trustabl-rules/blob/main/crewai/agent_safety.yaml)       |
+| 8  | CREW-102 | CrewAI  | agent | crewai_agent | CrewAI agent runs code execution in unsafe mode                  | high     | 0.90       | 63.0 | [agent_safety.yaml](https://github.com/trustabl/trustabl-rules/blob/main/crewai/agent_safety.yaml)       |
+| 9  | CREW-103 | CrewAI  | agent | crewai_agent | CrewAI agent wires the code-interpreter built-in tool            | high     | 0.85       | 59.5 | [code_execution.yaml](https://github.com/trustabl/trustabl-rules/blob/main/crewai/code_execution.yaml)   |
+| 10 | CREW-104 | CrewAI  | agent | crewai_agent | CrewAI agent allows delegation to peer agents                    | medium   | 0.75       | 30.0 | [agent_safety.yaml](https://github.com/trustabl/trustabl-rules/blob/main/crewai/agent_safety.yaml)       |
+| 11 | CREW-106 | CrewAI  | agent | crewai_agent | CrewAI agent grants an unconstrained FileReadTool                | high     | 0.70       | 49.0 | [dangerous_tools.yaml](https://github.com/trustabl/trustabl-rules/blob/main/crewai/dangerous_tools.yaml) |
+| 12 | CREW-107 | CrewAI  | agent | crewai_agent | CrewAI agent wires a tool that fetches model-chosen URLs         | medium   | 0.70       | 28.0 | [dangerous_tools.yaml](https://github.com/trustabl/trustabl-rules/blob/main/crewai/dangerous_tools.yaml) |
+| 13 | CREW-108 | CrewAI  | tool  | crewai_tool  | CrewAI tool returns its output as the final answer               | medium   | 0.60       | 24.0 | [tool_behavior.yaml](https://github.com/trustabl/trustabl-rules/blob/main/crewai/tool_behavior.yaml)     |
+| 14 | CREW-201 | CrewAI  | repo  | crewai       | CrewAI project ships no agent-guidance doc (AGENTS.md/CLAUDE.md) | low      | 0.90       | 13.5 | [repo_hygiene.yaml](https://github.com/trustabl/trustabl-rules/blob/main/crewai/repo_hygiene.yaml)       |