cadence-skill-installer 0.2.44 → 0.2.45

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cadence-skill-installer",
-  "version": "0.2.44",
+  "version": "0.2.45",
   "description": "Install the Cadence skill into supported AI tool skill directories.",
   "repository": "https://github.com/snowdamiz/cadence",
   "private": false,

package/skill/scripts/ideation_research.py

@@ -11,7 +11,14 @@ RESEARCH_SCHEMA_VERSION = 1
 PRIORITY_LEVELS = {"low", "medium", "high"}
 RESEARCH_EXECUTION_SCHEMA_VERSION = 1
 RESEARCH_EXECUTION_STATUSES = {"pending", "in_progress", "complete"}
-RESEARCH_TOPIC_STATUSES = {"pending", "in_progress", "needs_followup", "complete"}
+RESEARCH_TOPIC_STATUSES = {
+    "pending",
+    "in_progress",
+    "needs_followup",
+    "complete",
+    "complete_with_caveats",
+}
+RESEARCH_TOPIC_COMPLETE_STATUSES = {"complete", "complete_with_caveats"}
 DEFAULT_RESEARCH_HANDOFF_MESSAGE = 'Start a new chat and say "continue research".'
 
 
@@ -84,11 +91,14 @@ def default_research_execution() -> dict[str, Any]:
         "planning": {
             "target_effort_per_pass": 12,
             "max_topics_per_pass": 4,
+            "max_passes_per_topic": 3,
+            "max_total_passes": 120,
             "latest_round": 0,
         },
         "summary": {
             "topic_total": 0,
             "topic_complete": 0,
+            "topic_caveated": 0,
             "topic_needs_followup": 0,
             "topic_pending": 0,
             "pass_pending": 0,
@@ -181,6 +191,20 @@ def _normalize_research_execution(agenda: dict[str, Any], raw_execution: Any) ->
     if max_topics < 1:
         max_topics = 1
 
+    try:
+        max_passes_per_topic = int(planning.get("max_passes_per_topic", 3))
+    except (TypeError, ValueError):
+        max_passes_per_topic = 3
+    if max_passes_per_topic < 1:
+        max_passes_per_topic = 1
+
+    try:
+        max_total_passes = int(planning.get("max_total_passes", 120))
+    except (TypeError, ValueError):
+        max_total_passes = 120
+    if max_total_passes < 1:
+        max_total_passes = 1
+
     try:
         latest_round = int(planning.get("latest_round", 0))
     except (TypeError, ValueError):
@@ -191,6 +215,8 @@ def _normalize_research_execution(agenda: dict[str, Any], raw_execution: Any) ->
     normalized["planning"] = {
         "target_effort_per_pass": target_effort,
         "max_topics_per_pass": max_topics,
+        "max_passes_per_topic": max_passes_per_topic,
+        "max_total_passes": max_total_passes,
         "latest_round": latest_round,
     }
 
@@ -305,7 +331,10 @@ def _normalize_research_execution(agenda: dict[str, Any], raw_execution: Any) ->
     normalized["source_registry"] = source_registry
 
     total_topics = len(topic_status)
-    topic_complete = len([entry for entry in topic_status.values() if entry.get("status") == "complete"])
+    topic_complete = len(
+        [entry for entry in topic_status.values() if entry.get("status") in RESEARCH_TOPIC_COMPLETE_STATUSES]
+    )
+    topic_caveated = len([entry for entry in topic_status.values() if entry.get("status") == "complete_with_caveats"])
     topic_needs_followup = len(
         [entry for entry in topic_status.values() if entry.get("status") == "needs_followup"]
     )
@@ -331,6 +360,7 @@ def _normalize_research_execution(agenda: dict[str, Any], raw_execution: Any) ->
     normalized["summary"] = {
         "topic_total": total_topics,
         "topic_complete": topic_complete,
+        "topic_caveated": topic_caveated,
         "topic_needs_followup": topic_needs_followup,
         "topic_pending": max(topic_pending, 0),
         "pass_pending": len(pass_queue),
@@ -405,6 +435,7 @@ def reset_research_execution(ideation: Any) -> dict[str, Any]:
     execution["summary"] = {
         "topic_total": len(topic_index),
         "topic_complete": 0,
+        "topic_caveated": 0,
         "topic_needs_followup": 0,
         "topic_pending": len(topic_index),
         "pass_pending": 0,

package/skill/scripts/run-research-pass.py

@@ -23,8 +23,10 @@ from workflow_state import reconcile_workflow_state
 SCRIPT_DIR = Path(__file__).resolve().parent
 ROUTE_GUARD_SCRIPT = SCRIPT_DIR / "assert-workflow-route.py"
 CADENCE_JSON_REL = Path(".cadence") / "cadence.json"
-PASS_RESULT_TOPIC_STATUSES = {"complete", "needs_followup"}
+PASS_RESULT_TOPIC_STATUSES = {"complete", "complete_with_caveats", "needs_followup"}
 PASS_RESULT_CONFIDENCE = {"low", "medium", "high"}
+TOPIC_COMPLETE_STATUSES = {"complete", "complete_with_caveats"}
+TOPIC_ACTIVE_STATUSES = {"pending", "in_progress", "needs_followup"}
 
 
 def run_command(command: list[str]) -> subprocess.CompletedProcess[str]:
@@ -76,6 +78,33 @@ def coerce_string_list(value: Any) -> list[str]:
     return items
 
 
+def coerce_positive_int(value: Any, default: int, *, minimum: int = 1) -> int:
+    try:
+        number = int(value)
+    except (TypeError, ValueError):
+        number = default
+    if number < minimum:
+        return minimum
+    return number
+
+
+def planning_config(execution: dict[str, Any]) -> dict[str, int]:
+    planning = execution.get("planning")
+    if not isinstance(planning, dict):
+        planning = {}
+        execution["planning"] = planning
+
+    config = {
+        "target_effort_per_pass": coerce_positive_int(planning.get("target_effort_per_pass", 12), 12),
+        "max_topics_per_pass": coerce_positive_int(planning.get("max_topics_per_pass", 4), 4),
+        "max_passes_per_topic": coerce_positive_int(planning.get("max_passes_per_topic", 3), 3),
+        "max_total_passes": coerce_positive_int(planning.get("max_total_passes", 120), 120),
+        "latest_round": coerce_positive_int(planning.get("latest_round", 0), 0, minimum=0),
+    }
+    planning.update(config)
+    return config
+
+
 def parse_args() -> argparse.Namespace:
     parser = argparse.ArgumentParser(
         description="Plan and persist Cadence ideation research passes.",
@@ -227,7 +256,7 @@ def unresolved_topics(execution: dict[str, Any]) -> list[str]:
         [
             topic_id
             for topic_id, entry in topic_status.items()
-            if isinstance(entry, dict) and coerce_string(entry.get("status"), "pending") != "complete"
+            if isinstance(entry, dict) and coerce_string(entry.get("status"), "pending") in TOPIC_ACTIVE_STATUSES
         ]
     )
 
@@ -236,19 +265,22 @@ def sort_topics_for_planning(topic_ids: list[str], topic_map: dict[str, dict[str
     status_map = execution.get("topic_status")
     status_map = status_map if isinstance(status_map, dict) else {}
 
-    status_rank = {"needs_followup": 0, "in_progress": 1, "pending": 2}
+    status_rank = {"pending": 0, "in_progress": 1, "needs_followup": 2}
     priority_rank = {"high": 0, "medium": 1, "low": 2}
 
-    def sort_key(topic_id: str) -> tuple[int, int, int, str]:
+    def sort_key(topic_id: str) -> tuple[int, int, int, int, str]:
         status = "pending"
+        passes_attempted = 0
         entry = status_map.get(topic_id)
         if isinstance(entry, dict):
             status = coerce_string(entry.get("status"), "pending").lower()
+            passes_attempted = coerce_positive_int(entry.get("passes_attempted", 0), 0, minimum=0)
 
         topic = topic_map.get(topic_id, {})
         priority = coerce_string(topic.get("priority"), "medium").lower()
         return (
             status_rank.get(status, 2),
+            passes_attempted,
             priority_rank.get(priority, 1),
             -topic_effort(topic),
             topic_id,
@@ -258,15 +290,24 @@ def sort_topics_for_planning(topic_ids: list[str], topic_map: dict[str, dict[str
 
 
 def latest_round(execution: dict[str, Any]) -> int:
-    planning = execution.get("planning")
-    planning = planning if isinstance(planning, dict) else {}
-    try:
-        round_value = int(planning.get("latest_round", 0))
-    except (TypeError, ValueError):
-        round_value = 0
-    if round_value < 0:
-        return 0
-    return round_value
+    config = planning_config(execution)
+    round_candidates = [config.get("latest_round", 0)]
+
+    queue = execution.get("pass_queue")
+    if isinstance(queue, list):
+        for entry in queue:
+            if not isinstance(entry, dict):
+                continue
+            round_candidates.append(coerce_positive_int(entry.get("round", 0), 0, minimum=0))
+
+    history = execution.get("pass_history")
+    if isinstance(history, list):
+        for entry in history:
+            if not isinstance(entry, dict):
+                continue
+            round_candidates.append(coerce_positive_int(entry.get("round", 0), 0, minimum=0))
+
+    return max(round_candidates)
 
 
 def rebuild_pass_queue(execution: dict[str, Any], topic_map: dict[str, dict[str, Any]], timestamp: str) -> None:
@@ -275,29 +316,11 @@ def rebuild_pass_queue(execution: dict[str, Any], topic_map: dict[str, dict[str,
         execution["pass_queue"] = []
         return
 
-    planning = execution.get("planning")
-    if not isinstance(planning, dict):
-        planning = {}
-        execution["planning"] = planning
-
-    try:
-        target_effort = int(planning.get("target_effort_per_pass", 12))
-    except (TypeError, ValueError):
-        target_effort = 12
-    if target_effort < 1:
-        target_effort = 1
-
-    try:
-        max_topics = int(planning.get("max_topics_per_pass", 4))
-    except (TypeError, ValueError):
-        max_topics = 4
-    if max_topics < 1:
-        max_topics = 1
-
+    config = planning_config(execution)
+    target_effort = config["target_effort_per_pass"]
+    max_topics = config["max_topics_per_pass"]
     round_number = latest_round(execution) + 1
-    planning["latest_round"] = round_number
-    planning["target_effort_per_pass"] = target_effort
-    planning["max_topics_per_pass"] = max_topics
+    execution["planning"]["latest_round"] = round_number
 
     ordered_topics = sort_topics_for_planning(topic_ids, topic_map, execution)
     queue: list[dict[str, Any]] = []
@@ -351,6 +374,147 @@ def rebuild_pass_queue(execution: dict[str, Any], topic_map: dict[str, dict[str,
     execution["pass_queue"] = queue
 
 
+def append_unique_note(items: list[str], note: str) -> list[str]:
+    normalized = coerce_string_list(items)
+    text = coerce_string(note)
+    if text and text not in normalized:
+        normalized.append(text)
+    return normalized
+
+
+def mark_topic_complete_with_caveats(
+    entry: dict[str, Any],
+    *,
+    topic_id: str,
+    topic_map: dict[str, dict[str, Any]],
+    timestamp: str,
+    note: str,
+) -> None:
+    summary = coerce_string(entry.get("latest_summary"))
+    if not summary:
+        title = coerce_string(topic_map.get(topic_id, {}).get("title"), topic_id)
+        summary = f"Accepted with caveats after bounded research for {title}."
+
+    entry["status"] = "complete_with_caveats"
+    entry["latest_summary"] = summary
+    entry["unresolved_questions"] = append_unique_note(entry.get("unresolved_questions", []), note)
+    entry["updated_at"] = timestamp
+
+
+def enforce_topic_retry_limits(execution: dict[str, Any], topic_map: dict[str, dict[str, Any]], timestamp: str) -> list[str]:
+    topic_status = execution.get("topic_status")
+    if not isinstance(topic_status, dict):
+        return []
+
+    config = planning_config(execution)
+    max_passes_per_topic = config["max_passes_per_topic"]
+    capped_topic_ids: list[str] = []
+    note = (
+        f"Pass cap reached ({max_passes_per_topic}); accepting current findings with caveats."
+    )
+
+    for topic_id, raw_entry in topic_status.items():
+        if not isinstance(raw_entry, dict):
+            continue
+
+        status = coerce_string(raw_entry.get("status"), "pending")
+        if status not in TOPIC_ACTIVE_STATUSES:
+            continue
+
+        passes_attempted = coerce_positive_int(raw_entry.get("passes_attempted", 0), 0, minimum=0)
+        if passes_attempted < max_passes_per_topic:
+            continue
+
+        mark_topic_complete_with_caveats(
+            raw_entry,
+            topic_id=topic_id,
+            topic_map=topic_map,
+            timestamp=timestamp,
+            note=note,
+        )
+        capped_topic_ids.append(topic_id)
+
+    execution["topic_status"] = topic_status
+    return sorted(set(capped_topic_ids))
+
+
+def enforce_total_pass_limit(execution: dict[str, Any], topic_map: dict[str, dict[str, Any]], timestamp: str) -> list[str]:
+    history = execution.get("pass_history")
+    history = history if isinstance(history, list) else []
+    config = planning_config(execution)
+    max_total_passes = config["max_total_passes"]
+    if len(history) < max_total_passes:
+        return []
+
+    topic_status = execution.get("topic_status")
+    if not isinstance(topic_status, dict):
+        return []
+
+    capped_topic_ids: list[str] = []
+    note = (
+        f"Total pass cap reached ({max_total_passes}); accepting current findings with caveats."
+    )
+    for topic_id, raw_entry in topic_status.items():
+        if not isinstance(raw_entry, dict):
+            continue
+        status = coerce_string(raw_entry.get("status"), "pending")
+        if status not in TOPIC_ACTIVE_STATUSES:
+            continue
+
+        mark_topic_complete_with_caveats(
+            raw_entry,
+            topic_id=topic_id,
+            topic_map=topic_map,
+            timestamp=timestamp,
+            note=note,
+        )
+        capped_topic_ids.append(topic_id)
+
+    if capped_topic_ids:
+        execution["pass_queue"] = []
+        execution["topic_status"] = topic_status
+    return sorted(set(capped_topic_ids))
+
+
+def prune_pass_queue(execution: dict[str, Any]) -> None:
+    queue = execution.get("pass_queue")
+    if not isinstance(queue, list):
+        execution["pass_queue"] = []
+        return
+
+    topic_status = execution.get("topic_status")
+    topic_status = topic_status if isinstance(topic_status, dict) else {}
+    active_topic_ids = {
+        topic_id
+        for topic_id, entry in topic_status.items()
+        if isinstance(entry, dict) and coerce_string(entry.get("status"), "pending") in TOPIC_ACTIVE_STATUSES
+    }
+
+    filtered_queue: list[dict[str, Any]] = []
+    for entry in queue:
+        if not isinstance(entry, dict):
+            continue
+        topic_ids = [topic_id for topic_id in coerce_string_list(entry.get("topic_ids")) if topic_id in active_topic_ids]
+        if not topic_ids:
+            continue
+        status = coerce_string(entry.get("status"), "pending")
+        if status not in {"pending", "in_progress"}:
+            status = "pending"
+        filtered_queue.append(
+            {
+                "pass_id": coerce_string(entry.get("pass_id")),
+                "round": coerce_positive_int(entry.get("round", 0), 0, minimum=0),
+                "status": status,
+                "topic_ids": topic_ids,
+                "planned_effort": coerce_positive_int(entry.get("planned_effort", 0), 0, minimum=0),
+                "created_at": coerce_string(entry.get("created_at")),
+                "started_at": coerce_string(entry.get("started_at")),
+            }
+        )
+
+    execution["pass_queue"] = filtered_queue
+
+
 def recompute_execution_summary(execution: dict[str, Any]) -> None:
     topic_status = execution.get("topic_status")
     topic_status = topic_status if isinstance(topic_status, dict) else {}
@@ -360,7 +524,20 @@ def recompute_execution_summary(execution: dict[str, Any]) -> None:
     history = history if isinstance(history, list) else []
 
     total = len(topic_status)
-    complete = len([entry for entry in topic_status.values() if isinstance(entry, dict) and entry.get("status") == "complete"])
+    complete = len(
+        [
+            entry
+            for entry in topic_status.values()
+            if isinstance(entry, dict) and coerce_string(entry.get("status"), "pending") in TOPIC_COMPLETE_STATUSES
+        ]
+    )
+    caveated = len(
+        [
+            entry
+            for entry in topic_status.values()
+            if isinstance(entry, dict) and coerce_string(entry.get("status"), "pending") == "complete_with_caveats"
+        ]
+    )
     followup = len(
         [
             entry
@@ -408,6 +585,7 @@ def recompute_execution_summary(execution: dict[str, Any]) -> None:
     execution["summary"] = {
         "topic_total": total,
         "topic_complete": complete,
+        "topic_caveated": caveated,
         "topic_needs_followup": followup,
         "topic_pending": pending,
         "pass_pending": len(queue),
@@ -643,6 +821,10 @@ def handle_start(project_root: Path, args: argparse.Namespace) -> int:
         )
         return 2
 
+    enforce_topic_retry_limits(execution, topic_map, timestamp)
+    enforce_total_pass_limit(execution, topic_map, timestamp)
+    prune_pass_queue(execution)
+
     queue = execution.get("pass_queue")
     queue = queue if isinstance(queue, list) else []
     current_pass = next(
@@ -655,8 +837,9 @@ def handle_start(project_root: Path, args: argparse.Namespace) -> int:
     )
 
     if not isinstance(current_pass, dict):
-        if not queue:
+        if not queue and unresolved_topics(execution):
             rebuild_pass_queue(execution, topic_map, timestamp)
+            prune_pass_queue(execution)
             queue = execution.get("pass_queue", [])
         current_pass = next(
             (
@@ -695,7 +878,7 @@ def handle_start(project_root: Path, args: argparse.Namespace) -> int:
         entry = topic_status.get(topic_id)
         if not isinstance(entry, dict):
             continue
-        if coerce_string(entry.get("status"), "pending") != "complete":
+        if coerce_string(entry.get("status"), "pending") not in TOPIC_COMPLETE_STATUSES:
             if entry.get("status") != "needs_followup":
                 entry["status"] = "in_progress"
             entry["last_pass_id"] = pass_id
@@ -810,7 +993,7 @@ def handle_complete(project_root: Path, args: argparse.Namespace) -> int:
 
         unresolved = coerce_string_list(result.get("unresolved_questions"))
         if status == "complete" and unresolved:
-            status = "needs_followup"
+            status = "complete_with_caveats"
 
         summary = coerce_string(result.get("summary"))
         confidence = coerce_string(result.get("confidence"), "medium").lower()
@@ -841,12 +1024,7 @@ def handle_complete(project_root: Path, args: argparse.Namespace) -> int:
             }
             topic_status[topic_id] = entry
 
-        try:
-            passes_attempted = int(entry.get("passes_attempted", 0))
-        except (TypeError, ValueError):
-            passes_attempted = 0
-        if passes_attempted < 0:
-            passes_attempted = 0
+        passes_attempted = coerce_positive_int(entry.get("passes_attempted", 0), 0, minimum=0)
         entry["passes_attempted"] = passes_attempted + 1
         entry["status"] = status
         entry["last_pass_id"] = pass_id
@@ -894,13 +1072,17 @@ def handle_complete(project_root: Path, args: argparse.Namespace) -> int:
     )
     execution["pass_history"] = history
 
-    # Remove the completed in-progress pass and dynamically rebuild next passes.
+    # Remove the completed in-progress pass. Re-plan only at round boundaries.
     execution["pass_queue"] = [
         entry
         for entry in queue
         if isinstance(entry, dict) and coerce_string(entry.get("pass_id")) != pass_id
     ]
-    rebuild_pass_queue(execution, topic_map, timestamp)
+    enforce_topic_retry_limits(execution, topic_map, timestamp)
+    enforce_total_pass_limit(execution, topic_map, timestamp)
+    prune_pass_queue(execution)
+    if not execution.get("pass_queue") and unresolved_topics(execution):
+        rebuild_pass_queue(execution, topic_map, timestamp)
 
     recompute_execution_summary(execution)
     summary = execution.get("summary", {})

package/skill/skills/researcher/SKILL.md

@@ -26,7 +26,7 @@ description: Execute ideation research agenda topics through dynamic multi-pass
    - `topics` (array)
    - Each `topics[]` item must include:
      - `topic_id` (string, must be in current pass topic_ids)
-     - `status` (`complete` or `needs_followup`)
+     - `status` (`complete`, `complete_with_caveats`, or `needs_followup`)
      - `summary` (string)
      - `confidence` (`low|medium|high`)
      - `unresolved_questions` (array of strings)

package/skill/tests/test_ideation_research.py

@@ -7,7 +7,11 @@ SCRIPTS_DIR = Path(__file__).resolve().parents[1] / "scripts"
 if str(SCRIPTS_DIR) not in sys.path:
     sys.path.insert(0, str(SCRIPTS_DIR))
 
-from ideation_research import ResearchAgendaValidationError, normalize_ideation_research
+from ideation_research import (
+    ResearchAgendaValidationError,
+    ensure_ideation_research_defaults,
+    normalize_ideation_research,
+)
 
 
 def base_payload() -> dict:
@@ -141,6 +145,41 @@ class IdeationResearchNormalizationTests(unittest.TestCase):
 
         self.assertEqual(block_b_topic["related_entities"], ["entity-marketplace-fees"])
 
+    def test_execution_normalization_supports_caveated_completion_and_planning_caps(self) -> None:
+        payload = base_payload()
+        payload["research_execution"] = {
+            "planning": {
+                "target_effort_per_pass": 10,
+                "max_topics_per_pass": 2,
+                "max_passes_per_topic": 0,
+                "max_total_passes": -1,
+                "latest_round": 4,
+            },
+            "topic_status": {
+                "topic-a1": {
+                    "status": "complete_with_caveats",
+                    "passes_attempted": 3,
+                    "latest_summary": "Accepted with caveats.",
+                },
+                "topic-b1": {
+                    "status": "pending",
+                    "passes_attempted": 0,
+                },
+            },
+            "pass_queue": [],
+            "pass_history": [],
+        }
+
+        normalized_agenda = normalize_ideation_research(copy.deepcopy(payload), require_topics=True)
+        normalized = ensure_ideation_research_defaults(normalized_agenda)
+        execution = normalized["research_execution"]
+
+        self.assertEqual(execution["topic_status"]["topic-a1"]["status"], "complete_with_caveats")
+        self.assertEqual(execution["summary"]["topic_complete"], 1)
+        self.assertEqual(execution["summary"]["topic_caveated"], 1)
+        self.assertEqual(execution["planning"]["max_passes_per_topic"], 1)
+        self.assertEqual(execution["planning"]["max_total_passes"], 1)
+
 
 if __name__ == "__main__":
     unittest.main()

package/skill/tests/test_run_research_pass.py

@@ -4,6 +4,7 @@ import sys
 import tempfile
 import unittest
 from pathlib import Path
+from typing import Any
 
 SCRIPTS_DIR = Path(__file__).resolve().parents[1] / "scripts"
 if str(SCRIPTS_DIR) not in sys.path:
@@ -15,7 +16,13 @@ from workflow_state import default_data, reconcile_workflow_state, set_workflow_
 RUN_RESEARCH_PASS_SCRIPT = SCRIPTS_DIR / "run-research-pass.py"
 
 
-def build_cadence_state() -> dict:
+def build_cadence_state(
+    *,
+    pass_queue: list[dict[str, Any]] | None = None,
+    planning_overrides: dict[str, Any] | None = None,
+    topic_status_overrides: dict[str, dict[str, Any]] | None = None,
+    pass_history: list[dict[str, Any]] | None = None,
+) -> dict[str, Any]:
     data = default_data()
     data.setdefault("state", {})["project-mode"] = "greenfield"
     for task_id in (
@@ -76,17 +83,32 @@ def build_cadence_state() -> dict:
     ideation = reset_research_execution(ideation)
 
     execution = ideation.get("research_execution", {})
-    execution["pass_queue"] = [
-        {
-            "pass_id": "pass-r1-01",
-            "round": 1,
-            "status": "in_progress",
-            "topic_ids": ["topic-one", "topic-two"],
-            "planned_effort": 4,
-            "created_at": "2026-01-01T00:00:00Z",
-            "started_at": "2026-01-01T00:00:01Z",
-        }
-    ]
+    if pass_queue is None:
+        pass_queue = [
+            {
+                "pass_id": "pass-r1-01",
+                "round": 1,
+                "status": "in_progress",
+                "topic_ids": ["topic-one", "topic-two"],
+                "planned_effort": 4,
+                "created_at": "2026-01-01T00:00:00Z",
+                "started_at": "2026-01-01T00:00:01Z",
+            }
+        ]
+    execution["pass_queue"] = pass_queue
+    if planning_overrides:
+        execution.setdefault("planning", {}).update(planning_overrides)
+    if pass_history is not None:
+        execution["pass_history"] = pass_history
+
+    topic_status = execution.get("topic_status", {})
+    if topic_status_overrides:
+        for topic_id, updates in topic_status_overrides.items():
+            existing = topic_status.get(topic_id)
+            if not isinstance(existing, dict):
+                continue
+            existing.update(updates)
+
     execution["status"] = "in_progress"
     data["ideation"] = ideation
     data.setdefault("state", {})["ideation-completed"] = True
@@ -94,14 +116,54 @@ def build_cadence_state() -> dict:
     return reconcile_workflow_state(data, cadence_dir_exists=True)
 
 
+def write_state(project_root: Path, state: dict[str, Any]) -> Path:
+    cadence_dir = project_root / ".cadence"
+    cadence_dir.mkdir(parents=True, exist_ok=True)
+    cadence_json = cadence_dir / "cadence.json"
+    cadence_json.write_text(json.dumps(state, indent=4) + "\n", encoding="utf-8")
+    return cadence_json
+
+
+def run_complete(project_root: Path, *, pass_id: str, payload: dict[str, Any]) -> subprocess.CompletedProcess[str]:
+    return subprocess.run(
+        [
+            sys.executable,
+            str(RUN_RESEARCH_PASS_SCRIPT),
+            "--project-root",
+            str(project_root),
+            "complete",
+            "--pass-id",
+            pass_id,
+            "--json",
+            json.dumps(payload),
+        ],
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+
+
+def run_start(project_root: Path) -> subprocess.CompletedProcess[str]:
+    return subprocess.run(
+        [
+            sys.executable,
+            str(RUN_RESEARCH_PASS_SCRIPT),
+            "--project-root",
+            str(project_root),
+            "start",
+            "--ack-handoff",
+        ],
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+
+
 class RunResearchPassValidationTests(unittest.TestCase):
     def test_complete_requires_result_for_every_topic_in_pass(self) -> None:
         with tempfile.TemporaryDirectory() as tmp_dir:
             project_root = Path(tmp_dir)
-            cadence_dir = project_root / ".cadence"
-            cadence_dir.mkdir(parents=True, exist_ok=True)
-            cadence_json = cadence_dir / "cadence.json"
-            cadence_json.write_text(json.dumps(build_cadence_state(), indent=4) + "\n", encoding="utf-8")
+            write_state(project_root, build_cadence_state())
 
             payload = {
                 "topics": [
@@ -116,27 +178,293 @@ class RunResearchPassValidationTests(unittest.TestCase):
                 ]
             }
 
-            result = subprocess.run(
-                [
-                    sys.executable,
-                    str(RUN_RESEARCH_PASS_SCRIPT),
-                    "--project-root",
-                    str(project_root),
-                    "complete",
-                    "--pass-id",
-                    "pass-r1-01",
-                    "--json",
-                    json.dumps(payload),
-                ],
-                capture_output=True,
-                text=True,
-                check=False,
-            )
+            result = run_complete(project_root, pass_id="pass-r1-01", payload=payload)
 
             self.assertEqual(result.returncode, 2)
             self.assertIn("PASS_RESULT_MISSING_TOPICS", result.stderr)
             self.assertIn("topic-two", result.stderr)
 
+    def test_does_not_replan_queue_mid_round_after_followup(self) -> None:
+        with tempfile.TemporaryDirectory() as tmp_dir:
+            project_root = Path(tmp_dir)
+            write_state(
+                project_root,
+                build_cadence_state(
+                    pass_queue=[
+                        {
+                            "pass_id": "pass-r1-01",
+                            "round": 1,
+                            "status": "in_progress",
+                            "topic_ids": ["topic-one"],
+                            "planned_effort": 2,
+                            "created_at": "2026-01-01T00:00:00Z",
+                            "started_at": "2026-01-01T00:00:01Z",
+                        },
+                        {
+                            "pass_id": "pass-r1-02",
+                            "round": 1,
+                            "status": "pending",
+                            "topic_ids": ["topic-two"],
+                            "planned_effort": 2,
+                            "created_at": "2026-01-01T00:00:00Z",
+                            "started_at": "",
+                        },
+                    ]
+                ),
+            )
+
+            payload = {
+                "pass_summary": "Topic one needs one more pass.",
+                "topics": [
+                    {
+                        "topic_id": "topic-one",
+                        "status": "needs_followup",
+                        "summary": "Need one more clarification.",
+                        "confidence": "medium",
+                        "unresolved_questions": ["Open question"],
+                        "sources": [{"url": "https://example.com/1"}],
+                    }
+                ],
+            }
+            result = run_complete(project_root, pass_id="pass-r1-01", payload=payload)
+
+            self.assertEqual(result.returncode, 0, msg=result.stderr or result.stdout)
+            output = json.loads(result.stdout)
+            self.assertEqual(output["summary"]["next_pass_id"], "pass-r1-02")
+
+            state = json.loads((project_root / ".cadence" / "cadence.json").read_text(encoding="utf-8"))
+            queue = state["ideation"]["research_execution"]["pass_queue"]
+            self.assertEqual(len(queue), 1)
+            self.assertEqual(queue[0]["pass_id"], "pass-r1-02")
+            self.assertEqual(queue[0]["topic_ids"], ["topic-two"])
+
+    def test_replans_when_round_queue_drains(self) -> None:
+        with tempfile.TemporaryDirectory() as tmp_dir:
+            project_root = Path(tmp_dir)
+            write_state(
+                project_root,
+                build_cadence_state(
+                    pass_queue=[
+                        {
+                            "pass_id": "pass-r1-01",
+                            "round": 1,
+                            "status": "in_progress",
+                            "topic_ids": ["topic-one"],
+                            "planned_effort": 2,
+                            "created_at": "2026-01-01T00:00:00Z",
+                            "started_at": "2026-01-01T00:00:01Z",
+                        }
+                    ],
+                    topic_status_overrides={"topic-two": {"status": "complete"}},
+                ),
+            )
+
+            payload = {
+                "pass_summary": "Topic one still needs follow-up.",
+                "topics": [
+                    {
+                        "topic_id": "topic-one",
+                        "status": "needs_followup",
+                        "summary": "Need one more clarification.",
+                        "confidence": "medium",
+                        "unresolved_questions": ["Open question"],
+                        "sources": [{"url": "https://example.com/2"}],
+                    }
+                ],
+            }
+            result = run_complete(project_root, pass_id="pass-r1-01", payload=payload)
+
+            self.assertEqual(result.returncode, 0, msg=result.stderr or result.stdout)
+            output = json.loads(result.stdout)
+            self.assertEqual(output["summary"]["next_pass_id"], "pass-r2-01")
+
+            state = json.loads((project_root / ".cadence" / "cadence.json").read_text(encoding="utf-8"))
+            queue = state["ideation"]["research_execution"]["pass_queue"]
+            self.assertEqual(len(queue), 1)
+            self.assertEqual(queue[0]["pass_id"], "pass-r2-01")
+            self.assertEqual(queue[0]["topic_ids"], ["topic-one"])
+
+    def test_complete_with_unresolved_questions_becomes_complete_with_caveats(self) -> None:
+        with tempfile.TemporaryDirectory() as tmp_dir:
+            project_root = Path(tmp_dir)
+            write_state(
+                project_root,
+                build_cadence_state(
+                    pass_queue=[
+                        {
+                            "pass_id": "pass-r1-01",
+                            "round": 1,
+                            "status": "in_progress",
+                            "topic_ids": ["topic-one"],
+                            "planned_effort": 2,
+                            "created_at": "2026-01-01T00:00:00Z",
+                            "started_at": "2026-01-01T00:00:01Z",
+                        }
+                    ],
+                    topic_status_overrides={"topic-two": {"status": "complete"}},
+                ),
+            )
+
+            payload = {
+                "pass_summary": "Topic one finalized with caveats.",
+                "topics": [
+                    {
+                        "topic_id": "topic-one",
+                        "status": "complete",
+                        "summary": "Primary recommendation stands.",
+                        "confidence": "high",
+                        "unresolved_questions": ["Need direct vendor confirmation"],
+                        "sources": [{"url": "https://example.com/3"}],
+                    }
+                ],
+            }
+            result = run_complete(project_root, pass_id="pass-r1-01", payload=payload)
+
+            self.assertEqual(result.returncode, 0, msg=result.stderr or result.stdout)
+            output = json.loads(result.stdout)
+            self.assertTrue(output["research_complete"])
+
+            state = json.loads((project_root / ".cadence" / "cadence.json").read_text(encoding="utf-8"))
+            topic_one = state["ideation"]["research_execution"]["topic_status"]["topic-one"]
+            self.assertEqual(topic_one["status"], "complete_with_caveats")
+            self.assertTrue(state["state"]["research-completed"])
+
+    def test_topic_pass_cap_converts_followup_to_complete_with_caveats(self) -> None:
+        with tempfile.TemporaryDirectory() as tmp_dir:
+            project_root = Path(tmp_dir)
+            write_state(
+                project_root,
+                build_cadence_state(
+                    pass_queue=[
+                        {
+                            "pass_id": "pass-r1-01",
+                            "round": 1,
+                            "status": "in_progress",
+                            "topic_ids": ["topic-one"],
+                            "planned_effort": 2,
+                            "created_at": "2026-01-01T00:00:00Z",
+                            "started_at": "2026-01-01T00:00:01Z",
+                        }
+                    ],
+                    planning_overrides={"max_passes_per_topic": 2},
+                    topic_status_overrides={
+                        "topic-one": {"passes_attempted": 1},
+                        "topic-two": {"status": "complete"},
+                    },
+                ),
+            )
+
+            payload = {
+                "pass_summary": "Reached cap on topic one.",
+                "topics": [
+                    {
+                        "topic_id": "topic-one",
+                        "status": "needs_followup",
+                        "summary": "Best available recommendation captured.",
+                        "confidence": "high",
+                        "unresolved_questions": ["Need commercial confirmation"],
+                        "sources": [{"url": "https://example.com/4"}],
+                    }
+                ],
+            }
+            result = run_complete(project_root, pass_id="pass-r1-01", payload=payload)
+
+            self.assertEqual(result.returncode, 0, msg=result.stderr or result.stdout)
+            output = json.loads(result.stdout)
+            self.assertTrue(output["research_complete"])
+
+            state = json.loads((project_root / ".cadence" / "cadence.json").read_text(encoding="utf-8"))
+            topic_one = state["ideation"]["research_execution"]["topic_status"]["topic-one"]
+            self.assertEqual(topic_one["status"], "complete_with_caveats")
+            self.assertGreaterEqual(topic_one["passes_attempted"], 2)
+            self.assertEqual(state["ideation"]["research_execution"]["summary"]["pass_pending"], 0)
+
+    def test_total_pass_cap_finishes_remaining_topics(self) -> None:
+        with tempfile.TemporaryDirectory() as tmp_dir:
+            project_root = Path(tmp_dir)
+            write_state(
+                project_root,
+                build_cadence_state(
+                    pass_queue=[
+                        {
+                            "pass_id": "pass-r1-01",
+                            "round": 1,
+                            "status": "in_progress",
+                            "topic_ids": ["topic-one"],
+                            "planned_effort": 2,
+                            "created_at": "2026-01-01T00:00:00Z",
+                            "started_at": "2026-01-01T00:00:01Z",
+                        },
+                        {
+                            "pass_id": "pass-r1-02",
+                            "round": 1,
+                            "status": "pending",
+                            "topic_ids": ["topic-two"],
+                            "planned_effort": 2,
+                            "created_at": "2026-01-01T00:00:00Z",
+                            "started_at": "",
+                        },
+                    ],
+                    planning_overrides={"max_total_passes": 1},
+                    pass_history=[
+                        {
+                            "pass_id": "pass-r0-01",
+                            "round": 0,
+                            "completed_at": "2026-01-01T00:00:00Z",
+                            "pass_summary": "Previous pass",
+                            "topics": [],
+                            "source_ids": [],
+                        }
+                    ],
+                ),
+            )
+
+            payload = {
+                "pass_summary": "Hit global cap.",
+                "topics": [
+                    {
+                        "topic_id": "topic-one",
+                        "status": "needs_followup",
+                        "summary": "Sufficient for now.",
+                        "confidence": "medium",
+                        "unresolved_questions": ["Could investigate more"],
+                        "sources": [{"url": "https://example.com/5"}],
+                    }
+                ],
+            }
+            result = run_complete(project_root, pass_id="pass-r1-01", payload=payload)
+
+            self.assertEqual(result.returncode, 0, msg=result.stderr or result.stdout)
+            output = json.loads(result.stdout)
+            self.assertTrue(output["research_complete"])
+
+            state = json.loads((project_root / ".cadence" / "cadence.json").read_text(encoding="utf-8"))
+            execution = state["ideation"]["research_execution"]
+            self.assertEqual(execution["summary"]["pass_pending"], 0)
+            self.assertEqual(execution["topic_status"]["topic-one"]["status"], "complete_with_caveats")
+            self.assertEqual(execution["topic_status"]["topic-two"]["status"], "complete_with_caveats")
+
+    def test_start_prioritizes_pending_topics_before_repeat_followups(self) -> None:
+        with tempfile.TemporaryDirectory() as tmp_dir:
+            project_root = Path(tmp_dir)
+            write_state(
+                project_root,
+                build_cadence_state(
+                    pass_queue=[],
+                    planning_overrides={"max_topics_per_pass": 1, "target_effort_per_pass": 10},
+                    topic_status_overrides={
+                        "topic-one": {"status": "needs_followup", "passes_attempted": 5},
+                        "topic-two": {"status": "pending", "passes_attempted": 0},
+                    },
+                ),
+            )
+
+            result = run_start(project_root)
+
+            self.assertEqual(result.returncode, 0, msg=result.stderr or result.stdout)
+            output = json.loads(result.stdout)
+            self.assertEqual(output["pass"]["topic_ids"], ["topic-two"])
+
 
 if __name__ == "__main__":
     unittest.main()