feat(symphony): enforce dependency dispatch + PageRank-aware sorting

Fix 5 root causes from failed tlaplus-ts Symphony run:

1. Dependency enforcement: blocked_by populated from Gitea dependency
   API, Todo blocker rule prevents dispatch until all blockers terminal
2. Branch-per-issue: SYMPHONY_* env vars passed to hooks for
   issue-specific branches (symphony/issue-${NUMBER})
3. Issue context in hooks: after_create generates CLAUDE.md with
   issue title/description for agent guidance
4. Per-state concurrency: configurable limits prevent overloading
5. Reconciliation: refresh blocker states before each dispatch cycle

Additionally integrate Gitea Robot API for PageRank-aware dispatch:
- Add pagerank_score field to Issue model
- Fetch PageRank from /api/v1/robot/ready endpoint (single call)
- Merge scores into candidates with graceful fallback
- Sort dispatch candidates by PageRank desc, then priority, then age

All 128 unit + 29 integration tests pass.

Refs #671

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: Terraphim CI

.gitignore

@@ -70,7 +70,7 @@ crates/terraphim_settings/test_settings/settings.toml
 a.out
 
 # Cache
-.cachebro/
+.cached-context/
 .ruff_cache/
 
 # Stale logs and test results

crates/terraphim_symphony/QUICKSTART.md

@@ -194,6 +194,23 @@ Shell scripts executed at workspace lifecycle points. All run with `sh -lc` in t
 | `hooks.before_remove` | Before workspace deletion | Logged and ignored |
 | `hooks.timeout_ms` | -- | Default: `60000` (60s). Hook execution timeout |
 
+**Hook environment variables**: All hooks receive these environment variables for the current issue:
+
+| Variable | Example | Description |
+|----------|---------|-------------|
+| `SYMPHONY_ISSUE_ID` | `42` | Tracker-internal issue ID |
+| `SYMPHONY_ISSUE_IDENTIFIER` | `owner/repo#7` | Human-readable issue key |
+| `SYMPHONY_ISSUE_NUMBER` | `7` | Issue number (extracted from identifier) |
+| `SYMPHONY_ISSUE_TITLE` | `Implement parser` | Issue title |
+
+Use these in hooks to create per-issue branches and meaningful commit messages:
+
+```yaml
+hooks:
+  before_run: 'BRANCH="symphony/issue-${SYMPHONY_ISSUE_NUMBER}" && git checkout "$BRANCH" 2>/dev/null || git checkout -b "$BRANCH" origin/main'
+  after_run: 'BRANCH="symphony/issue-${SYMPHONY_ISSUE_NUMBER}" && git add -A && git commit -m "symphony: ${SYMPHONY_ISSUE_IDENTIFIER}" || true && git push -u origin "$BRANCH" || true'
+```
+
 ### Agent
 
 | Setting | Default | Description |
