feat(ai-contracts-test): add prompt renderer component (ethereum-optimism#17578)

* feat(ai-contracts-test): add prompt renderer component

- implement render.py script for prompt generation with placeholder replacement
- add prompt/ directory with canonical prompt template (prompt.md)
- extend justfile with new commands: just render and just prompt (combined workflow)
- update runbook documentation with multi-step workflow instructions

* fix(semgrep): exclude prompt files from sol-safety-trycatch-eip150 rule

Author: aliersh

.semgrep/rules/sol-rules.yaml

@@ -110,6 +110,7 @@ rules:
       exclude:
         - packages/contracts-bedrock/test
         - packages/contracts-bedrock/scripts
+        - ops/ai-eng/contracts-test-maintenance/prompt/prompt.md
 
   - id: sol-style-input-arg-fmt
     languages: [solidity]

ops/ai-eng/contracts-test-maintenance/docs/runbook.md

@@ -10,12 +10,23 @@ The system uses a two-branch scoring algorithm: tests whose contracts have moved
 
 ```bash
 # From the ai-eng directory
+
+# Option 1: Run both steps in one command (recommended)
+just prompt
+
+# Option 2: Run steps individually
+# Step 1: Rank tests by staleness
 just rank
+
+# Step 2: Generate AI prompt for the highest-priority test
+just render
 ```
 
 ## Output
 
-The tool generates `tests_ranker/output/ranking.json`:
+### Test Ranking Output
+
+The `just rank` command generates `tests_ranker/output/ranking.json`:
 
 ```json
 {
@@ -40,3 +51,9 @@ The tool generates `tests_ranker/output/ranking.json`:
 - `contract_commit_ts` - Unix timestamp of contract file's last commit
 - `staleness_days` - Calculated staleness (positive = contract newer)
 - `score` - Priority score (higher = more urgent)
+
+### Prompt Renderer Output
+
+The `just render` command generates a markdown file in `prompt-renderer/output/` with the name format `{ContractName}_prompt.md`. This file contains the AI prompt template with the highest-priority test and contract paths filled in, ready to be used for test maintenance analysis.
+
+For example, if the top-ranked test is `ProtocolVersions.t.sol`, the output file will be `ProtocolVersions_prompt.md`.

ops/ai-eng/contracts-test-maintenance/prompt-renderer/render.py

@@ -0,0 +1,92 @@
+#!/usr/bin/env python3
+"""
+Script to render a prompt instance by replacing placeholders with actual test and contract paths
+from the first entry in the ranking JSON file.
+"""
+
+import json
+from pathlib import Path
+
+
+def load_ranking_data():
+    """Load the ranking JSON file and return the first entry."""
+    ranking_file = (
+        Path(__file__).parent.parent / "tests_ranker" / "output" / "ranking.json"
+    )
+
+    with open(ranking_file, "r") as f:
+        data = json.load(f)
+
+    if not data.get("entries"):
+        raise ValueError("No entries found in ranking.json")
+
+    return data["entries"][0]
+
+
+def load_prompt_template():
+    """Load the prompt template markdown file."""
+    prompt_file = Path(__file__).parent.parent / "prompt" / "prompt.md"
+
+    with open(prompt_file, "r") as f:
+        return f.read()
+
+
+def render_prompt(template, test_path, contract_path):
+    """Replace the placeholders in the template with actual paths."""
+    return template.replace("{TEST_PATH}", test_path).replace(
+        "{CONTRACT_PATH}", contract_path
+    )
+
+
+def save_prompt_instance(rendered_prompt, test_path, contract_path):
+    """Save the rendered prompt to the output folder with a descriptive name."""
+    output_dir = Path(__file__).parent / "output"
+    output_dir.mkdir(exist_ok=True)
+
+    # Extract test name and remove .t suffix if present
+    test_name = Path(test_path).stem
+    if test_name.endswith(".t"):
+        test_name = test_name[:-2]
+
+    # Create descriptive filename
+    filename = f"{test_name}_prompt.md"
+    output_file = output_dir / filename
+
+    with open(output_file, "w") as f:
+        f.write(rendered_prompt)
+
+    return output_file
+
+
+def main():
+    """Main function to render and save the prompt instance."""
+    try:
+        # Load the first entry from ranking
+        first_entry = load_ranking_data()
+        test_path = first_entry["test_path"]
+        contract_path = first_entry["contract_path"]
+
+        print(f"Using first ranking entry:")
+        print(f"  Test path: {test_path}")
+        print(f"  Contract path: {contract_path}")
+
+        # Load prompt template
+        template = load_prompt_template()
+
+        # Render the prompt with actual paths
+        rendered_prompt = render_prompt(template, test_path, contract_path)
+
+        # Save the rendered prompt
+        output_file = save_prompt_instance(rendered_prompt, test_path, contract_path)
+
+        print(f"Prompt instance saved to: {output_file}")
+
+    except Exception as e:
+        print(f"Error: {e}")
+        return 1
+
+    return 0
+
+
+if __name__ == "__main__":
+    exit(main())