Clarify catalog parsing, protected-file matching, and recipe requirements in docstrings (#567)

Update robot-repo-automaton docstrings to describe accepted catalog
forms and parse errors, protected-file matching rules and their effect
on fix confidence, and required recipe fields for conversion to a rule.
Documentation only; no runtime behavior changes.

Validation was not run.

[View coding
task](https://app.coderabbit.ai/code/tasks/644ad760-f790-5539-a914-61a2f1a2febf?source=coding_agent_github_pr_description)

---------

Signed-off-by: Jonathan D.A. Jewell <6759885+hyperpolymath@users.noreply.github.com>
Co-authored-by: Jonathan Jewell <jonathan.jewell@gmail.com>
Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
Co-authored-by: Jonathan D.A. Jewell <6759885+hyperpolymath@users.noreply.github.com>
Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>

Author: 3 people

robot-repo-automaton/src/catalog.rs

@@ -155,6 +155,10 @@ impl ErrorCatalog {
         })
     }
 
+    /// Extract catalogue entries from a quoted `define` form or an already
+    /// unwrapped list.
+    ///
+    /// Returns a catalogue-parse error when `value` is not a non-empty list.
     fn find_catalog_content(value: &Value) -> Result<Vec<&Value>> {
         // Handle (define error-catalog '(...)) structure
         if let Some(cons) = value.as_cons() {

robot-repo-automaton/src/confidence.rs

@@ -298,11 +298,11 @@ impl ThresholdConfig {
     }
 }
 
-/// Check if a file is protected from bot deletion or modification.
+/// Return whether a target matches a protected basename, extension, or
+/// directory marker used to lower confidence for automated fixes.
 ///
-/// Protected files include project state, documentation, and checkpoint files
-/// that bots should NEVER delete or overwrite. These represent intentional
-/// project work that cannot be regenerated from templates.
+/// Basenames are matched case-insensitively; extension and directory matches
+/// are case-sensitive.
 fn is_protected_file(target: &str) -> bool {
     let basename = target.rsplit('/').next().unwrap_or(target);
 

robot-repo-automaton/src/hypatia.rs

@@ -639,6 +639,9 @@ impl CicdHyperAClient {
 }
 
 /// Convert a verisimdb-data recipe JSON to a Rule.
+///
+/// Returns `None` unless the recipe has a string `id` and either a string
+/// `file_glob` or `pattern`.
 fn recipe_to_rule(recipe: &serde_json::Value) -> Option<Rule> {
     let id = recipe.get("id")?.as_str()?.to_string();
     let name = recipe