docs(fleet): clarify automaton behavior, panel ID validation, and lock-sync helpers

Author: coderabbitai[bot]

robot-repo-automaton/src/fixer.rs

@@ -424,10 +424,10 @@ impl Fixer {
         })
     }
 
-    /// Modify a file with safety checks and rollback support
+    /// Modify a file with safety checks.
     ///
-    /// Reads the modification specification from the fix, applies it to the file,
-    /// and rolls back if the modification produces invalid content.
+    /// Reads the modification specification from the fix and rejects invalid
+    /// structured content before atomically replacing the original file.
     fn apply_modify(
         &self,
         target_path: &Path,
@@ -542,11 +542,8 @@ impl Fixer {
 
     /// Create a file with template expansion
     ///
-    /// Supports template variables:
-    /// - `gitbot-fleet` - Repository name
-    /// - `hyperpolymath` - Repository owner
-    /// - `{{LICENSE}}` - License identifier
-    /// - `{{YEAR}}` - Current year
+    /// Supports the literal `gitbot-fleet` as a repository-name placeholder,
+    /// plus `{{LICENSE}}`, `{{YEAR}}`, `{{AUTHOR}}`, and `{{EMAIL}}`.
     fn apply_create(
         &self,
         target_path: &Path,
@@ -938,6 +935,8 @@ fn resolve_from_existing_ancestor(path: &Path) -> Result<PathBuf> {
     }
 }
 
+/// Return whether the character at byte offset `index` is escaped by an odd run
+/// of backslashes. `index` must be a UTF-8 boundary.
 fn is_escaped(value: &str, index: usize) -> bool {
     value[..index]
         .bytes()

robot-repo-automaton/src/fleet.rs

@@ -157,12 +157,10 @@ impl FleetCoordinator {
         }
     }
 
-    /// Report fix outcomes to Hypatia's neurosymbolic learning loop.
+    /// Record a fix outcome as a fleet finding for Hypatia's learning loop.
     ///
-    /// When robot-repo-automaton applies a fix (or fails to apply one),
-    /// this method records the outcome so the learning engine can adjust
-    /// confidence thresholds and propose new rules based on real-world
-    /// success/failure rates.
+    /// If connected, records the pattern, result, fix type, and confidence in
+    /// the shared context. If disconnected, this is a no-op.
     pub fn report_fix_outcome(
         &mut self,
         pattern: &str,

robot-repo-automaton/src/hooks.rs

@@ -279,7 +279,10 @@ impl PreCommitChecker {
         Ok(violations)
     }
 
-    /// Check for secrets in staged files
+    /// Return secret findings for staged files.
+    ///
+    /// Secret scanning is not yet implemented, so this currently returns an
+    /// empty list.
     pub fn check_secrets(&self) -> Result<Vec<String>> {
         let findings = Vec::new();
 

robot-repo-automaton/src/hypatia.rs

@@ -205,8 +205,8 @@ impl CicdHyperAClient {
 
     /// Fetch a ruleset from the registry.
     ///
-    /// Tries the Hypatia API first; falls back to loading rules from the
-    /// local verisimdb-data recipes directory if the API is unavailable.
+    /// Tries the Hypatia API first; falls back to local recipes when the request
+    /// fails, returns a non-success status, or does not contain a valid ruleset.
     pub async fn fetch_ruleset(&self, ruleset_id: &str) -> crate::Result<Ruleset> {
         tracing::info!(
             "Fetching ruleset: {} from {}",
@@ -268,6 +268,8 @@ impl CicdHyperAClient {
         self.load_recipes_from(ruleset_id, &recipes_dirs)
     }
 
+    /// Load recipes from the first existing candidate directory, or use the
+    /// built-in RSR rules when no valid recipes are found.
     fn load_recipes_from(
         &self,
         ruleset_id: &str,

scripts/check-lock-sync.sh

@@ -85,6 +85,9 @@ USES_FILE="$(mktemp "${TMPDIR:-/tmp}/check-lock-sync.uses.XXXXXX")"
 RAW_USES_FILE="$(mktemp "${TMPDIR:-/tmp}/check-lock-sync.raw-uses.XXXXXX")"
 trap 'rm -f "$USES_FILE" "$RAW_USES_FILE"' EXIT
 
+# Print each valid scalar `uses` value from the workflow at $1, one per line.
+# Return non-zero if parsing fails or a value is empty, non-string, or contains
+# a tab or line break.
 extract_uses_yq() {
   local workflow="$1"
 
@@ -97,6 +100,9 @@ extract_uses_yq() {
   yq -r '.. | select(type == "!!map" and has("uses")) | .uses | select(type == "!!str")' "$workflow"
 }
 
+# Print each valid scalar `uses` value from the workflow at $1, one per line.
+# Return non-zero if parsing fails or a value is empty, non-string, or contains
+# a tab or line break.
 extract_uses_ruby() {
   local workflow="$1"
 
@@ -106,6 +112,8 @@ require "yaml"
 workflow = ARGV.fetch(0)
 document = YAML.safe_load(File.read(workflow), aliases: true)
 
+# Traverse a parsed workflow and emit its valid scalar `uses` values.
+# Abort if a value is empty, non-string, or contains a tab or line break.
 def emit_uses(node, workflow)
   case node
   when Hash

shared-context/src/panel.rs

@@ -34,7 +34,8 @@ use std::path::PathBuf;
 pub struct PanelId(pub String);
 
 impl PanelId {
-    /// Create a new panel ID, validating PascalCase format.
+    /// Create a panel ID whose non-reserved name starts with an uppercase letter
+    /// and contains only alphanumeric characters.
     pub fn new(name: &str) -> Result<Self, PanelError> {
         if name.is_empty() {
             return Err(PanelError::InvalidName("Panel name cannot be empty".into()));