@@ -350,7 +367,11 @@ WORKFLOW.md is watched for changes (via `file-watch` feature, enabled by default
 
 **Git clone fails in after_create hook** -- Plain HTTPS URLs prompt for credentials in non-interactive shell contexts. Use token-embedded URLs: `git clone https://user:${TOKEN}@host/org/repo.git .`
 
-**Liquid templates appearing literally in hooks** -- Hook scripts are plain shell commands run via `sh -lc`. They are NOT Liquid-rendered. Do not use `{{ }}` template syntax in hook values. Only the prompt body (below the YAML front matter) supports Liquid.
+**Liquid templates appearing literally in hooks** -- Hook scripts are plain shell commands run via `sh -lc`. They are NOT Liquid-rendered. Do not use `{{ }}` template syntax in hook values. Only the prompt body (below the YAML front matter) supports Liquid. Use `$SYMPHONY_ISSUE_NUMBER` and other `SYMPHONY_*` environment variables instead.
+
+**Merge conflicts between agent workspaces** -- If multiple agents push to the same branch, use per-issue branches via `$SYMPHONY_ISSUE_NUMBER` in your `before_run` and `after_run` hooks. See the hook environment variables section above.
+
+**Dependency enforcement not working with Gitea** -- Symphony fetches dependencies from the Gitea API (`/api/v1/repos/.../issues/{n}/dependencies`) and uses them to block dispatch. Ensure dependencies are created via the Gitea web UI or API. Issues in "Todo" state with non-terminal blockers will not be dispatched until their blockers are closed.
 
 ---
 
@@ -407,8 +428,8 @@ workspace:
 
 hooks:
   after_create: "git clone https://terraphim:${GITEA_TOKEN}@git.terraphim.cloud/terraphim/pagerank-viewer.git ."
-  before_run: "git fetch origin && git checkout main && git pull"
-  after_run: "git add -A && git commit -m 'symphony: auto-commit' && git push || true"
+  before_run: 'git fetch origin && BRANCH="symphony/issue-${SYMPHONY_ISSUE_NUMBER}" && (git checkout "$BRANCH" 2>/dev/null && git pull origin "$BRANCH" || git checkout -b "$BRANCH" origin/main) || true'
+  after_run: 'BRANCH="symphony/issue-${SYMPHONY_ISSUE_NUMBER}" && git add -A && git commit -m "symphony: ${SYMPHONY_ISSUE_IDENTIFIER} - ${SYMPHONY_ISSUE_TITLE}" || true && git push -u origin "$BRANCH" || true'
   timeout_ms: 120000
 
 codex:

crates/terraphim_symphony/bin/symphony.rs

@@ -8,12 +8,12 @@ use std::path::PathBuf;
 use tracing::info;
 use tracing_subscriber::EnvFilter;
 
+use terraphim_symphony::SymphonyError;
 use terraphim_symphony::config::ServiceConfig;
 use terraphim_symphony::orchestrator::SymphonyOrchestrator;
 use terraphim_symphony::tracker::gitea::GiteaTracker;
 use terraphim_symphony::tracker::linear::LinearTracker;
 use terraphim_symphony::workspace::WorkspaceManager;
-use terraphim_symphony::SymphonyError;
 
 /// Symphony orchestration service.
 ///
@@ -51,23 +51,20 @@ async fn main() -> anyhow::Result<()> {
     config.validate_for_dispatch()?;
 
     // Build the tracker client
-    let tracker: Box<dyn terraphim_symphony::IssueTracker> =
-        match config.tracker_kind().as_deref() {
-            Some("linear") => Box::new(LinearTracker::from_config(&config)?),
-            Some("gitea") => Box::new(GiteaTracker::from_config(&config)?),
-            Some(kind) => {
-                return Err(SymphonyError::UnsupportedTrackerKind {
-                    kind: kind.into(),
-                }
-                .into());
-            }
-            None => {
-                return Err(SymphonyError::ValidationFailed {
-                    checks: vec!["tracker.kind is required".into()],
-                }
-                .into());
+    let tracker: Box<dyn terraphim_symphony::IssueTracker> = match config.tracker_kind().as_deref()
+    {
+        Some("linear") => Box::new(LinearTracker::from_config(&config)?),
+        Some("gitea") => Box::new(GiteaTracker::from_config(&config)?),
+        Some(kind) => {
+            return Err(SymphonyError::UnsupportedTrackerKind { kind: kind.into() }.into());
+        }
+        None => {
+            return Err(SymphonyError::ValidationFailed {
+                checks: vec!["tracker.kind is required".into()],
             }
-        };
+            .into());
+        }
+    };
 
     // Build the workspace manager
     let workspace_mgr = WorkspaceManager::new(&config)?;

crates/terraphim_symphony/examples/WORKFLOW-claude-code.md

@@ -21,8 +21,8 @@ workspace:
 
 hooks:
   after_create: "git clone https://terraphim:${GITEA_TOKEN}@git.terraphim.cloud/terraphim/pagerank-viewer.git ."
-  before_run: "git fetch origin && git checkout main && git pull"
-  after_run: "git add -A && git commit -m 'symphony: auto-commit' && git push || true"
+  before_run: "git fetch origin && BRANCH=\"symphony/issue-${SYMPHONY_ISSUE_NUMBER}\" && (git checkout \"$BRANCH\" 2>/dev/null && git pull origin \"$BRANCH\" || git checkout -b \"$BRANCH\" origin/main) || true"
+  after_run: "BRANCH=\"symphony/issue-${SYMPHONY_ISSUE_NUMBER}\" && git add -A && git commit -m \"symphony: ${SYMPHONY_ISSUE_IDENTIFIER} - ${SYMPHONY_ISSUE_TITLE}\" || true && git push -u origin \"$BRANCH\" || true"
   timeout_ms: 120000
 
 codex:

crates/terraphim_symphony/examples/WORKFLOW-tlaplus-ts.md

@@ -20,9 +20,9 @@ workspace:
   root: ~/symphony_workspaces
 
 hooks:
-  after_create: "git clone https://terraphim:${GITEA_TOKEN}@git.terraphim.cloud/terraphim/tlaplus-ts.git ."
-  before_run: "git fetch origin && git checkout main && git pull"
-  after_run: "git add -A && git commit -m 'symphony: auto-commit' && git push || true"
+  after_create: "git clone https://terraphim:${GITEA_TOKEN}@git.terraphim.cloud/terraphim/tlaplus-ts.git . && cat > CLAUDE.md << 'CLAUDEEOF'\n# CLAUDE.md - Agent Instructions\n\n## Commit Discipline\n- Make atomic commits with descriptive messages referencing the issue\n- Format: feat(module): description (Refs #N)\n- Run tests before committing: npx vitest run\n- Run build before committing: npm run build\n- Run lint before committing: npm run lint\n\n## Testing\n- Never use mocks in tests\n- Write comprehensive tests using vitest\n- Ensure all existing tests still pass\n\n## Code Standards\n- TypeScript strict mode\n- ESM modules\n- Use British English in documentation\nCLAUDEEOF"
+  before_run: "git fetch origin && BRANCH=\"symphony/issue-${SYMPHONY_ISSUE_NUMBER}\" && (git checkout \"$BRANCH\" 2>/dev/null && git pull origin \"$BRANCH\" || git checkout -b \"$BRANCH\" origin/main) || true"
+  after_run: "BRANCH=\"symphony/issue-${SYMPHONY_ISSUE_NUMBER}\" && git add -A && git commit -m \"symphony: ${SYMPHONY_ISSUE_IDENTIFIER} - ${SYMPHONY_ISSUE_TITLE}\" || true && git push -u origin \"$BRANCH\" || true"
   timeout_ms: 120000
 
 codex:

crates/terraphim_symphony/src/api/mod.rs

@@ -69,7 +69,10 @@ async fn get_state(State(state): State<Arc<Mutex<ApiState>>>) -> impl IntoRespon
 async fn post_refresh(State(state): State<Arc<Mutex<ApiState>>>) -> impl IntoResponse {
     let locked = state.lock().await;
     locked.refresh_notify.notify_one();
-    (StatusCode::ACCEPTED, Json(serde_json::json!({"status": "refresh_queued"})))
+    (
+        StatusCode::ACCEPTED,
+        Json(serde_json::json!({"status": "refresh_queued"})),
+    )
 }
 
 /// GET /api/v1/:issue_identifier - issue-specific debug details.
@@ -95,7 +98,11 @@ async fn get_issue(
         .iter()
         .find(|r| r.issue_identifier == identifier)
     {
-        return (StatusCode::OK, Json(serde_json::to_value(retrying).unwrap())).into_response();
+        return (
+            StatusCode::OK,
+            Json(serde_json::to_value(retrying).unwrap()),
+        )
+            .into_response();
     }
 
     let err = ApiError {
@@ -104,7 +111,11 @@ async fn get_issue(
             message: format!("issue {identifier} not found in running or retry state"),
         },
     };
-    (StatusCode::NOT_FOUND, Json(serde_json::to_value(err).unwrap())).into_response()
+    (
+        StatusCode::NOT_FOUND,
+        Json(serde_json::to_value(err).unwrap()),
+    )
+        .into_response()
 }
 
 /// GET / - human-readable dashboard.

crates/terraphim_symphony/src/config/mod.rs

@@ -54,20 +54,25 @@ impl ServiceConfig {
 
     /// Tracker API endpoint URL.
     pub fn tracker_endpoint(&self) -> String {
-        self.get_str(&["tracker", "endpoint"])
-            .unwrap_or_else(|| match self.tracker_kind().as_deref() {
+        self.get_str(&["tracker", "endpoint"]).unwrap_or_else(|| {
+            match self.tracker_kind().as_deref() {
                 Some("linear") => "https://api.linear.app/graphql".into(),
                 Some("gitea") => std::env::var("GITEA_URL")
                     .unwrap_or_else(|_| "https://git.terraphim.cloud".into()),
                 _ => String::new(),
-            })
+            }
+        })
     }
 
     /// Tracker API key, with `$VAR` resolution.
     pub fn tracker_api_key(&self) -> Option<String> {
         let raw = self.get_str(&["tracker", "api_key"])?;
         let resolved = resolve_env_var(&raw);
-        if resolved.is_empty() { None } else { Some(resolved) }
+        if resolved.is_empty() {
+            None
+        } else {
+            Some(resolved)
+        }
     }
 
     /// Tracker project slug (required for Linear).
@@ -85,6 +90,12 @@ impl ServiceConfig {
         self.get_str(&["tracker", "repo"])
     }
 
+    /// Whether to use the Gitea Robot API for PageRank-aware dispatch.
+    /// Defaults to `true` when tracker kind is "gitea".
+    pub fn tracker_use_robot_api(&self) -> bool {
+        self.get_bool(&["tracker", "use_robot_api"]).unwrap_or(true)
+    }
+
     /// Active issue states (issues eligible for dispatch).
     pub fn active_states(&self) -> Vec<String> {
         self.get_str_list(&["tracker", "active_states"])
@@ -281,8 +292,7 @@ impl ServiceConfig {
                         .is_none()
                 {
                     checks.push(
-                        "tracker.api_key or LINEAR_API_KEY environment variable is required"
-                            .into(),
+                        "tracker.api_key or LINEAR_API_KEY environment variable is required".into(),
                     );
                 }
                 if self.tracker_project_slug().is_none() {
@@ -297,8 +307,7 @@ impl ServiceConfig {
                         .is_none()
                 {
                     checks.push(
-                        "tracker.api_key or GITEA_TOKEN environment variable is required"
-                            .into(),
+                        "tracker.api_key or GITEA_TOKEN environment variable is required".into(),
                     );
                 }
                 if self.tracker_gitea_owner().is_none() {
@@ -353,18 +362,20 @@ impl ServiceConfig {
 
     fn get_u64(&self, path: &[&str]) -> Option<u64> {
         let val = self.get_value(path)?;
-        val.as_u64().or_else(|| {
-            val.as_str()
-                .and_then(|s| s.parse::<u64>().ok())
-        })
+        val.as_u64()
+            .or_else(|| val.as_str().and_then(|s| s.parse::<u64>().ok()))
     }
 
     fn get_i64(&self, path: &[&str]) -> Option<i64> {
         let val = self.get_value(path)?;
-        val.as_i64().or_else(|| {
-            val.as_str()
-                .and_then(|s| s.parse::<i64>().ok())
-        })
+        val.as_i64()
+            .or_else(|| val.as_str().and_then(|s| s.parse::<i64>().ok()))
+    }
+
+    fn get_bool(&self, path: &[&str]) -> Option<bool> {
+        let val = self.get_value(path)?;
+        val.as_bool()
+            .or_else(|| val.as_str().and_then(|s| s.parse::<bool>().ok()))
     }
 
     fn get_str_list(&self, path: &[&str]) -> Option<Vec<String>> {
@@ -451,9 +462,7 @@ mod tests {
 
     #[test]
     fn custom_active_states() {
-        let cfg = config_from_yaml(
-            "tracker:\n  active_states:\n    - Backlog\n    - Started",
-        );
+        let cfg = config_from_yaml("tracker:\n  active_states:\n    - Backlog\n    - Started");
         assert_eq!(cfg.active_states(), vec!["Backlog", "Started"]);
     }
 
@@ -533,9 +542,8 @@ mod tests {
 
     #[test]
     fn per_state_concurrency_ignores_invalid() {
-        let cfg = config_from_yaml(
-            "agent:\n  max_concurrent_agents_by_state:\n    Todo: 0\n    Bad: -1",
-        );
+        let cfg =
+            config_from_yaml("agent:\n  max_concurrent_agents_by_state:\n    Todo: 0\n    Bad: -1");
         let map = cfg.max_concurrent_agents_by_state();
         assert!(map.is_empty());
     }
@@ -554,9 +562,7 @@ mod tests {
 
     #[test]
     fn validation_linear_missing_project_slug() {
-        let cfg = config_from_yaml(
-            "tracker:\n  kind: linear\n  api_key: test-key",
-        );
+        let cfg = config_from_yaml("tracker:\n  kind: linear\n  api_key: test-key");
         let err = cfg.validate_for_dispatch().unwrap_err();
         match err {
             SymphonyError::ValidationFailed { checks } => {
@@ -621,9 +627,7 @@ mod tests {
 
     #[test]
     fn claude_settings_file_path() {
-        let cfg = config_from_yaml(
-            "agent:\n  settings: /home/alex/.claude/symphony-settings.json",
-        );
+        let cfg = config_from_yaml("agent:\n  settings: /home/alex/.claude/symphony-settings.json");
         assert_eq!(
             cfg.claude_settings().unwrap(),
             "/home/alex/.claude/symphony-settings.json"
@@ -632,9 +636,7 @@ mod tests {
 
     #[test]
     fn claude_settings_tilde_path() {
-        let cfg = config_from_yaml(
-            "agent:\n  settings: ~/.claude/symphony-settings.json",
-        );
+        let cfg = config_from_yaml("agent:\n  settings: ~/.claude/symphony-settings.json");
         assert_eq!(
             cfg.claude_settings().unwrap(),
             "~/.claude/symphony-settings.json"
@@ -657,7 +659,11 @@ mod tests {
         let err = cfg.validate_for_dispatch().unwrap_err();
         match err {
             SymphonyError::ValidationFailed { checks } => {
-                assert!(checks.iter().any(|c| c.contains("unsupported agent.runner")));
+                assert!(
+                    checks
+                        .iter()
+                        .any(|c| c.contains("unsupported agent.runner"))
+                );
             }
             _ => panic!("expected ValidationFailed"),
         }

crates/terraphim_symphony/src/config/template.rs

@@ -19,11 +19,7 @@ const DEFAULT_PROMPT: &str = "You are working on an issue from the configured tr
 /// # Errors
 /// Returns `TemplateParseError` if the template syntax is invalid, or
 /// `TemplateRenderError` if a referenced variable or filter is unknown.
-pub fn render_prompt(
-    template_str: &str,
-    issue: &Issue,
-    attempt: Option<u32>,
-) -> Result<String> {
+pub fn render_prompt(template_str: &str, issue: &Issue, attempt: Option<u32>) -> Result<String> {
     let source = if template_str.trim().is_empty() {
         DEFAULT_PROMPT
     } else {
@@ -171,6 +167,7 @@ mod tests {
             url: Some("https://tracker.example.com/MT-42".into()),
             labels: vec!["bug".into(), "urgent".into()],
             blocked_by: vec![],
+            pagerank_score: None,
             created_at: Some(Utc::now()),
             updated_at: Some(Utc::now()),
         }