`918941f`

Generalize workflow recovery steering

Authored by

espadonne 3 weeks ago

SHA: 918941fbed1f1abed10bcd75b830973e65bba696
Parents: a759233
Tree: 0185e0b

15 changed files

Status	File	+	-
M	`src/loader/runtime/compaction.py`	91	77
M	`src/loader/runtime/dod.py`	9	57
M	`src/loader/runtime/finalization.py`	12	31
M	`src/loader/runtime/safeguard_services.py`	25	269
A	`src/loader/runtime/semantic_rules/__init__.py`	2	0
A	`src/loader/runtime/semantic_rules/html_toc.py`	506	0
M	`src/loader/runtime/tool_batch_recovery.py`	74	15
M	`src/loader/runtime/tool_batches.py`	160	60
M	`src/loader/runtime/workflow.py`	210	0
M	`src/loader/runtime/workflow_lanes.py`	37	9
M	`tests/test_runtime_harness.py`	7	5
M	`tests/test_safeguard_services.py`	26	10
M	`tests/test_tool_batch_policies.py`	98	1
M	`tests/test_tool_batches.py`	317	4
M	`tests/test_workflow.py`	111	0

src/loader/runtime/compaction.pymodified

  from __future__ import annotations
 -import html
  import re
  from collections import Counter
  from dataclasses import dataclass
  from pathlib import Path
  from ..llm.base import Message, Role, ToolCall
 +from .semantic_rules import html_toc as html_toc_rule
  DEFAULT_AUTO_COMPACTION_INPUT_TOKENS_THRESHOLD = 100_000
  MIN_AUTO_COMPACTION_INPUT_TOKENS_THRESHOLD = 12_000
      return files
 -def summarize_confirmed_facts(messages: list[Message], *, max_items: int = 2) -> str | None:
 +def summarize_confirmed_facts(
 +    messages: list[Message],
 +    *,
 +    max_items: int = 2,
 +    focus_path: str | None = None,
 +) -> str | None:
      """Summarize recent confirmed discoveries from successful tool results."""
 -    facts = _collect_confirmed_facts(messages)
 +    relevant_messages = _messages_for_focus_path(messages, focus_path=focus_path)
 +    facts = _collect_confirmed_facts(relevant_messages)
      if not facts:
          return None
      messages: list[Message],
      *,
      current_task: str | None = None,
 +    focus_path: str | None = None,
  ) -> str | None:
      """Infer one concrete next step from the task and recent transcript."""
 -    if summarize_confirmed_facts(messages, max_items=1) is None:
 +    relevant_messages = _messages_for_focus_path(messages, focus_path=focus_path)
 +    if summarize_confirmed_facts(
 +        relevant_messages,
 +        max_items=1,
 +        focus_path=focus_path,
 +    ) is None:
          return None
 -    target_path = _choose_target_path(messages, current_task=current_task)
 -    has_confirmed_titles = _summarize_html_title_discovery(messages) is not None
 -    verification_gap = _summarize_latest_html_verification_gap(messages)
 +    target_path = _choose_target_path(
 +        relevant_messages,
 +        current_task=current_task,
 +        focus_path=focus_path,
 +    )
 +    has_confirmed_titles = _summarize_html_title_discovery(relevant_messages) is not None
 +    verification_gap = _summarize_latest_html_verification_gap(relevant_messages)
      if target_path:
          if verification_gap:
              return (
          if not isinstance(raw_path, str):
              continue
          normalized_path = _normalize_path_candidate(raw_path) or raw_path
 -        if Path(normalized_path).name == "index.html" or "/chapters/" not in normalized_path:
 +        if html_toc_rule.is_html_toc_index_path(normalized_path) or "/chapters/" not in normalized_path:
              continue
          payload = "\n".join(
              for result in message.tool_results
              if result.content.strip()
          ) or message.content
 -        title = _extract_html_title(payload)
 +        title = html_toc_rule.extract_html_title_from_text(payload)
          if not title:
              continue
      return f"Chapter titles confirmed: {preview}"
 -def _extract_html_title(payload: str) -> str | None:
 -    for pattern in (
 -        r"<h1[^>]*>(.*?)</h1>",
 -        r"<title[^>]*>(.*?)</title>",
 -    ):
 -        match = re.search(pattern, payload, re.IGNORECASE | re.DOTALL)
 -        if not match:
 -            continue
 -        title = re.sub(r"<[^>]+>", " ", match.group(1))
 -        title = _collapse_inline_whitespace(html.unescape(title))
 -        if title:
 -            return title
 -    return None
+-
+-
  def _collect_html_file_discovery_fact(
      messages: list[Message],
      *,
              for result in message.tool_results
              if result.content.strip()
          ) or message.content
 -        gap = _extract_html_verification_gap(payload, max_items=max_items)
 +        gap = html_toc_rule.summarize_html_toc_verification_gap(
 +            payload,
 +            max_items=max_items,
 +        )
          if gap:
              return gap
      return None
 -def _extract_html_verification_gap(payload: str, *, max_items: int = 2) -> str | None:
 -    missing: list[str] = []
 -    mismatches: list[str] = []
 -    mode: str | None = None
+-
 -    for raw_line in payload.splitlines():
 -        line = raw_line.strip()
 -        if not line:
 -            continue
 -        lowered = line.lower()
 -        if lowered == "missing links:":
 -            mode = "missing"
 -            continue
 -        if lowered == "title mismatches:":
 -            mode = "mismatch"
 -            continue
 -        if mode == "missing" and "->" in line:
 -            href = line.split("->", 1)[0].strip()
 -            if href and href not in missing:
 -                missing.append(href)
 -            continue
 -        if mode == "mismatch" and "!=" in line:
 -            if line not in mismatches:
 -                mismatches.append(line)
+-
 -    parts: list[str] = []
 -    if missing:
 -        preview = ", ".join(missing[:max_items])
 -        if len(missing) > max_items:
 -            preview += ", ..."
 -        parts.append(f"missing TOC links {preview}")
 -    if mismatches:
 -        preview = ", ".join(mismatches[:max_items])
 -        if len(mismatches) > max_items:
 -            preview += ", ..."
 -        parts.append(f"title mismatches {preview}")
 -    return "; ".join(parts) if parts else None
+-
+-
  def _summarize_html_file_discovery(payload: str) -> str | None:
 -    filenames = re.findall(r"([A-Za-z0-9_.-]+\.html)", payload)
 -    unique_names: list[str] = []
 -    for name in filenames:
 -        if name not in unique_names:
 -            unique_names.append(name)
 -    if len(unique_names) < 3:
 -        return None
 -    preview = ", ".join(unique_names[:6])
 -    if len(unique_names) > 6:
 -        preview += ", ..."
 -    return f"Existing files include {preview}"
 +    return html_toc_rule.summarize_html_file_discovery(payload)
  def _resolve_tool_name(
      messages: list[Message],
      *,
      current_task: str | None = None,
 +    focus_path: str | None = None,
  ) -> str | None:
 +    if focus_path:
 +        normalized_focus = _normalize_path_candidate(focus_path)
 +        if normalized_focus:
 +            resolved_focus = html_toc_rule.resolve_html_toc_index_path(normalized_focus)
 +            if resolved_focus is not None:
 +                return str(resolved_focus)
 +            return normalized_focus
++
      candidates: Counter[str] = Counter()
      for message in messages:
          for tool_call in message.tool_calls:
              if not normalized:
                  continue
              path_name = Path(normalized).name
 -            if path_name == "index.html":
 +            if html_toc_rule.is_html_toc_index_path(normalized):
                  candidates[normalized] += 10
              elif path_name.endswith(".html") and "/chapters/" not in normalized:
                  candidates[normalized] += 4
          return None
      current_task_paths = extract_key_files([Message(role=Role.USER, content=current_task)], limit=3)
      for path in current_task_paths:
 -        if Path(path).name == "index.html":
 +        if html_toc_rule.is_html_toc_index_path(path):
              return path
      return current_task_paths[0] if current_task_paths else None
++
++
 +def _messages_for_focus_path(
 +    messages: list[Message],
 +    *,
 +    focus_path: str | None = None,
 +) -> list[Message]:
 +    if not focus_path:
 +        return messages
++
 +    anchors = _focus_path_anchors(focus_path)
 +    if not anchors:
 +        return messages
++
 +    filtered = [
 +        message
 +        for message in messages
 +        if _message_matches_focus_path(message, anchors)
 +    ]
 +    return filtered or messages
++
++
 +def _focus_path_anchors(focus_path: str) -> tuple[str, ...]:
 +    normalized_focus = _normalize_path_candidate(focus_path) or str(
 +        Path(focus_path).expanduser()
 +    )
 +    focus = Path(normalized_focus).expanduser()
 +    anchors = {str(focus)}
++
 +    resolved_index = html_toc_rule.resolve_html_toc_index_path(focus)
 +    if resolved_index is not None:
 +        anchors.add(str(resolved_index))
 +        anchors.add(str(resolved_index.parent))
 +        anchors.add(str(resolved_index.parent / "chapters"))
 +    else:
 +        anchors.add(str(focus.parent))
++
 +    return tuple(anchor for anchor in anchors if anchor)
++
++
 +def _message_matches_focus_path(message: Message, anchors: tuple[str, ...]) -> bool:
 +    if any(anchor in str(message.content or "") for anchor in anchors):
 +        return True
++
 +    for tool_call in message.tool_calls:
 +        for key in ("file_path", "path", "cwd"):
 +            value = tool_call.arguments.get(key)
 +            if isinstance(value, str) and any(anchor in value for anchor in anchors):
 +                return True
 +    return False

src/loader/runtime/dod.pymodified

  from ..llm.base import ToolCall
  from ..tools.shell_tools import BashTool
 +from .semantic_rules import html_toc as html_toc_rule
  from .verification_observations import VerificationAttempt, verification_attempt_id
  TaskSize = Literal["small", "standard", "large"]
      task_statement: str,
  ) -> str | None:
      task_hints = " ".join([task_statement, *dod.acceptance_criteria]).lower()
 -    if not any(
 -        hint in task_hints
 -        for hint in ("href", "link", "links", "table of contents", "chapter title")
 -    ):
 +    if not html_toc_rule.task_targets_html_toc(task_hints):
          return None
      for path_str in dod.touched_files:
          path = Path(path_str)
          effective_path = path if path.is_absolute() else (project_root / path)
 -        if effective_path.name != "index.html" or effective_path.suffix != ".html":
 -            continue
 -        if not (effective_path.parent / "chapters").is_dir():
 -            continue
 -        return _build_html_toc_verification_command(effective_path)
 +        command = html_toc_rule.build_html_toc_verification_command(effective_path)
 +        if command:
 +            return command
      return None
  def _build_html_toc_verification_command(index_path: Path) -> str:
 -    path_literal = repr(str(index_path))
 -    return "\n".join(
 -        [
 -            "python3 - <<'PY'",
 -            "from pathlib import Path",
 -            "import re",
 -            "import sys",
 -            "",
 -            f"index = Path({path_literal}).expanduser()",
 -            "root = index.parent",
 -            "text = index.read_text()",
 -            "section_match = re.search(r'<ul class=\"chapter-list\">(.*?)</ul>', text, re.S)",
 -            "if section_match is None:",
 -            "    print('Missing chapter-list table of contents', file=sys.stderr)",
 -            "    raise SystemExit(1)",
 -            "links = re.findall(r'<a href=\"([^\"]+)\">([^<]+)</a>', section_match.group(1))",
 -            "if not links:",
 -            "    print('No chapter links found in table of contents', file=sys.stderr)",
 -            "    raise SystemExit(1)",
 -            "",
 -            "missing = []",
 -            "mismatched = []",
 -            "for href, label in links:",
 -            "    target = (root / href).resolve()",
 -            "    if not target.exists():",
 -            "        missing.append(f'{href} -> missing')",
 -            "        continue",
 -            "    body = target.read_text()",
 -            "    match = re.search(r'<h1>(.*?)</h1>', body, re.S)",
 -            "    title = match.group(1).strip() if match else ''",
 -            "    if title and label.strip() != title:",
 -            "        mismatched.append(f'{href} -> {label.strip()} != {title}')",
 -            "",
 -            "if missing or mismatched:",
 -            "    if missing:",
 -            "        print('Missing links:', file=sys.stderr)",
 -            "        for item in missing:",
 -            "            print(item, file=sys.stderr)",
 -            "    if mismatched:",
 -            "        print('Title mismatches:', file=sys.stderr)",
 -            "        for item in mismatched:",
 -            "            print(item, file=sys.stderr)",
 -            "    raise SystemExit(1)",
 -            "",
 -            "print(f'validated {len(links)} toc links in {index.name}')",
 -            "PY",
 -        ]
 -    )
 +    command = html_toc_rule.build_html_toc_verification_command(index_path)
 +    if command is None:
 +        raise ValueError(f"{index_path} is not a valid HTML TOC target")
 +    return command
  def _first_non_empty_line(text: str) -> str:

src/loader/runtime/finalization.pymodified

  from .logging import get_runtime_logger
  from .memory import MemoryStore
  from .policy_timeline import append_verification_timeline_entry
 +from .semantic_rules import html_toc as html_toc_rule
  from .session import normalize_usage
  from .tracing import RuntimeTracer
  from .verification_observations import (
      attempt_id: str | None,
      attempt_number: int | None,
  ) -> VerificationObservation:
 -    command = evidence.command or "verification"
      return VerificationObservation(
          status=(
              VerificationObservationStatus.SKIPPED.value
      fixes: list[str] = []
      for evidence in evidence_items:
          for candidate in (evidence.stderr, evidence.output, evidence.stdout):
 -            missing, mismatches = _parse_verification_failures(str(candidate))
 +            missing, mismatches = html_toc_rule.parse_html_toc_verification_failures(
 +                str(candidate)
 +            )
              for href in missing:
 -                item = f"Fix the missing TOC href `{href}` in `index.html`."
 +                item = (
 +                    f"Fix the missing TOC href `{href}` in the target HTML "
 +                    "table-of-contents page."
 +                )
                  if item not in fixes:
                      fixes.append(item)
              for mismatch in mismatches:
 -                item = f"Fix the TOC label mismatch `{mismatch}`."
 +                item = (
 +                    f"Fix the TOC label mismatch `{mismatch}` in the target HTML "
 +                    "table-of-contents page."
 +                )
                  if item not in fixes:
                      fixes.append(item)
      return fixes
 -def _parse_verification_failures(text: str) -> tuple[list[str], list[str]]:
 -    missing: list[str] = []
 -    mismatches: list[str] = []
 -    mode: str | None = None
+-
 -    for raw_line in text.splitlines():
 -        line = raw_line.strip()
 -        if not line:
 -            continue
 -        lowered = line.lower()
 -        if lowered == "missing links:":
 -            mode = "missing"
 -            continue
 -        if lowered == "title mismatches:":
 -            mode = "mismatch"
 -            continue
 -        if mode == "missing" and "->" in line:
 -            href = line.split("->", 1)[0].strip()
 -            if href and href not in missing:
 -                missing.append(href)
 -            continue
 -        if mode == "mismatch" and "!=" in line and line not in mismatches:
 -            mismatches.append(line)
+-
 -    return missing, mismatches
+-
+-
  def _classify_verification_kind(command: str) -> str:
      """Classify the verification command into a summary kind."""

src/loader/runtime/safeguard_services.pymodified

  import re
  import shlex
 -from difflib import get_close_matches
  from dataclasses import dataclass
 +from difflib import get_close_matches
  from pathlib import Path
 +from .semantic_rules import html_toc as html_toc_rule
  TEXT_REWRITE_SUFFIXES = frozenset(
+     {
      return None
 -def extract_html_title_from_text(payload: str) -> str | None:
 -    """Extract one human-readable HTML title from raw file contents."""
+-
 -    for pattern in (r"<h1[^>]*>(.*?)</h1>", r"<title[^>]*>(.*?)</title>"):
 -        match = re.search(pattern, payload, re.IGNORECASE | re.DOTALL)
 -        if not match:
 -            continue
 -        title = re.sub(r"<[^>]+>", " ", match.group(1))
 -        normalized = " ".join(title.split()).strip()
 -        if normalized:
 -            return normalized
 -    return None
+-
+-
 -def read_html_title(path: Path) -> str:
 -    """Read one HTML file title for inventory and validation helpers."""
+-
 -    try:
 -        return extract_html_title_from_text(path.read_text()) or ""
 -    except OSError:
 -        return ""
+-
+-
 -def format_html_inventory_entry(root: Path, candidate: Path) -> str:
 -    """Format one exact href/title pair for model-facing guidance."""
+-
 -    normalized_root = root.expanduser().resolve(strict=False)
 -    normalized_candidate = candidate.expanduser().resolve(strict=False)
 -    try:
 -        href = str(normalized_candidate.relative_to(normalized_root))
 -    except ValueError:
 -        href = normalized_candidate.name
 -    title = read_html_title(candidate)
 -    if title:
 -        return f"{href} = {title}"
 -    return href
+-
+-
 -def _collect_html_inventory_entries(index_path: str | Path) -> list[tuple[str, str]]:
 -    """Return exact href/title pairs for sibling HTML chapters."""
+-
 -    index = Path(index_path).expanduser()
 -    if index.name != "index.html":
 -        return []
+-
 -    chapters_dir = index.parent / "chapters"
 -    if not chapters_dir.is_dir():
 -        return []
+-
 -    entries: list[tuple[str, str]] = []
 -    for candidate in sorted(chapters_dir.glob("*.html")):
 -        if not candidate.is_file():
 -            continue
 -        title = read_html_title(candidate)
 -        if not title:
 -            continue
 -        href = format_html_inventory_entry(index.parent, candidate).split(" = ", 1)[0]
 -        entries.append((href, title))
 -    return entries
+-
+-
 -def summarize_html_inventory(
 -    index_path: str | Path,
 -    *,
 -    limit: int | None = 12,
 -) -> str | None:
 -    """Summarize the existing sibling HTML inventory for one index page."""
+-
 -    index = Path(index_path).expanduser()
 -    if index.name != "index.html":
 -        return None
+-
 -    entries = [f"{href} = {title}" for href, title in _collect_html_inventory_entries(index)]
 -    if not entries:
 -        return None
+-
 -    if limit is not None and len(entries) > limit:
 -        return "; ".join(entries[:limit]) + "; ..."
 -    return "; ".join(entries)
+-
+-
 -def extract_html_toc_excerpt(
 -    index_path: str | Path,
 -    *,
 -    max_lines: int = 16,
 -) -> str | None:
 -    """Extract the current HTML table-of-contents block for recovery guidance."""
+-
 -    index = Path(index_path).expanduser()
 -    if index.name != "index.html":
 -        return None
+-
 -    try:
 -        text = index.read_text()
 -    except OSError:
 -        return None
+-
 -    match = re.search(
 -        r"(<h2[^>]*>\s*Table of Contents\s*</h2>.*?</ul>)",
 -        text,
 -        re.IGNORECASE | re.DOTALL,
 -    )
 -    if not match:
 -        match = re.search(
 -            r"(<ul[^>]*class=\"[^\"]*chapter-list[^\"]*\"[^>]*>.*?</ul>)",
 -            text,
 -            re.IGNORECASE | re.DOTALL,
 -        )
 -    if not match:
 -        return None
+-
 -    snippet_lines = [line.rstrip() for line in match.group(1).splitlines() if line.strip()]
 -    if not snippet_lines:
 -        return None
 -    if len(snippet_lines) > max_lines:
 -        snippet_lines = snippet_lines[:max_lines] + ["..."]
 -    return "\n".join(snippet_lines)
+-
+-
 -def build_html_toc_replacement_block(index_path: str | Path) -> str | None:
 -    """Build one exact replacement TOC block from the verified sibling inventory."""
+-
 -    entries = _collect_html_inventory_entries(index_path)
 -    if not entries:
 -        return None
+-
 -    excerpt = extract_html_toc_excerpt(index_path, max_lines=64)
 -    excerpt_lines = excerpt.splitlines() if excerpt else []
+-
 -    heading_line = next(
 -        (line.rstrip() for line in excerpt_lines if "<h2" in line.lower()),
 -        "<h2>Table of Contents</h2>",
 -    )
 -    ul_line = next(
 -        (
 -            line.rstrip()
 -            for line in excerpt_lines
 -            if "<ul" in line.lower() and "chapter-list" in line.lower()
 -        ),
 -        '        <ul class="chapter-list">',
 -    )
 -    li_indent = next(
 -        (
 -            re.match(r"^\s*", line).group(0)
 -            for line in excerpt_lines
 -            if "<li><a " in line
 -        ),
 -        re.match(r"^\s*", ul_line).group(0) + "    ",
 -    )
 -    closing_line = next(
 -        (line.rstrip() for line in excerpt_lines if "</ul>" in line.lower()),
 -        f"{re.match(r'^\s*', ul_line).group(0)}</ul>",
 -    )
+-
 -    lines = [heading_line, ul_line]
 -    lines.extend(
 -        f'{li_indent}<li><a href="{href}">{title}</a></li>'
 -        for href, title in entries
 -    )
 -    lines.append(closing_line)
 -    return "\n".join(lines)
+-
+-
 -def build_html_toc_edit_call_template(index_path: str | Path) -> str | None:
 -    """Build one concrete `edit(...)` template for replacing the TOC block."""
+-
 -    index = Path(index_path).expanduser()
 -    excerpt = extract_html_toc_excerpt(index, max_lines=64)
 -    replacement = build_html_toc_replacement_block(index)
 -    if not excerpt or not replacement:
 -        return None
+-
 -    return "\n".join(
 -        [
 -            "edit(",
 -            f'  file_path="{index}",',
 -            '  old_string="""',
 -            excerpt,
 -            '""",',
 -            '  new_string="""',
 -            replacement,
 -            '"""',
 -            ")",
 -        ]
 -    )
+-
+-
 -@dataclass(frozen=True)
 -class HtmlTocValidationResult:
 -    """Semantic validation result for one chapter-list table of contents."""
+-
 -    valid: bool
 -    link_count: int
 -    missing: tuple[str, ...] = ()
 -    mismatched: tuple[str, ...] = ()
+-
+-
 -def validate_html_toc(index_path: str | Path) -> HtmlTocValidationResult | None:
 -    """Validate that one HTML index TOC points at real chapter files with matching titles."""
+-
 -    index = Path(index_path).expanduser()
 -    if index.name != "index.html":
 -        return None
+-
 -    try:
 -        text = index.read_text()
 -    except OSError:
 -        return None
+-
 -    section_match = re.search(r'<ul class="chapter-list">(.*?)</ul>', text, re.S)
 -    if section_match is None:
 -        return HtmlTocValidationResult(
 -            valid=False,
 -            link_count=0,
 -            missing=("Missing chapter-list table of contents",),
 -        )
+-
 -    links = re.findall(r'<a href="([^"]+)">([^<]+)</a>', section_match.group(1))
 -    if not links:
 -        return HtmlTocValidationResult(
 -            valid=False,
 -            link_count=0,
 -            missing=("No chapter links found in table of contents",),
 -        )
+-
 -    root = index.parent
 -    missing: list[str] = []
 -    mismatched: list[str] = []
 -    for href, label in links:
 -        target = (root / href).expanduser().resolve(strict=False)
 -        if not target.exists():
 -            missing.append(f"{href} -> missing")
 -            continue
 -        title = read_html_title(target)
 -        if title and label.strip() != title:
 -            mismatched.append(f"{href} -> {label.strip()} != {title}")
+-
 -    return HtmlTocValidationResult(
 -        valid=not missing and not mismatched,
 -        link_count=len(links),
 -        missing=tuple(missing),
 -        mismatched=tuple(mismatched),
 -    )
+-
+-
  class ActionTracker:
      """Tracks completed actions to prevent duplicates and detect loops."""
          """Record that one index currently satisfies the semantic chapter-link check."""
          normalized = self._normalize_path(index_path)
 -        if Path(normalized).name != "index.html":
 +        if not html_toc_rule.is_html_toc_index_path(normalized):
              return
          self._validated_html_tocs[normalized] = self._mutation_epoch
          normalized = self._normalize_path(index_path)
          path = Path(normalized)
 -        chapters_dir = path if path.name == "chapters" else path.parent / "chapters"
 +        chapters_dir = path if html_toc_rule.is_html_toc_chapters_dir(path) else path.parent / "chapters"
          self._verified_html_inventory_dirs.add(self._normalize_path(str(chapters_dir)))
      def check_tool_call(self, tool_name: str, arguments: dict) -> tuple[bool, str]:
              return
          normalized_path = self._normalize_path(file_path)
          path = Path(normalized_path)
 -        if path.suffix != ".html" or path.name == "index.html" or path.parent.name != "chapters":
 +        if not html_toc_rule.is_html_toc_chapter_file(path):
              return
          directory = str(path.parent)
                  return False, ""
              normalized_path = self._normalize_path(file_path)
              path = Path(normalized_path)
 -            if path.name != "index.html":
 +            if not html_toc_rule.is_html_toc_index_path(path):
                  return False, ""
              chapters_dir = str(path.parent / "chapters")
              chapter_count = self._chapter_evidence_count(chapters_dir)
                  return False, ""
              return (
                  True,
 -                "Already confirmed multiple chapter files in the sibling chapters "
 -                "directory; reuse the known file/title evidence and update index.html "
 -                "instead of rereading it",
 +                "Already confirmed multiple linked chapter files in "
 +                f"{html_toc_rule.describe_html_toc_chapters_dir(path)}; reuse that file/title "
 +                f"evidence and update {html_toc_rule.describe_html_toc_target(path)} instead of "
 +                "rereading it",
+             )
          if tool_name in {"glob", "grep"}:
                  return False, ""
              normalized_path = self._normalize_path(search_path)
              path = Path(normalized_path)
 -            if path.name != "chapters":
 +            if not html_toc_rule.is_html_toc_chapters_dir(path):
                  return False, ""
              chapter_count = self._chapter_evidence_count(str(path))
              if chapter_count < self.HTML_CHAPTER_EVIDENCE_THRESHOLD:
                  return False, ""
              return (
                  True,
 -                "Already confirmed multiple chapter files in this directory; reuse "
 -                "the known filename/title evidence and update the target index instead "
 -                "of rerunning the directory search",
 +                "Already confirmed multiple linked chapter files in "
 +                f"{html_toc_rule.describe_html_toc_chapters_dir(path)}; reuse that filename/title "
 +                f"evidence and update {html_toc_rule.describe_html_toc_target(path)} instead of "
 +                "rerunning the directory search",
+             )
          return False, ""
              if self._matches_validated_html_toc(path):
                  return (
                      True,
 -                    "The current index.html already passes the validated chapter-link "
 -                    "check; stop rereading index.html or chapters/ and finish the task "
 -                    "unless a specific href or title is still unresolved",
 +                    html_toc_rule.build_validated_html_toc_observation_reason(path),
+                 )
          return False, ""
              if self._matches_verified_html_inventory(path):
                  return (
                      True,
 -                    "The verified chapter inventory already lists the exact href/title "
 -                    "pairs for this directory; update index.html from that inventory "
 -                    "instead of rereading chapter files",
 +                    html_toc_rule.build_verified_html_inventory_observation_reason(path),
+                 )
          return False, ""
          content: str,
      ) -> ValidationResult:
          normalized = Path(file_path).expanduser()
 -        if normalized.name != "index.html" or "<a " not in content:
 +        if not html_toc_rule.is_html_toc_index_path(normalized) or "<a " not in content:
              return ValidationResult(valid=True)
          link_pairs = re.findall(r'<a\s+href="([^"]+)">([^<]+)</a>', content)
                      missing.append(href)
                  continue
 -            title = read_html_title(target)
 +            title = html_toc_rule.read_html_title(target)
              if title and label.strip() != title:
                  if href not in mismatched:
                      mismatched.append(href)
          if missing:
              suggestions = self._suggest_existing_html_targets(root, missing)
              preview_items = [
 -                format_html_inventory_entry(root, root / suggestion)
 +                html_toc_rule.format_html_inventory_entry(root, root / suggestion)
                  for suggestion in suggestions
+             ]
              if not preview_items:
                  valid=False,
                  reason="Edited TOC references chapter files that do not exist",
                  suggestion=(
 -                    "Use only existing chapter href/title pairs from beside index.html, for example: "
 +                    f"Use only existing chapter href/title pairs from beside "
 +                    f"{html_toc_rule.describe_html_toc_target(normalized)}, for example: "
                      f"{preview}"
                  ),
                  severity="error",
          if mismatched:
              exact_entries = [
 -                format_html_inventory_entry(root, (root / href).resolve(strict=False))
 +                html_toc_rule.format_html_inventory_entry(root, (root / href).resolve(strict=False))
                  for href in mismatched
                  if (root / href).resolve(strict=False).exists()
+             ]
                  valid=False,
                  reason="Edited TOC labels do not match the linked chapter titles",
                  suggestion=(
 -                    "Copy the exact href/title pair from the linked HTML file, for example: "
 +                    f"Copy the exact href/title pair from the linked HTML file for "
 +                    f"{html_toc_rule.describe_html_toc_target(normalized)}, for example: "
                      f"{preview}"
                  ),
                  severity="error",

src/loader/runtime/semantic_rules/__init__.pyadded

`@@ -0,0 +1,2 @@`
	1	+"""Internal semantic rule helpers for specialized task classes."""
	2	+

src/loader/runtime/semantic_rules/html_toc.pyadded

 +"""Internal semantic rule helpers for HTML table-of-contents repair tasks."""
++
 +from __future__ import annotations
++
 +import re
 +from dataclasses import dataclass
 +from pathlib import Path
++
 +HTML_TOC_REPAIR_PATTERNS = (
 +    r"\bfix(?:ing|ed)?\b",
 +    r"\bcorrect(?:ing|ed)?\b",
 +    r"\brepair(?:ing|ed)?\b",
 +    r"\bupdate(?:d|s|ing)?\b",
 +    r"\bsync(?:hronize|hronized|ing)?\b",
 +    r"\balign(?:ed|ing)?\b",
 +    r"\bmatch(?:es|ed|ing)?\b",
 +    r"\bwrong\b",
 +    r"\bincorrect\b",
 +    r"\binaccurate\b",
 +    r"\bbroken\b",
 +    r"\bmismatche?d\b",
 +    r"\bmissing\b",
 +)
 +HTML_TOC_SUBJECT_HINTS = (
 +    "table of contents",
 +    "toc",
 +    "href",
 +    "hrefs",
 +    "link text",
 +    "chapter link",
 +    "chapter links",
 +    "chapter title",
 +    "chapter titles",
 +)
 +HTML_TOC_TARGET_HINTS = (
 +    "index.html",
 +    "index page",
 +    "index table of contents",
 +    "chapters/",
 +    "/chapters",
 +    "chapters directory",
 +    "chapter directory",
 +)
++
++
 +def task_targets_html_toc(task_text: str | None) -> bool:
 +    """Return True when task text clearly targets one HTML TOC repair flow."""
++
 +    lowered = str(task_text or "").strip().lower()
 +    if not lowered:
 +        return False
 +    has_subject = any(hint in lowered for hint in HTML_TOC_SUBJECT_HINTS)
 +    has_target = any(hint in lowered for hint in HTML_TOC_TARGET_HINTS)
 +    has_repair_intent = any(
 +        re.search(pattern, lowered) is not None for pattern in HTML_TOC_REPAIR_PATTERNS
 +    )
 +    return has_subject and has_target and has_repair_intent
++
++
 +def is_html_toc_index_path(path_value: str | Path) -> bool:
 +    """Return True when one path is the TOC index target."""
++
 +    path = Path(path_value).expanduser()
 +    return path.name == "index.html" and path.suffix.lower() in {".html", ".htm"}
++
++
 +def is_html_toc_chapters_dir(path_value: str | Path) -> bool:
 +    """Return True when one path is the sibling chapters directory."""
++
 +    return Path(path_value).expanduser().name == "chapters"
++
++
 +def is_html_toc_chapter_file(path_value: str | Path) -> bool:
 +    """Return True when one path is a chapter HTML file beside the TOC index."""
++
 +    path = Path(path_value).expanduser()
 +    return (
 +        path.suffix.lower() in {".html", ".htm"}
 +        and path.name != "index.html"
 +        and path.parent.name == "chapters"
 +    )
++
++
 +def resolve_html_toc_index_path(path_value: str | Path) -> Path | None:
 +    """Resolve a related TOC path back to its index target."""
++
 +    candidate = Path(path_value).expanduser()
 +    if is_html_toc_index_path(candidate):
 +        return candidate
 +    if is_html_toc_chapters_dir(candidate):
 +        return candidate.parent / "index.html"
 +    if is_html_toc_chapter_file(candidate):
 +        return candidate.parent.parent / "index.html"
 +    return None
++
++
 +def describe_html_toc_target(path_value: str | Path) -> str:
 +    """Return one model-facing label for the active TOC target."""
++
 +    index = resolve_html_toc_index_path(path_value)
 +    if index is None:
 +        return "`the target HTML table-of-contents page`"
 +    return f"`{index}`"
++
++
 +def describe_html_toc_chapters_dir(path_value: str | Path) -> str:
 +    """Return one model-facing label for the sibling chapter directory."""
++
 +    index = resolve_html_toc_index_path(path_value)
 +    if index is None:
 +        return "`the sibling chapter directory`"
 +    return f"`{index.parent / 'chapters'}`"
++
++
 +def extract_html_title_from_text(payload: str) -> str | None:
 +    """Extract one human-readable title from raw HTML text."""
++
 +    for pattern in (r"<h1[^>]*>(.*?)</h1>", r"<title[^>]*>(.*?)</title>"):
 +        match = re.search(pattern, payload, re.IGNORECASE | re.DOTALL)
 +        if not match:
 +            continue
 +        title = re.sub(r"<[^>]+>", " ", match.group(1))
 +        normalized = " ".join(title.split()).strip()
 +        if normalized:
 +            return normalized
 +    return None
++
++
 +def read_html_title(path: Path) -> str:
 +    """Read one HTML file title for inventory and validation helpers."""
++
 +    try:
 +        return extract_html_title_from_text(path.read_text()) or ""
 +    except OSError:
 +        return ""
++
++
 +def format_html_inventory_entry(root: Path, candidate: Path) -> str:
 +    """Format one exact href/title pair for model-facing guidance."""
++
 +    normalized_root = root.expanduser().resolve(strict=False)
 +    normalized_candidate = candidate.expanduser().resolve(strict=False)
 +    try:
 +        href = str(normalized_candidate.relative_to(normalized_root))
 +    except ValueError:
 +        href = normalized_candidate.name
 +    title = read_html_title(candidate)
 +    if title:
 +        return f"{href} = {title}"
 +    return href
++
++
 +def build_validated_html_toc_observation_reason(path_value: str | Path) -> str:
 +    """Build a duplicate-observation reason for one already validated TOC target."""
++
 +    target = describe_html_toc_target(path_value)
 +    chapters_dir = describe_html_toc_chapters_dir(path_value)
 +    return (
 +        f"The HTML table-of-contents target {target} already passed semantic link "
 +        f"validation; reuse that result instead of rereading {target} or its sibling "
 +        f"chapter directory {chapters_dir} unless one specific href or label is still "
 +        "unresolved"
 +    )
++
++
 +def build_verified_html_inventory_observation_reason(path_value: str | Path) -> str:
 +    """Build a duplicate-observation reason for one verified chapter inventory."""
++
 +    target = describe_html_toc_target(path_value)
 +    chapters_dir = describe_html_toc_chapters_dir(path_value)
 +    return (
 +        f"The verified sibling chapter inventory for {chapters_dir} already contains the "
 +        f"exact href/title pairs needed for {target}; reuse that inventory instead of "
 +        "rereading chapter files"
 +    )
++
++
 +def _collect_html_inventory_entries(index_path: str | Path) -> list[tuple[str, str]]:
 +    """Return exact href/title pairs for sibling HTML chapters."""
++
 +    index = Path(index_path).expanduser()
 +    if not is_html_toc_index_path(index):
 +        return []
++
 +    chapters_dir = index.parent / "chapters"
 +    if not chapters_dir.is_dir():
 +        return []
++
 +    entries: list[tuple[str, str]] = []
 +    for candidate in sorted(chapters_dir.glob("*.html")):
 +        if not candidate.is_file():
 +            continue
 +        title = read_html_title(candidate)
 +        if not title:
 +            continue
 +        href = format_html_inventory_entry(index.parent, candidate).split(" = ", 1)[0]
 +        entries.append((href, title))
 +    return entries
++
++
 +def summarize_html_inventory(
 +    index_path: str | Path,
 +    *,
 +    limit: int | None = 12,
 +) -> str | None:
 +    """Summarize one sibling HTML inventory for an index page."""
++
 +    index = Path(index_path).expanduser()
 +    if not is_html_toc_index_path(index):
 +        return None
++
 +    entries = [f"{href} = {title}" for href, title in _collect_html_inventory_entries(index)]
 +    if not entries:
 +        return None
++
 +    if limit is not None and len(entries) > limit:
 +        return "; ".join(entries[:limit]) + "; ..."
 +    return "; ".join(entries)
++
++
 +def extract_html_toc_excerpt(
 +    index_path: str | Path,
 +    *,
 +    max_lines: int = 16,
 +) -> str | None:
 +    """Extract the current TOC block for recovery guidance."""
++
 +    index = Path(index_path).expanduser()
 +    if not is_html_toc_index_path(index):
 +        return None
++
 +    try:
 +        text = index.read_text()
 +    except OSError:
 +        return None
++
 +    match = re.search(
 +        r"(<h2[^>]*>\s*Table of Contents\s*</h2>.*?</ul>)",
 +        text,
 +        re.IGNORECASE | re.DOTALL,
 +    )
 +    if not match:
 +        match = re.search(
 +            r"(<ul[^>]*class=\"[^\"]*chapter-list[^\"]*\"[^>]*>.*?</ul>)",
 +            text,
 +            re.IGNORECASE | re.DOTALL,
 +        )
 +    if not match:
 +        return None
++
 +    snippet_lines = [line.rstrip() for line in match.group(1).splitlines() if line.strip()]
 +    if not snippet_lines:
 +        return None
 +    if len(snippet_lines) > max_lines:
 +        snippet_lines = snippet_lines[:max_lines] + ["..."]
 +    return "\n".join(snippet_lines)
++
++
 +def build_html_toc_replacement_block(index_path: str | Path) -> str | None:
 +    """Build one exact replacement TOC block from the verified sibling inventory."""
++
 +    entries = _collect_html_inventory_entries(index_path)
 +    if not entries:
 +        return None
++
 +    excerpt = extract_html_toc_excerpt(index_path, max_lines=64)
 +    excerpt_lines = excerpt.splitlines() if excerpt else []
++
 +    heading_line = next(
 +        (line.rstrip() for line in excerpt_lines if "<h2" in line.lower()),
 +        "<h2>Table of Contents</h2>",
 +    )
 +    ul_line = next(
 +        (
 +            line.rstrip()
 +            for line in excerpt_lines
 +            if "<ul" in line.lower() and "chapter-list" in line.lower()
 +        ),
 +        '        <ul class="chapter-list">',
 +    )
 +    li_indent = next(
 +        (
 +            re.match(r"^\s*", line).group(0)
 +            for line in excerpt_lines
 +            if "<li><a " in line
 +        ),
 +        re.match(r"^\s*", ul_line).group(0) + "    ",
 +    )
 +    ul_indent = re.match(r"^\s*", ul_line).group(0)
 +    closing_line = next(
 +        (line.rstrip() for line in excerpt_lines if "</ul>" in line.lower()),
 +        f"{ul_indent}</ul>",
 +    )
++
 +    lines = [heading_line, ul_line]
 +    lines.extend(
 +        f'{li_indent}<li><a href="{href}">{title}</a></li>'
 +        for href, title in entries
 +    )
 +    lines.append(closing_line)
 +    return "\n".join(lines)
++
++
 +def build_html_toc_edit_call_template(index_path: str | Path) -> str | None:
 +    """Build one concrete edit template for replacing the TOC block."""
++
 +    index = Path(index_path).expanduser()
 +    excerpt = extract_html_toc_excerpt(index, max_lines=64)
 +    replacement = build_html_toc_replacement_block(index)
 +    if not excerpt or not replacement:
 +        return None
++
 +    return "\n".join(
 +        [
 +            "edit(",
 +            f'  file_path="{index}",',
 +            '  old_string="""',
 +            excerpt,
 +            '""",',
 +            '  new_string="""',
 +            replacement,
 +            '"""',
 +            ")",
 +        ]
 +    )
++
++
 +@dataclass(frozen=True)
 +class HtmlTocValidationResult:
 +    """Semantic validation result for one chapter-list table of contents."""
++
 +    valid: bool
 +    link_count: int
 +    missing: tuple[str, ...] = ()
 +    mismatched: tuple[str, ...] = ()
++
++
 +def validate_html_toc(index_path: str | Path) -> HtmlTocValidationResult | None:
 +    """Validate that one HTML TOC points at real chapter files with matching titles."""
++
 +    index = Path(index_path).expanduser()
 +    if not is_html_toc_index_path(index):
 +        return None
++
 +    try:
 +        text = index.read_text()
 +    except OSError:
 +        return None
++
 +    section_match = re.search(r'<ul class="chapter-list">(.*?)</ul>', text, re.S)
 +    if section_match is None:
 +        return HtmlTocValidationResult(
 +            valid=False,
 +            link_count=0,
 +            missing=("Missing chapter-list table of contents",),
 +        )
++
 +    links = re.findall(r'<a href="([^"]+)">([^<]+)</a>', section_match.group(1))
 +    if not links:
 +        return HtmlTocValidationResult(
 +            valid=False,
 +            link_count=0,
 +            missing=("No chapter links found in table of contents",),
 +        )
++
 +    root = index.parent
 +    missing: list[str] = []
 +    mismatched: list[str] = []
 +    for href, label in links:
 +        target = (root / href).expanduser().resolve(strict=False)
 +        if not target.exists():
 +            missing.append(f"{href} -> missing")
 +            continue
 +        title = read_html_title(target)
 +        if title and label.strip() != title:
 +            mismatched.append(f"{href} -> {label.strip()} != {title}")
++
 +    return HtmlTocValidationResult(
 +        valid=not missing and not mismatched,
 +        link_count=len(links),
 +        missing=tuple(missing),
 +        mismatched=tuple(mismatched),
 +    )
++
++
 +def build_html_toc_verification_command(index_path: str | Path) -> str | None:
 +    """Build the semantic verification command for one HTML TOC target."""
++
 +    index = Path(index_path).expanduser()
 +    if not is_html_toc_index_path(index):
 +        return None
 +    if not (index.parent / "chapters").is_dir():
 +        return None
++
 +    path_literal = repr(str(index))
 +    return "\n".join(
 +        [
 +            "python3 - <<'PY'",
 +            "from pathlib import Path",
 +            "import re",
 +            "import sys",
 +            "",
 +            f"index = Path({path_literal}).expanduser()",
 +            "root = index.parent",
 +            "text = index.read_text()",
 +            "section_match = re.search(r'<ul class=\"chapter-list\">(.*?)</ul>', text, re.S)",
 +            "if section_match is None:",
 +            "    print('Missing chapter-list table of contents', file=sys.stderr)",
 +            "    raise SystemExit(1)",
 +            "links = re.findall(r'<a href=\"([^\"]+)\">([^<]+)</a>', section_match.group(1))",
 +            "if not links:",
 +            "    print('No chapter links found in table of contents', file=sys.stderr)",
 +            "    raise SystemExit(1)",
 +            "",
 +            "missing = []",
 +            "mismatched = []",
 +            "for href, label in links:",
 +            "    target = (root / href).resolve()",
 +            "    if not target.exists():",
 +            "        missing.append(f'{href} -> missing')",
 +            "        continue",
 +            "    body = target.read_text()",
 +            "    match = re.search(r'<h1>(.*?)</h1>', body, re.S)",
 +            "    title = match.group(1).strip() if match else ''",
 +            "    if title and label.strip() != title:",
 +            "        mismatched.append(f'{href} -> {label.strip()} != {title}')",
 +            "",
 +            "if missing or mismatched:",
 +            "    if missing:",
 +            "        print('Missing links:', file=sys.stderr)",
 +            "        for item in missing:",
 +            "            print(item, file=sys.stderr)",
 +            "    if mismatched:",
 +            "        print('Title mismatches:', file=sys.stderr)",
 +            "        for item in mismatched:",
 +            "            print(item, file=sys.stderr)",
 +            "    raise SystemExit(1)",
 +            "",
 +            "print(f'validated {len(links)} toc links in {index.name}')",
 +            "PY",
 +        ]
 +    )
++
++
 +def parse_html_toc_verification_failures(text: str) -> tuple[list[str], list[str]]:
 +    """Parse missing hrefs and mismatched labels from verifier output."""
++
 +    missing: list[str] = []
 +    mismatches: list[str] = []
 +    mode: str | None = None
++
 +    for raw_line in text.splitlines():
 +        line = raw_line.strip()
 +        if not line:
 +            continue
 +        lowered = line.lower()
 +        if lowered == "missing links:":
 +            mode = "missing"
 +            continue
 +        if lowered == "title mismatches:":
 +            mode = "mismatch"
 +            continue
 +        if mode == "missing" and "->" in line:
 +            href = line.split("->", 1)[0].strip()
 +            if href and href not in missing:
 +                missing.append(href)
 +            continue
 +        if mode == "mismatch" and "!=" in line and line not in mismatches:
 +            mismatches.append(line)
++
 +    return missing, mismatches
++
++
 +def summarize_html_toc_verification_gap(payload: str, *, max_items: int = 2) -> str | None:
 +    """Summarize the latest semantic verifier gap from shell output."""
++
 +    missing, mismatches = parse_html_toc_verification_failures(payload)
++
 +    parts: list[str] = []
 +    if missing:
 +        preview = ", ".join(missing[:max_items])
 +        if len(missing) > max_items:
 +            preview += ", ..."
 +        parts.append(f"missing TOC links {preview}")
 +    if mismatches:
 +        preview = ", ".join(mismatches[:max_items])
 +        if len(mismatches) > max_items:
 +            preview += ", ..."
 +        parts.append(f"title mismatches {preview}")
 +    return "; ".join(parts) if parts else None
++
++
 +def summarize_html_file_discovery(payload: str) -> str | None:
 +    """Summarize a set of discovered HTML filenames from tool output."""
++
 +    filenames = re.findall(r"([A-Za-z0-9_.-]+\.html)", payload)
 +    unique_names: list[str] = []
 +    for name in filenames:
 +        if name not in unique_names:
 +            unique_names.append(name)
 +    if len(unique_names) < 3:
 +        return None
 +    preview = ", ".join(unique_names[:6])
 +    if len(unique_names) > 6:
 +        preview += ", ..."
 +    return f"Existing files include {preview}"

src/loader/runtime/tool_batch_recovery.pymodified

  from __future__ import annotations
 +import re
  from collections.abc import Awaitable, Callable
  from difflib import SequenceMatcher
  from pathlib import Path
 -import re
 -from ..llm.base import Message, ToolCall
 -from .compaction import infer_preferred_next_step, summarize_confirmed_facts
 +from ..llm.base import Message, Role, ToolCall
 +from .compaction import (
 +    extract_key_files,
 +    infer_preferred_next_step,
 +    summarize_confirmed_facts,
 +)
  from .context import RuntimeContext
  from .events import AgentEvent
  from .executor import ToolExecutionOutcome
  from .recovery import RecoveryContext, format_failure_message, format_recovery_prompt
 -from .safeguard_services import (
 -    build_html_toc_edit_call_template,
 -    build_html_toc_replacement_block,
 -    extract_html_toc_excerpt,
 -    read_html_title,
 -    summarize_html_inventory,
 -)
 +from .semantic_rules import html_toc as html_toc_rule
  EventSink = Callable[[AgentEvent], Awaitable[None]]
          session = self.context.session
          current_task = getattr(session, "current_task", None)
 +        focus_path = self._preferred_focus_path(
 +            tool_call=tool_call,
 +            current_task=current_task,
 +        )
          confirmed_facts = summarize_confirmed_facts(session.messages)
          preferred_next_step = infer_preferred_next_step(
              session.messages,
              current_task=current_task,
 +            focus_path=focus_path or None,
+         )
          actionable_known_state = bool(confirmed_facts and preferred_next_step)
          lines = [prompt]
              lines.extend(["", "## CURRENT TARGET EXCERPT", *target_excerpt_lines])
          return "\n".join(lines)
 +    def _preferred_focus_path(
 +        self,
 +        *,
 +        tool_call: ToolCall,
 +        current_task: str | None,
 +    ) -> str:
 +        raw_path = str(
 +            tool_call.arguments.get("file_path")
 +            or tool_call.arguments.get("path")
 +            or ""
 +        ).strip()
 +        if not raw_path:
 +            return ""
 +        if tool_call.name in {"write", "edit", "patch"} or not current_task:
 +            return raw_path
++
 +        primary_target = self._primary_task_target_path(current_task)
 +        if not primary_target:
 +            return raw_path
++
 +        candidate = self._canonicalize_path(raw_path)
 +        target = self._canonicalize_path(primary_target)
 +        if not candidate or not target or candidate == target:
 +            return raw_path
++
 +        candidate_path = Path(candidate)
 +        target_path = Path(target)
 +        if (
 +            tool_call.name == "read"
 +            and candidate_path.suffix == ".html"
 +            and candidate_path.parent == target_path.parent / "chapters"
 +        ):
 +            return target
++
 +        return raw_path
++
 +    def _primary_task_target_path(self, current_task: str) -> str | None:
 +        paths = extract_key_files(
 +            [Message(role=Role.USER, content=current_task)],
 +            limit=6,
 +        )
 +        for path in paths:
 +            normalized = self._canonicalize_path(path)
 +            if not normalized:
 +                continue
 +            if normalized.endswith(".html") and "/chapters/" not in normalized:
 +                return normalized
 +        for path in paths:
 +            normalized = self._canonicalize_path(path)
 +            if normalized:
 +                return normalized
 +        return None
++
      def _file_not_found_candidate_lines(
          self,
          tool_call: ToolCall,
          path = Path(candidate)
          label = f"`{path.name}`"
          if path.suffix == ".html":
 -            title = read_html_title(path)
 +            title = html_toc_rule.read_html_title(path)
              if title:
                  return f"{label} = {title}"
          return label
          ).strip()
          if not file_path:
              return []
 +        current_task = getattr(self.context.session, "current_task", None)
 +        if not html_toc_rule.task_targets_html_toc(current_task):
 +            return []
 -        inventory = summarize_html_inventory(file_path, limit=12)
 -        excerpt = extract_html_toc_excerpt(file_path)
 +        inventory = html_toc_rule.summarize_html_inventory(file_path, limit=12)
 +        excerpt = html_toc_rule.extract_html_toc_excerpt(file_path)
          if not inventory and not excerpt:
              return []
          if excerpt:
              lines.append("- Current TOC block:")
              lines.extend(f"  {line}" for line in excerpt.splitlines())
 -        replacement = build_html_toc_replacement_block(file_path)
 +        replacement = html_toc_rule.build_html_toc_replacement_block(file_path)
          if replacement:
              lines.append("- Suggested replacement block:")
              lines.extend(f"  {line}" for line in replacement.splitlines())
              lines.append("  old_string: use the Current TOC block above exactly")
              lines.append("  new_string: use the Suggested replacement block above exactly")
              lines.append("  Do not rewrite the whole file.")
 -        edit_template = build_html_toc_edit_call_template(file_path)
 +        edit_template = html_toc_rule.build_html_toc_edit_call_template(file_path)
          if edit_template:
              lines.append("- Suggested edit call:")
              lines.extend(f"  {line}" for line in edit_template.splitlines())

src/loader/runtime/tool_batches.pymodified

  from typing import Any
  from ..llm.base import Role, ToolCall
 +from .compaction import infer_preferred_next_step, summarize_confirmed_facts
  from .context import RuntimeContext
  from .dod import (
      DefinitionOfDone,
  from .executor import ToolExecutionState, ToolExecutor
  from .logging import get_runtime_logger
  from .policy_timeline import append_verification_timeline_entry
 +from .safeguard_services import extract_shell_text_rewrite_target
 +from .semantic_rules import html_toc as html_toc_rule
  from .tool_batch_checks import ToolBatchConfidenceGate, ToolBatchVerificationGate
  from .tool_batch_recovery import ToolBatchRecoveryController
  from .verification_observations import (
      VerificationObservation,
      VerificationObservationStatus,
+ )
 -from .workflow import sync_todos_to_definition_of_done
 -from .workflow import advance_todos_from_tool_call
 -from .compaction import infer_preferred_next_step, summarize_confirmed_facts
 -from .safeguard_services import (
 -    build_html_toc_edit_call_template,
 -    build_html_toc_replacement_block,
 -    extract_html_toc_excerpt,
 -    extract_shell_text_rewrite_target,
 -    summarize_html_inventory,
 -    validate_html_toc,
 -)
 +from .workflow import advance_todos_from_tool_call, sync_todos_to_definition_of_done
  EventSink = Callable[[AgentEvent], Awaitable[None]]
  ConfirmationHandler = (
  UserQuestionHandler = Callable[[str, list[str] | None], Awaitable[str]] | None
  _VERIFY_ITEM = "Collect verification evidence"
 +_TODO_NUDGE_EXCLUDED_ITEMS = {
 +    "Complete the requested work",
 +    _VERIFY_ITEM,
 +}
  @dataclass
              self.context.session.append(outcome.message)
              summary.tool_result_messages.append(outcome.message)
              if outcome.state == ToolExecutionState.DUPLICATE:
 -                self._queue_duplicate_observation_nudge(tool_call)
 +                self._queue_duplicate_observation_nudge(tool_call, dod=dod)
              elif outcome.state == ToolExecutionState.BLOCKED:
                  self._queue_blocked_shell_rewrite_nudge(tool_call)
                  self._queue_blocked_html_edit_nudge(tool_call, outcome.event_content)
          return result
 -    def _queue_duplicate_observation_nudge(self, tool_call: ToolCall) -> None:
 +    def _queue_duplicate_observation_nudge(
 +        self,
 +        tool_call: ToolCall,
 +        *,
 +        dod: DefinitionOfDone,
 +    ) -> None:
          """Queue a concrete next-step nudge after duplicate observational actions."""
          if tool_call.name not in {"read", "glob", "grep", "bash"}:
              return
          current_task = getattr(self.context.session, "current_task", None)
 +        next_pending = next(
 +            (
 +                item
 +                for item in dod.pending_items
 +                if item not in _TODO_NUDGE_EXCLUDED_ITEMS
 +            ),
 +            None,
 +        )
          confirmed_facts = summarize_confirmed_facts(
              self.context.session.messages,
              max_items=2,
+         )
 +        if next_pending and not html_toc_rule.task_targets_html_toc(current_task):
 +            if confirmed_facts:
 +                self.context.queue_steering_message(
 +                    "Reuse the earlier observation instead of repeating it. "
 +                    f"Confirmed facts: {confirmed_facts}. "
 +                    f"Continue with the next pending item: `{next_pending}`. "
 +                    "Only gather more evidence if a specific fact required for that step is still unknown."
 +                )
 +            else:
 +                self.context.queue_steering_message(
 +                    "Reuse the earlier observation instead of repeating it. "
 +                    f"Continue with the next pending item: `{next_pending}`. "
 +                    "Only gather more evidence if a specific fact required for that step is still unknown."
 +                )
 +            return
++
          preferred_next_step = infer_preferred_next_step(
              self.context.session.messages,
              current_task=current_task,
          if tool_call.name not in {"edit", "patch"}:
              return
 +        if not self._targets_html_toc_task():
 +            return
          target_path = str(tool_call.arguments.get("file_path", "")).strip()
 -        if not target_path.endswith("index.html"):
 +        if not html_toc_rule.is_html_toc_index_path(target_path):
              return
 -        validation = validate_html_toc(target_path)
 +        validation = html_toc_rule.validate_html_toc(target_path)
          if (
              "old_string and new_string are identical" in event_content
              and validation is not None
              note_validated = getattr(action_tracker, "note_validated_html_toc", None)
              if callable(note_validated):
                  note_validated(target_path)
 +            target_label = html_toc_rule.describe_html_toc_target(target_path)
              self.context.queue_steering_message(
 -                "The current `index.html` already matches the validated replacement block. "
 -                f"Semantic verification preview: validated {validation.link_count} toc links in "
 -                f"`{Path(target_path).name}`. "
 +                f"The HTML table-of-contents target {target_label} already matches the "
 +                "validated replacement block. "
 +                f"Semantic verification preview: validated {validation.link_count} linked "
 +                "entries. "
                  "Do not call `edit`, `patch`, or reread the same TOC again. Briefly state "
 -                "that the table of contents is already updated so Loader can continue the "
 +                f"that {target_label} is already updated so Loader can continue the "
                  "verification gate or finish the task."
+             )
              return
          confirmed_facts = summarize_confirmed_facts(
              self.context.session.messages,
              max_items=2,
 +            focus_path=target_path,
+         )
          preferred_next_step = infer_preferred_next_step(
              self.context.session.messages,
              current_task=current_task,
 +            focus_path=target_path,
+         )
 -        verified_inventory = summarize_html_inventory(target_path, limit=12)
 -        current_excerpt = extract_html_toc_excerpt(target_path)
 -        suggested_replacement = build_html_toc_replacement_block(target_path)
 -        suggested_call = build_html_toc_edit_call_template(target_path)
 +        verified_inventory = html_toc_rule.summarize_html_inventory(target_path, limit=12)
 +        current_excerpt = html_toc_rule.extract_html_toc_excerpt(target_path)
 +        suggested_replacement = html_toc_rule.build_html_toc_replacement_block(target_path)
 +        suggested_call = html_toc_rule.build_html_toc_edit_call_template(target_path)
 +        target_label = html_toc_rule.describe_html_toc_target(target_path)
          excerpt_suffix = (
              f"\nCurrent TOC block:\n{current_excerpt}"
              if current_excerpt
          if preferred_next_step and confirmed_facts and verified_inventory:
              self.context.queue_steering_message(
 -                "Use the current target contents plus the verified sibling inventory instead of guessing. "
 +                f"Use the current TOC target contents plus the verified sibling inventory for "
 +                f"{target_label} instead of guessing. "
                  f"Confirmed facts: {confirmed_facts}. "
                  f"Known chapter inventory: {verified_inventory}. "
                  f"{preferred_next_step} "
 -                "Apply those exact href/title pairs in `index.html`. "
 +                f"Apply those exact href/title pairs in {target_label}. "
                  "Do not rewrite the whole document. For `edit`, set `old_string` to the "
                  "current TOC block above exactly and set `new_string` to the suggested "
                  "replacement block below exactly."
          if verified_inventory:
              self.context.queue_steering_message(
 -                "Use the current target contents plus the verified sibling inventory instead of guessing. "
 +                f"Use the current TOC target contents plus the verified sibling inventory for "
 +                f"{target_label} instead of guessing. "
                  f"Known chapter inventory: {verified_inventory}. "
 -                "Apply those exact href/title pairs in `index.html`. "
 +                f"Apply those exact href/title pairs in {target_label}. "
                  "Do not rewrite the whole document. For `edit`, set `old_string` to the "
                  "current TOC block above exactly and set `new_string` to the suggested "
                  "replacement block below exactly."
              return
          self.context.queue_steering_message(
 -            "Use the current target contents when retrying this `index.html` edit instead of guessing. "
 +            f"Use the current TOC target contents when retrying the edit for {target_label} "
 +            "instead of guessing. "
              f"{excerpt_suffix}".strip()
+         )
          if not self._targets_html_toc_task():
              return
 -        verified_inventory = summarize_html_inventory(index_path, limit=12)
 +        verified_inventory = html_toc_rule.summarize_html_inventory(index_path, limit=12)
          if not verified_inventory:
              return
          self._inventory_hint_targets.add(index_path)
 +        target_label = html_toc_rule.describe_html_toc_target(index_path)
 +        chapters_label = html_toc_rule.describe_html_toc_chapters_dir(index_path)
          self.context.queue_steering_message(
 -            "You already have the verified sibling inventory needed for this edit. "
 +            f"You already have the verified sibling inventory needed for {target_label}. "
              f"Known chapter inventory: {verified_inventory}. "
 -            f"Update `{index_path}` using those exact href/title pairs instead of rereading files "
 -            "unless one specific title is still unknown."
 +            f"Update {target_label} using those exact href/title pairs instead of rereading "
 +            f"files in {chapters_label} unless one specific title is still unknown."
+         )
      def _annotate_verified_html_inventory(self, tool_call: ToolCall, outcome) -> None:
              return
          index_path = str(Path(chapters_path).expanduser().parent / "index.html")
 -        verified_inventory = summarize_html_inventory(index_path, limit=12)
 +        verified_inventory = html_toc_rule.summarize_html_inventory(index_path, limit=12)
          if not verified_inventory:
              return
          if callable(note_inventory):
              note_inventory(index_path)
 -        note = (
 -            "Verified chapter inventory: "
 -            f"{verified_inventory}"
 -        )
 +        note = f"Verified chapter inventory: {verified_inventory}"
          merged_event = outcome.event_content
          if note not in merged_event:
              merged_event = f"{note}\n{merged_event}".strip()
      def _annotate_validated_html_toc_completion(self, tool_call: ToolCall, outcome) -> None:
          """Attach semantic TOC validation evidence to a successful mutating result."""
 +        if not self._targets_html_toc_task():
 +            return
          target_path = self._validated_html_toc_target(tool_call)
          if target_path is None:
              return
 -        if tool_call.name == "read" and not self._targets_html_toc_task():
 -            return
 -        validation = validate_html_toc(target_path)
 +        validation = html_toc_rule.validate_html_toc(target_path)
          if validation is None or not validation.valid:
              return
      def _queue_validated_html_toc_completion_nudge(self, tool_call: ToolCall) -> None:
          """Push the next model turn toward finishing once the TOC already validates."""
 +        if not self._targets_html_toc_task():
 +            return
          target_path = self._validated_html_toc_target(tool_call)
          if target_path is None:
              return
 -        if tool_call.name == "read" and not self._targets_html_toc_task():
 -            return
 -        validation = validate_html_toc(target_path)
 +        validation = html_toc_rule.validate_html_toc(target_path)
          if validation is None or not validation.valid:
              return
          if tool_call.name == "read":
 +            target_label = html_toc_rule.describe_html_toc_target(target_path)
 +            chapters_label = html_toc_rule.describe_html_toc_chapters_dir(target_path)
              self.context.queue_steering_message(
 -                "The current `index.html` already satisfies the verified chapter-link constraints. "
 -                f"Semantic verification preview: validated {validation.link_count} toc links in "
 -                f"`{Path(target_path).name}`. "
 +                f"The HTML table-of-contents target {target_label} already satisfies the "
 +                "verified link/title constraints. "
 +                f"Semantic verification preview: validated {validation.link_count} linked "
 +                "entries. "
                  "No TOC edit is required unless you can point to one specific incorrect href or "
 -                "title. Do not reread `index.html` or files in `chapters/` again. Briefly state "
 -                "that the table of contents is already correct so Loader can finish the task."
 +                f"title. Do not reread {target_label} or files in {chapters_label} again. "
 +                "Briefly state that the table of contents is already correct so Loader can "
 +                "finish the task."
+             )
              return
 +        target_label = html_toc_rule.describe_html_toc_target(target_path)
 +        chapters_label = html_toc_rule.describe_html_toc_chapters_dir(target_path)
          self.context.queue_steering_message(
 -            "The current `index.html` already satisfies the verified chapter-link constraints. "
 -            f"Semantic verification preview: validated {validation.link_count} toc links in "
 -            f"`{Path(target_path).name}`. "
 -            "Do not reread `index.html` or files in `chapters/` unless a specific href or "
 -            "title is still unresolved. Briefly state that the table of contents has been "
 -            "updated so Loader can run the verification gate."
 +            f"The HTML table-of-contents target {target_label} already satisfies the "
 +            "verified link/title constraints. "
 +            f"Semantic verification preview: validated {validation.link_count} linked "
 +            "entries. "
 +            f"Do not reread {target_label} or files in {chapters_label} unless a specific "
 +            "href or title is still unresolved. Briefly state that the table of contents has "
 +            "been updated so Loader can run the verification gate."
+         )
      @staticmethod
          if not target_path:
              return None
 -        if not target_path.endswith("index.html"):
 +        if not html_toc_rule.is_html_toc_index_path(target_path):
              return None
          return str(Path(target_path).expanduser())
                  if content:
                      current_task = content
                      break
 -        return any(
 -            hint in current_task
 -            for hint in ("href", "link", "links", "table of contents", "chapter", "index.html")
 -        )
 +        return html_toc_rule.task_targets_html_toc(current_task)
      async def _record_successful_execution(
          self,
              if isinstance(new_todos, list):
                  sync_todos_to_definition_of_done(dod, new_todos)
          else:
 -            advance_todos_from_tool_call(dod, tool_call)
 +            pending_before = list(dod.pending_items)
 +            if advance_todos_from_tool_call(dod, tool_call):
 +                self._queue_next_pending_todo_nudge(
 +                    tool_call=tool_call,
 +                    pending_before=pending_before,
 +                    dod=dod,
 +                )
          self.dod_store.save(dod)
          recovery_context = self.context.recovery_context
          if recovery_context is not None:
                  self.context.recovery_context = None
          return None
 +    def _queue_next_pending_todo_nudge(
 +        self,
 +        *,
 +        tool_call: ToolCall,
 +        pending_before: list[str],
 +        dod: DefinitionOfDone,
 +    ) -> None:
 +        if is_state_mutating_tool_call(tool_call):
 +            return
 +        if tool_call.name not in {"read", "glob", "grep", "bash"}:
 +            return
 +        if tool_call.name == "bash":
 +            command = str(tool_call.arguments.get("command", "")).lower()
 +            if not any(
 +                token in command
 +                for token in (
 +                    "ls ",
 +                    " ls",
 +                    "find ",
 +                    "grep ",
 +                    "rg ",
 +                    "cat ",
 +                    "sed ",
 +                    "head ",
 +                    "tail ",
 +                )
 +            ):
 +                return
++
 +        completed_label = next(
 +            (
 +                item
 +                for item in pending_before
 +                if item not in dod.pending_items
 +                and item not in _TODO_NUDGE_EXCLUDED_ITEMS
 +            ),
 +            None,
 +        )
 +        next_pending = next(
 +            (
 +                item
 +                for item in dod.pending_items
 +                if item not in _TODO_NUDGE_EXCLUDED_ITEMS
 +            ),
 +            None,
 +        )
 +        if not completed_label or not next_pending or next_pending == completed_label:
 +            return
++
 +        self.context.queue_steering_message(
 +            f"Confirmed progress: `{completed_label}` is now satisfied by the successful "
 +            f"`{tool_call.name}` result. Continue with the next pending item: "
 +            f"`{next_pending}` instead of rereading the same evidence."
 +        )
++
  def _mark_verification_stale(
      *,

src/loader/runtime/workflow.pymodified

      "extract_verification_commands_from_markdown",
      "load_brief",
      "load_planning_artifacts",
 +    "merge_refreshed_todos_with_existing_scope",
 +    "preserve_task_grounded_acceptance_criteria",
      "sync_todos_to_definition_of_done",
+ ]
      "determine",
+ )
  _MUTATION_STEP_HINTS = (
 +    "create",
      "update",
      "edit",
      "write",
      "confirm",
      "check",
+ )
 +_TASK_COVERAGE_STOP_WORDS = {
 +    "the",
 +    "and",
 +    "with",
 +    "from",
 +    "that",
 +    "this",
 +    "into",
 +    "your",
 +    "have",
 +    "make",
 +    "will",
 +    "then",
 +    "each",
 +    "file",
 +    "files",
 +    "guide",
 +}
  _SHELL_COMMAND_START = re.compile(
      r"(?<![\w/.-])("
      r"ls|grep|pytest|uv|python3?|html5validator|cargo|npm|node|mypy|ruff|find|git|cat|sed|head|tail|test|diff|cmp|bash|sh|make"
              "It does not run a planner/critic consensus loop.",
+         ]
 +    def with_acceptance_criteria(self, acceptance_criteria: list[str]) -> PlanningArtifacts:
 +        """Return one copy with a rewritten acceptance-criteria section."""
++
 +        merged = [item.strip() for item in acceptance_criteria if item.strip()]
 +        if not merged or merged == self.acceptance_criteria:
 +            return self
++
 +        return PlanningArtifacts(
 +            implementation_markdown=self.implementation_markdown,
 +            verification_markdown=_replace_markdown_section_items(
 +                self.verification_markdown,
 +                "Acceptance Criteria",
 +                merged,
 +            ),
 +            verification_commands=list(self.verification_commands),
 +            acceptance_criteria=list(merged),
 +            implementation_steps=list(self.implementation_steps),
 +        )
++
  class WorkflowArtifactStore:
      """Persist briefs and plans under `.loader/`."""
      dod.completed_items = list(dict.fromkeys(completed + special_completed))
 +def preserve_task_grounded_acceptance_criteria(
 +    task_statement: str,
 +    *,
 +    existing_acceptance_criteria: list[str],
 +    refreshed_acceptance_criteria: list[str],
 +) -> list[str]:
 +    """Preserve task-grounded scope when refreshed artifacts are narrower."""
++
 +    grounded_existing = [
 +        item
 +        for item in existing_acceptance_criteria
 +        if item.strip()
 +        and item.strip().lower() != task_statement.strip().lower()
 +        and _task_text_covers_requirement(task_statement, item)
 +    ]
 +    return list(dict.fromkeys([*grounded_existing, *refreshed_acceptance_criteria]))
++
++
 +def merge_refreshed_todos_with_existing_scope(
 +    task_statement: str,
 +    *,
 +    existing_pending_items: list[str],
 +    existing_completed_items: list[str],
 +    refreshed_steps: list[str],
 +) -> list[dict[str, str]]:
 +    """Merge one refreshed plan with task-grounded todo scope already in flight."""
++
 +    grounded_completed = [
 +        item
 +        for item in existing_completed_items
 +        if item.strip()
 +        and item not in _SPECIAL_TODO_ITEMS
 +        and _task_text_covers_requirement(task_statement, item)
 +    ]
 +    grounded_pending = [
 +        item
 +        for item in existing_pending_items
 +        if item.strip()
 +        and item not in _SPECIAL_TODO_ITEMS
 +        and _task_text_covers_requirement(task_statement, item)
 +    ]
++
 +    todos: list[dict[str, str]] = []
 +    seen: set[str] = set()
 +    for item in grounded_completed:
 +        if item in seen:
 +            continue
 +        seen.add(item)
 +        todos.append(
 +            {
 +                "content": item,
 +                "active_form": f"Working on: {item}",
 +                "status": "completed",
 +            }
 +        )
 +    for item in [*grounded_pending, *refreshed_steps]:
 +        label = item.strip()
 +        if not label or label in seen:
 +            continue
 +        seen.add(label)
 +        todos.append(
 +            {
 +                "content": label,
 +                "active_form": f"Working on: {label}",
 +                "status": "pending",
 +            }
 +        )
 +    return todos
++
++
  def advance_todos_from_tool_call(dod, tool_call: ToolCall) -> bool:
      """Advance the best-matching pending todo from a successful tool call."""
      parent = Path(path_hint).parent.name.lower() if path_hint else ""
      score = 0
 +    is_discovery_tool = name in {"read", "glob", "grep"}
 +    if name == "bash":
 +        is_discovery_tool = _looks_like_search_command(command) or _looks_like_read_command(command)
 +    if (
 +        is_discovery_tool
 +        and _contains_any(text, _MUTATION_STEP_HINTS)
 +        and not (
 +            _contains_any(text, _READ_STEP_HINTS)
 +            or _contains_any(text, _SEARCH_STEP_HINTS)
 +            or _contains_any(text, _PARSE_STEP_HINTS)
 +            or _contains_any(text, _VERIFY_STEP_HINTS)
 +        )
 +    ):
 +        return 0
++
      if basename and basename in text:
          score += 3
      if parent and parent not in {"", "."} and parent in text:
      return lines
 +def _replace_markdown_section_items(
 +    markdown: str,
 +    title: str,
 +    items: list[str],
 +) -> str:
 +    lines = markdown.rstrip().splitlines()
 +    heading = f"## {title}".lower()
 +    start_index: int | None = None
 +    end_index = len(lines)
 +    for index, line in enumerate(lines):
 +        if line.strip().lower() == heading:
 +            start_index = index
 +            continue
 +        if start_index is not None and re.match(r"^##+\s+", line.strip()):
 +            end_index = index
 +            break
++
 +    replacement = _render_section(title, items)
 +    if start_index is None:
 +        body = "\n".join(lines).rstrip()
 +        suffix = "\n\n" if body else ""
 +        replacement_text = "\n".join(replacement).rstrip()
 +        return f"{body}{suffix}{replacement_text}\n"
++
 +    updated = [*lines[:start_index], *replacement, *lines[end_index:]]
 +    return "\n".join(updated).rstrip() + "\n"
++
++
  def _first_item(items: list[str] | None) -> str | None:
      if not items:
          return None
      return merged, merged != current
 +def _task_text_covers_requirement(task_text: str, requirement: str) -> bool:
 +    normalized_text = task_text.lower()
 +    normalized_requirement = requirement.lower()
 +    if normalized_requirement in normalized_text:
 +        return True
 +    if (
 +        _requirement_describes_output_scope(normalized_requirement)
 +        and _task_mentions_multiple_outputs(normalized_text)
 +    ):
 +        return True
++
 +    tokens = [
 +        token
 +        for token in re.findall(r"[a-z0-9_./-]+", normalized_requirement)
 +        if len(token) > 2 and token not in _TASK_COVERAGE_STOP_WORDS
 +    ]
 +    if not tokens:
 +        return normalized_requirement.strip() in normalized_text
 +    matches = sum(1 for token in tokens if token in normalized_text)
 +    threshold = max(1, min(2, len(tokens)))
 +    return matches >= threshold
++
++
 +def _task_mentions_multiple_outputs(task_text: str) -> bool:
 +    matches = re.findall(
 +        r"(?:~/(?:[A-Za-z0-9_.-]+/)+[A-Za-z0-9_.-]+(?:\.[A-Za-z0-9]+)?|"
 +        r"/(?:Users|home|tmp|var|private)/(?:[A-Za-z0-9_. -]+/)+[A-Za-z0-9_.-]+(?:\.[A-Za-z0-9]+)?|"
 +        r"[A-Za-z0-9_.-]+\.html|chapters/)",
 +        task_text,
 +    )
 +    if len(matches) >= 2:
 +        return True
 +    if matches and re.search(
 +        r"\b(chapter files?|files?|directories|directory structure|folders|pages|artifacts?|outputs?)\b",
 +        task_text,
 +    ):
 +        return True
 +    return False
++
++
 +def _requirement_describes_output_scope(requirement: str) -> bool:
 +    return any(
 +        phrase in requirement
 +        for phrase in (
 +            "all files",
 +            "file naming",
 +            "correct locations",
 +            "directory structure",
 +            "proper directory structure",
 +            "all links",
 +            "no broken links",
 +            "formatted and consistent",
 +            "consistent in style",
 +        )
 +    )
++
++
  def _mark_explicit_section(brief: ClarifyBrief, section: str) -> None:
      if section in brief.explicit_sections:
          return

src/loader/runtime/workflow_lanes.pymodified

      WorkflowPolicy,
      WorkflowTimelineEntryKind,
      enrich_clarify_brief_with_grounding,
 +    merge_refreshed_todos_with_existing_scope,
 +    preserve_task_grounded_acceptance_criteria,
      sync_todos_to_definition_of_done,
+ )
  from .workflow_ledger import (
              if response.content.strip()
              else PlanningArtifacts.fallback(task_statement=task)
+         )
 +        if refresh_reasons:
 +            preserved_acceptance = preserve_task_grounded_acceptance_criteria(
 +                task,
 +                existing_acceptance_criteria=list(dod.acceptance_criteria),
 +                refreshed_acceptance_criteria=list(artifacts.acceptance_criteria),
 +            )
 +            artifacts = artifacts.with_acceptance_criteria(preserved_acceptance)
          implementation_path, verification_path = self.artifact_store.write_plan(
              task,
              artifacts,
          dod.implementation_plan = str(implementation_path)
          dod.verification_plan = str(verification_path)
          if refresh_reasons:
 -            dod.acceptance_criteria = list(dict.fromkeys(artifacts.acceptance_criteria))
 +            dod.acceptance_criteria = list(artifacts.acceptance_criteria)
          else:
              dod.acceptance_criteria = list(
                  dict.fromkeys(dod.acceptance_criteria + artifacts.acceptance_criteria)
              dod=dod,
              emit=emit,
              executor=executor,
 +            task_statement=task,
 +            preserve_existing_scope=bool(refresh_reasons),
+         )
      async def _emit_artifact(
          dod: DefinitionOfDone,
          emit: EventSink,
          executor: ToolExecutor | None,
 +        task_statement: str,
 +        preserve_existing_scope: bool = False,
      ) -> None:
          if not artifacts.implementation_steps:
              return
          assert executor is not None
 +        if preserve_existing_scope:
 +            todos = merge_refreshed_todos_with_existing_scope(
 +                task_statement,
 +                existing_pending_items=list(dod.pending_items),
 +                existing_completed_items=list(dod.completed_items),
 +                refreshed_steps=list(artifacts.implementation_steps[:8]),
 +            )
 +        else:
              todos = [
+                 {
                      "content": step,
+                 }
                  for step in artifacts.implementation_steps[:8]
+             ]
 +        if not todos:
 +            return
++
          tool_call = ToolCall(
              id="plan-todos-1",
              name="TodoWrite",
              refresh_block = (
                  "Refresh the existing planning artifacts instead of creating a fresh plan "
                  "from scratch.\n"
 +                "Preserve the original task outcome and acceptance scope unless the user "
 +                "explicitly changed the task.\n"
 +                "Do not redefine success around partially completed work or a sample "
 +                "artifact.\n"
                  "Use the current task state and these recovery reasons:\n"
                  + "\n".join(f"- {item}" for item in refresh_reasons)
                  + "\n\n"

tests/test_runtime_harness.pymodified


 
     assert any("TOC references chapter files that do not exist" in message for message in messages)
     assert any(
-        "Use the current target contents plus the verified sibling inventory instead of guessing." in message
+        "Use the current TOC target contents plus the verified sibling inventory" in message
         for message in steering_messages
     )
+    assert any(str(index_file) in message for message in steering_messages)
     assert any(
         "chapters/05-input-output.html = Chapter 5: Input and Output" in message
         for message in steering_messages

         for message in messages
     )
     assert any(
-        "The verified chapter inventory already lists the exact href/title pairs for this directory"
+        "verified sibling chapter inventory"
         in message
         for message in messages
     )

         for message in messages
     )
     assert any(
-        "already passes the validated chapter-link check" in message
+        "already passed semantic link validation" in message
         for message in messages
     )
     assert any(
-        "already satisfies the verified chapter-link constraints" in message
+        "already satisfies the verified link/title constraints" in message
         for message in steering_messages
     )
     assert any(
-        "Do not reread `index.html` or files in `chapters/`" in message
+        "Do not reread" in message and "chapters" in message
         for message in steering_messages
     )
     assert "validated 2 toc links in index.html" in run.response

         in message
         for message in steering_messages
     )
+    assert any(str(index_file) in message for message in steering_messages)
     assert (
         sum(
             1

tests/test_safeguard_services.pymodified

      ActionTracker,
      PreActionValidator,
      ValidationResult,
 +)
 +from loader.runtime.safeguards import RuntimeSafeguards
 +from loader.runtime.semantic_rules.html_toc import (
      build_html_toc_edit_call_template,
      build_html_toc_replacement_block,
 +    build_validated_html_toc_observation_reason,
 +    build_verified_html_inventory_observation_reason,
      format_html_inventory_entry,
 +    task_targets_html_toc,
      validate_html_toc,
+ )
 -from loader.runtime.safeguards import RuntimeSafeguards
  def test_action_tracker_detects_duplicate_write_after_recording(tmp_path) -> None:
      assert str(file_path) in reason
 +def test_task_targets_html_toc_requires_explicit_repair_intent() -> None:
 +    prompt = (
 +        "Have a look at ~/Loader/guides/fortran and chapters/ within. Get a feel "
 +        "for the structure and cadence of the guide. We are going to make an all "
 +        "new equally thorough guide on how to use the nginx tool. It will live in "
 +        "~/Loader/guides/nginx/index.html and ~/Loader/guides/nginx/chapters/."
 +    )
++
 +    assert task_targets_html_toc(prompt) is False
++
++
  def test_build_html_toc_replacement_block_uses_verified_inventory(tmp_path) -> None:
      chapters = tmp_path / "chapters"
      chapters.mkdir()
      assert tracker.check_tool_call("read", {"file_path": str(index_path)}) == (
          True,
 -        "The current index.html already passes the validated chapter-link check; stop rereading index.html or chapters/ and finish the task unless a specific href or title is still unresolved",
 +        build_validated_html_toc_observation_reason(index_path),
+     )
      assert tracker.check_tool_call("read", {"file_path": str(chapter_path)}) == (
          True,
 -        "The current index.html already passes the validated chapter-link check; stop rereading index.html or chapters/ and finish the task unless a specific href or title is still unresolved",
 +        build_validated_html_toc_observation_reason(chapter_path),
+     )
      assert tracker.check_tool_call(
          "glob",
          {"path": str(chapters), "pattern": "*.html"},
      ) == (
          True,
 -        "The current index.html already passes the validated chapter-link check; stop rereading index.html or chapters/ and finish the task unless a specific href or title is still unresolved",
 +        build_validated_html_toc_observation_reason(chapters),
+     )
      assert tracker.check_tool_call(
          "bash",
          {"command": f"cat {index_path}"},
      ) == (
          True,
 -        "The current index.html already passes the validated chapter-link check; stop rereading index.html or chapters/ and finish the task unless a specific href or title is still unresolved",
 +        build_validated_html_toc_observation_reason(index_path),
+     )
      tracker.record_tool_call(
      assert tracker.check_tool_call("read", {"file_path": str(index_path)}) == (False, "")
      assert tracker.check_tool_call("read", {"file_path": str(chapter_path)}) == (
          True,
 -        "The verified chapter inventory already lists the exact href/title pairs for this directory; update index.html from that inventory instead of rereading chapter files",
 +        build_verified_html_inventory_observation_reason(chapter_path),
+     )
      assert tracker.check_tool_call(
          "glob",
          {"path": str(chapters), "pattern": "*.html"},
      ) == (
          True,
 -        "The verified chapter inventory already lists the exact href/title pairs for this directory; update index.html from that inventory instead of rereading chapter files",
 +        build_verified_html_inventory_observation_reason(chapters),
+     )
      assert tracker.check_tool_call(
          "bash",
          {"command": f"head -20 {chapter_path}"},
      ) == (
          True,
 -        "The verified chapter inventory already lists the exact href/title pairs for this directory; update index.html from that inventory instead of rereading chapter files",
 +        build_verified_html_inventory_observation_reason(chapter_path),
+     )
      is_duplicate, reason = tracker.check_tool_call("read", {"file_path": str(index_path)})
      assert is_duplicate is True
 -    assert "known file/title evidence" in reason
 +    assert "reuse that file/title evidence" in reason
  def test_action_tracker_blocks_repeated_chapter_directory_search_once_titles_are_known(
      is_duplicate, reason = tracker.check_tool_call("glob", search_args)
      assert is_duplicate is True
 -    assert "known filename/title evidence" in reason
 +    assert "reuse that filename/title evidence" in reason
  def test_action_tracker_allows_repeated_read_after_mutation(tmp_path) -> None:

tests/test_tool_batch_policies.pymodified

          assess_confidence=assess_confidence,
          verify_action=verify_action,
+     )
 +    context.session.current_task = (
 +        "Update index.html so every chapter link and title matches the real HTML files in chapters/."
 +    )
      controller = ToolBatchRecoveryController(context)
      tool_call = ToolCall(id="bash-1", name="bash", arguments={"command": "pytest"})
      outcome = tool_outcome(tool_call=tool_call, output="command failed", is_error=True)
      assert "04-variables.html" in follow_up.content
      assert "02-basic-syntax.html -> 02-setup.html" in follow_up.content
      assert "02-setup.html = Chapter 2: Setting Up Fortran" in follow_up.content
 -    assert "`~/Loader/guides/fortran/index.html`" in follow_up.content
 +    assert "/Users/mfwolffe/Loader/guides/fortran/index.html" in follow_up.content
      assert any(event.type == "recovery" for event in events)
          assess_confidence=assess_confidence,
          verify_action=verify_action,
+     )
 +    context.session.current_task = (
 +        "Update index.html so every chapter link and title matches the real HTML files in chapters/."
 +    )
      controller = ToolBatchRecoveryController(context)
      tool_call = ToolCall(
          id="patch-index",
      assert 'old_string="""' in follow_up.content
 +@pytest.mark.asyncio
 +async def test_tool_batch_recovery_controller_scopes_known_state_to_active_target(
 +    temp_dir: Path,
 +) -> None:
 +    async def assess_confidence(
 +        tool_name: str,
 +        tool_args: dict,
 +        context: str,
 +    ) -> ConfidenceAssessment:
 +        raise AssertionError("Confidence should not run here")
++
 +    async def verify_action(
 +        tool_name: str,
 +        tool_args: dict,
 +        result: str,
 +        expected: str = "",
 +    ) -> ActionVerification:
 +        raise AssertionError("Verification should not run here")
++
 +    nginx_chapters = temp_dir / "nginx" / "chapters"
 +    nginx_chapters.mkdir(parents=True)
 +    nginx_index = temp_dir / "nginx" / "index.html"
 +    nginx_index.write_text(
 +        "<h2>Table of Contents</h2>\n"
 +        "<ul>\n"
 +        '    <li><a href="chapters/01_getting_started.html">Getting Started with NGINX</a></li>\n'
 +        '    <li><a href="chapters/02_installation.html">Installation</a></li>\n'
 +        "</ul>\n"
 +    )
 +    (nginx_chapters / "01_getting_started.html").write_text(
 +        "<h1>Getting Started with NGINX</h1>\n"
 +    )
++
 +    context = build_context(
 +        temp_dir=temp_dir,
 +        messages=[
 +            Message(
 +                role=Role.TOOL,
 +                content=(
 +                    "Observation [read]: Result: "
 +                    f"{temp_dir / 'fortran' / 'index.html'}\n"
 +                    "Semantic verification preview: validated 12 toc links in index.html"
 +                ),
 +            ),
 +        ],
 +        assess_confidence=assess_confidence,
 +        verify_action=verify_action,
 +    )
 +    context.session.current_task = (  # type: ignore[attr-defined]
 +        "Have a look at ~/Loader/guides/fortran and chapters/ within. Get a feel "
 +        "for the structure and cadence of the guide. We are going to make an all "
 +        "new equally thorough guide on how to use the nginx tool. It will live in "
 +        "~/Loader/guides/nginx/index.html and ~/Loader/guides/nginx/chapters/."
 +    )
 +    controller = ToolBatchRecoveryController(context)
 +    tool_call = ToolCall(
 +        id="edit-nginx",
 +        name="edit",
 +        arguments={
 +            "file_path": str(nginx_index),
 +            "old_string": "<ul>\n</ul>",
 +            "new_string": "<ul class=\"chapter-list\">\n</ul>",
 +        },
 +    )
 +    outcome = tool_outcome(
 +        tool_call=tool_call,
 +        output=(
 +            "Tool execution error: EditTool.execute() missing 1 required positional "
 +            "argument: 'new_string'"
 +        ),
 +        is_error=True,
 +    )
++
 +    events: list[AgentEvent] = []
++
 +    async def emit(event: AgentEvent) -> None:
 +        events.append(event)
++
 +    follow_up = await controller.build_follow_up(
 +        tool_call=tool_call,
 +        outcome=outcome,
 +        emit=emit,
 +    )
++
 +    assert follow_up is not None
 +    assert (
 +        "Preferred next step: Update "
 +        f"`{temp_dir / 'fortran' / 'index.html'}`"
 +    ) not in follow_up.content
++
++
  @pytest.mark.asyncio
  async def test_tool_batch_recovery_controller_reuses_context_for_related_missing_files(
      temp_dir: Path,

tests/test_tool_batches.pymodified

+ )
  from loader.runtime.recovery import RecoveryContext
  from loader.runtime.tool_batches import ToolBatchRunner
 +from loader.runtime.workflow import sync_todos_to_definition_of_done
  from loader.tools.base import ToolResult as RegistryToolResult
  from loader.tools.base import create_default_registry
  from tests.helpers.runtime_harness import ScriptedBackend
          verify_action=verify_action,
          auto_recover=False,
+     )
 +    context.session.current_task = (
 +        "Update index.html so every chapter link and title matches the real HTML files in chapters/."
 +    )
      queued_messages: list[str] = []
      context.queue_steering_message_callback = queued_messages.append
      runner = ToolBatchRunner(context, DefinitionOfDoneStore(temp_dir))
          pending_tool_calls_seen=set(),
          emit=_noop_emit,
          summary=summary,
 -        dod=create_definition_of_done("Fix the chapter links"),
 +        dod=create_definition_of_done(
 +            "Update index.html so every chapter link and title matches the real HTML files in chapters/."
 +        ),
          executor=executor,  # type: ignore[arg-type]
          on_confirmation=None,
          on_user_question=None,
          for message in summary.tool_result_messages
+     )
      assert len(queued_messages) == 1
 -    assert "already satisfies the verified chapter-link constraints" in queued_messages[0]
 -    assert "Do not reread `index.html` or files in `chapters/`" in queued_messages[0]
 +    assert "already satisfies the verified link/title constraints" in queued_messages[0]
 +    assert f"`{index_path}`" in queued_messages[0]
 +    assert f"`{chapters}`" in queued_messages[0]
++
++
 +@pytest.mark.asyncio
 +async def test_tool_batch_runner_does_not_apply_html_toc_handoff_to_reference_read(
 +    temp_dir: Path,
 +) -> None:
 +    async def assess_confidence(
 +        tool_name: str,
 +        tool_args: dict,
 +        context: str,
 +    ) -> ConfidenceAssessment:
 +        raise AssertionError("Confidence scoring should be disabled in this scenario")
++
 +    async def verify_action(
 +        tool_name: str,
 +        tool_args: dict,
 +        result: str,
 +        expected: str = "",
 +    ) -> ActionVerification:
 +        raise AssertionError("Verification should not run for this scenario")
++
 +    chapters = temp_dir / "chapters"
 +    chapters.mkdir()
 +    (chapters / "01-introduction.html").write_text(
 +        "<h1>Chapter 1: Introduction to Fortran</h1>\n"
 +    )
 +    (chapters / "02-setup.html").write_text(
 +        "<h1>Chapter 2: Setting Up Your Environment</h1>\n"
 +    )
 +    index_path = temp_dir / "index.html"
 +    index_path.write_text(
 +        "<h2>Table of Contents</h2>\n"
 +        '<ul class="chapter-list">\n'
 +        '    <li><a href="chapters/01-introduction.html">Chapter 1: Introduction to Fortran</a></li>\n'
 +        '    <li><a href="chapters/02-setup.html">Chapter 2: Setting Up Your Environment</a></li>\n'
 +        "</ul>\n"
 +    )
++
 +    prompt = (
 +        "Have a look at ~/Loader/guides/fortran and chapters/ within. Get a feel "
 +        "for the structure and cadence of the guide. We are going to make an all "
 +        "new equally thorough guide on how to use the nginx tool."
 +    )
++
 +    context = build_context(
 +        temp_dir=temp_dir,
 +        messages=[],
 +        safeguards=FakeSafeguards(),
 +        assess_confidence=assess_confidence,
 +        verify_action=verify_action,
 +        auto_recover=False,
 +    )
 +    context.session.current_task = prompt  # type: ignore[attr-defined]
 +    queued_messages: list[str] = []
 +    context.queue_steering_message_callback = queued_messages.append
 +    runner = ToolBatchRunner(context, DefinitionOfDoneStore(temp_dir))
 +    tool_call = ToolCall(
 +        id="read-index",
 +        name="read",
 +        arguments={"file_path": str(index_path)},
 +    )
 +    executor = FakeExecutor(
 +        [
 +            tool_outcome(
 +                tool_call=tool_call,
 +                output=index_path.read_text(),
 +                is_error=False,
 +            )
 +        ]
 +    )
++
 +    summary = TurnSummary(final_response="")
 +    await runner.execute_batch(
 +        tool_calls=[tool_call],
 +        tool_source="assistant",
 +        pending_tool_calls_seen=set(),
 +        emit=_noop_emit,
 +        summary=summary,
 +        dod=create_definition_of_done(prompt),
 +        executor=executor,  # type: ignore[arg-type]
 +        on_confirmation=None,
 +        on_user_question=None,
 +        emit_confirmation=None,
 +        consecutive_errors=0,
 +    )
++
 +    assert queued_messages == []
 +    assert all(
 +        "Semantic verification preview:" not in message.content
 +        for message in summary.tool_result_messages
 +    )
++
++
 +@pytest.mark.asyncio
 +async def test_tool_batch_runner_queues_next_pending_todo_after_discovery_progress(
 +    temp_dir: Path,
 +) -> None:
 +    async def assess_confidence(
 +        tool_name: str,
 +        tool_args: dict,
 +        context: str,
 +    ) -> ConfidenceAssessment:
 +        raise AssertionError("Confidence scoring should be disabled in this scenario")
++
 +    async def verify_action(
 +        tool_name: str,
 +        tool_args: dict,
 +        result: str,
 +        expected: str = "",
 +    ) -> ActionVerification:
 +        raise AssertionError("Verification should not run for this scenario")
++
 +    reference = temp_dir / "fortran" / "index.html"
 +    reference.parent.mkdir(parents=True)
 +    reference.write_text("<h1>Fortran Beginner's Guide</h1>\n")
++
 +    context = build_context(
 +        temp_dir=temp_dir,
 +        messages=[],
 +        safeguards=FakeSafeguards(),
 +        assess_confidence=assess_confidence,
 +        verify_action=verify_action,
 +        auto_recover=False,
 +    )
 +    queued_messages: list[str] = []
 +    context.queue_steering_message_callback = queued_messages.append
 +    runner = ToolBatchRunner(context, DefinitionOfDoneStore(temp_dir))
 +    dod = create_definition_of_done("Create an equally thorough nginx guide.")
 +    sync_todos_to_definition_of_done(
 +        dod,
 +        [
 +            {
 +                "content": "Examine the existing Fortran guide structure to understand the cadence and format",
 +                "active_form": "Working on: Examine the existing Fortran guide structure to understand the cadence and format",
 +                "status": "pending",
 +            },
 +            {
 +                "content": "Create the nginx directory structure",
 +                "active_form": "Working on: Create the nginx directory structure",
 +                "status": "pending",
 +            },
 +            {
 +                "content": "Create the nginx index.html file",
 +                "active_form": "Working on: Create the nginx index.html file",
 +                "status": "pending",
 +            },
 +        ],
 +    )
 +    tool_call = ToolCall(
 +        id="read-reference",
 +        name="read",
 +        arguments={"file_path": str(reference)},
 +    )
 +    executor = FakeExecutor(
 +        [
 +            tool_outcome(
 +                tool_call=tool_call,
 +                output="<h1>Fortran Beginner's Guide</h1>\n",
 +                is_error=False,
 +            )
 +        ]
 +    )
++
 +    summary = TurnSummary(final_response="")
 +    await runner.execute_batch(
 +        tool_calls=[tool_call],
 +        tool_source="assistant",
 +        pending_tool_calls_seen=set(),
 +        emit=_noop_emit,
 +        summary=summary,
 +        dod=dod,
 +        executor=executor,  # type: ignore[arg-type]
 +        on_confirmation=None,
 +        on_user_question=None,
 +        emit_confirmation=None,
 +        consecutive_errors=0,
 +    )
++
 +    assert (
 +        "Examine the existing Fortran guide structure to understand the cadence and format"
 +        in dod.completed_items
 +    )
 +    assert any(
 +        "Continue with the next pending item: `Create the nginx directory structure`"
 +        in message
 +        for message in queued_messages
 +    )
++
++
 +@pytest.mark.asyncio
 +async def test_tool_batch_runner_duplicate_reference_read_prefers_next_pending_todo(
 +    temp_dir: Path,
 +) -> None:
 +    async def assess_confidence(
 +        tool_name: str,
 +        tool_args: dict,
 +        context: str,
 +    ) -> ConfidenceAssessment:
 +        raise AssertionError("Confidence scoring should be disabled in this scenario")
++
 +    async def verify_action(
 +        tool_name: str,
 +        tool_args: dict,
 +        result: str,
 +        expected: str = "",
 +    ) -> ActionVerification:
 +        raise AssertionError("Verification should not run for this scenario")
++
 +    reference = temp_dir / "fortran" / "index.html"
 +    reference.parent.mkdir(parents=True)
 +    reference.write_text("<h1>Fortran Beginner's Guide</h1>\n")
++
 +    messages = [
 +        Message(
 +            role=Role.TOOL,
 +            content=(
 +                "Observation [read]: Result: "
 +                "<h1>Fortran Beginner's Guide</h1>\n"
 +            ),
 +        )
 +    ]
 +    context = build_context(
 +        temp_dir=temp_dir,
 +        messages=messages,
 +        safeguards=FakeSafeguards(),
 +        assess_confidence=assess_confidence,
 +        verify_action=verify_action,
 +        auto_recover=False,
 +    )
 +    prompt = (
 +        "Have a look at ~/Loader/guides/fortran and chapters/ within. Get a feel "
 +        "for the structure and cadence of the guide. We are going to make an all "
 +        "new equally thorough guide on how to use the nginx tool."
 +    )
 +    context.session.current_task = prompt
 +    queued_messages: list[str] = []
 +    context.queue_steering_message_callback = queued_messages.append
 +    runner = ToolBatchRunner(context, DefinitionOfDoneStore(temp_dir))
 +    dod = create_definition_of_done(prompt)
 +    sync_todos_to_definition_of_done(
 +        dod,
 +        [
 +            {
 +                "content": "Examine the existing Fortran guide structure to understand the cadence and format",
 +                "active_form": "Working on: Examine the existing Fortran guide structure to understand the cadence and format",
 +                "status": "completed",
 +            },
 +            {
 +                "content": "Create the nginx directory structure",
 +                "active_form": "Working on: Create the nginx directory structure",
 +                "status": "pending",
 +            },
 +            {
 +                "content": "Create the nginx index.html file",
 +                "active_form": "Working on: Create the nginx index.html file",
 +                "status": "pending",
 +            },
 +        ],
 +    )
 +    tool_call = ToolCall(
 +        id="read-dup",
 +        name="read",
 +        arguments={"file_path": str(reference)},
 +    )
 +    duplicate_message = (
 +        "[Skipped - duplicate action: Already read "
 +        f"{reference} recently without any intervening changes; "
 +        "reuse the earlier read result instead of rereading]"
 +    )
 +    executor = FakeExecutor(
 +        [
 +            ToolExecutionOutcome(
 +                tool_call=tool_call,
 +                state=ToolExecutionState.DUPLICATE,
 +                message=Message.tool_result_message(
 +                    tool_call_id=tool_call.id,
 +                    display_content=duplicate_message,
 +                    result_content=duplicate_message,
 +                ),
 +                event_content=duplicate_message,
 +                is_error=False,
 +                result_output=duplicate_message,
 +            )
 +        ]
 +    )
++
 +    summary = TurnSummary(final_response="")
 +    await runner.execute_batch(
 +        tool_calls=[tool_call],
 +        tool_source="assistant",
 +        pending_tool_calls_seen=set(),
 +        emit=_noop_emit,
 +        summary=summary,
 +        dod=dod,
 +        executor=executor,  # type: ignore[arg-type]
 +        on_confirmation=None,
 +        on_user_question=None,
 +        emit_confirmation=None,
 +        consecutive_errors=0,
 +    )
++
 +    assert len(queued_messages) == 1
 +    assert "Reuse the earlier observation instead of repeating it." in queued_messages[0]
 +    assert "Continue with the next pending item: `Create the nginx directory structure`" in queued_messages[0]
 +    assert "Update `" not in queued_messages[0]
  @pytest.mark.asyncio
      assert len(queued_messages) == 1
      assert "already matches the validated replacement block" in queued_messages[0]
 -    assert "validated 2 toc links in `index.html`" in queued_messages[0]
 +    assert "validated 2 linked entries" in queued_messages[0]
 +    assert f"`{index_path}`" in queued_messages[0]
      assert "Do not call `edit`, `patch`, or reread the same TOC again" in queued_messages[0]

tests/test_workflow.pymodified

      build_execute_bridge,
      enrich_clarify_brief_with_grounding,
      extract_verification_commands_from_markdown,
 +    merge_refreshed_todos_with_existing_scope,
 +    preserve_task_grounded_acceptance_criteria,
      sync_todos_to_definition_of_done,
+ )
+     ]
 +def test_preserve_task_grounded_acceptance_criteria_keeps_original_scope_on_refresh() -> None:
 +    task = (
 +        "Create an equally thorough nginx guide with index.html plus chapter files "
 +        "covering getting started, installation, first website setup, configs, and "
 +        "advanced topics."
 +    )
++
 +    preserved = preserve_task_grounded_acceptance_criteria(
 +        task,
 +        existing_acceptance_criteria=[
 +            "All files are created in the correct locations with proper directory structure",
 +            "Content covers all required topics: getting started, installation, first website, configuration basics, advanced configurations, and troubleshooting",
 +        ],
 +        refreshed_acceptance_criteria=[
 +            "At least one chapter file exists in ~/Loader/guides/nginx/chapters/",
 +            "~/Loader/guides/nginx/index.html exists and contains proper table of contents",
 +        ],
 +    )
++
 +    assert (
 +        "All files are created in the correct locations with proper directory structure"
 +        in preserved
 +    )
 +    assert (
 +        "Content covers all required topics: getting started, installation, first website, configuration basics, advanced configurations, and troubleshooting"
 +        in preserved
 +    )
 +    assert "At least one chapter file exists in ~/Loader/guides/nginx/chapters/" in preserved
++
++
 +def test_preserve_task_grounded_acceptance_criteria_drops_stale_plan_specific_scope() -> None:
 +    task = (
 +        "Implement a persistent workflow artifact with planning artifacts, "
 +        "verification commands, and plan refresh discipline."
 +    )
++
 +    preserved = preserve_task_grounded_acceptance_criteria(
 +        task,
 +        existing_acceptance_criteria=["planned.txt exists in the workspace root."],
 +        refreshed_acceptance_criteria=["notes.txt exists in the workspace root."],
 +    )
++
 +    assert preserved == ["notes.txt exists in the workspace root."]
++
++
 +def test_planning_artifacts_with_acceptance_criteria_rewrites_verification_markdown() -> None:
 +    artifacts = PlanningArtifacts.from_model_output(
 +        "\n".join(
 +            [
 +                "# Implementation Plan",
 +                "",
 +                "## Execution Order",
 +                "1. Create the guide files.",
 +                "",
 +                "<<<VERIFICATION>>>",
 +                "",
 +                "# Verification Plan",
 +                "",
 +                "## Acceptance Criteria",
 +                "- At least one chapter file exists.",
 +                "",
 +                "## Verification Commands",
 +                "- `find chapters -name \"*.html\" | wc -l`",
 +            ]
 +        ),
 +        task_statement="Create a thorough nginx guide.",
 +    )
++
 +    updated = artifacts.with_acceptance_criteria(
 +        [
 +            "All files are created in the correct locations.",
 +            "Content covers getting started, installation, and advanced topics.",
 +        ]
 +    )
++
 +    assert "At least one chapter file exists." not in updated.verification_markdown
 +    assert "All files are created in the correct locations." in updated.verification_markdown
 +    assert (
 +        "Content covers getting started, installation, and advanced topics."
 +        in updated.verification_markdown
 +    )
++
++
 +def test_merge_refreshed_todos_with_existing_scope_keeps_grounded_progress() -> None:
 +    task = (
 +        "Create an equally thorough nginx guide with index.html plus chapter files "
 +        "covering getting started, installation, first website setup, configs, and "
 +        "advanced topics."
 +    )
++
 +    todos = merge_refreshed_todos_with_existing_scope(
 +        task,
 +        existing_pending_items=[
 +            "Create each chapter file in sequence, following the established pattern",
 +            "Collect verification evidence",
 +        ],
 +        existing_completed_items=["Create directory structure for the new nginx guide"],
 +        refreshed_steps=["Create sample chapter file to verify the structure works"],
 +    )
++
 +    assert todos[0]["content"] == "Create directory structure for the new nginx guide"
 +    assert todos[0]["status"] == "completed"
 +    assert any(
 +        item["content"] == "Create each chapter file in sequence, following the established pattern"
 +        and item["status"] == "pending"
 +        for item in todos
 +    )
++
++
  def test_workflow_artifact_store_and_bridge_round_trip(tmp_path: Path) -> None:
      store = WorkflowArtifactStore(tmp_path)
      brief = ClarifyBrief.fallback(

`@@ -2022,9 +2022,10 @@` async def test_blocked_html_index_edit_queues_inventory_reuse_steering(
2022	2022
2023	2023	assert any("TOC references chapter files that do not exist" in message for message in messages)
2024	2024	assert any(
2025		- "Use the current target contents plus the verified sibling inventory instead of guessing." in message
	2025	+ "Use the current TOC target contents plus the verified sibling inventory" in message
2026	2026	for message in steering_messages
2027	2027	)
	2028	+ assert any(str(index_file) in message for message in steering_messages)
2028	2029	assert any(
2029	2030	"chapters/05-input-output.html = Chapter 5: Input and Output" in message
2030	2031	for message in steering_messages
`@@ -2141,7 +2142,7 @@` async def test_verified_html_inventory_blocks_redundant_chapter_reread(
2141	2142	for message in messages
2142	2143	)
2143	2144	assert any(
2144		- "The verified chapter inventory already lists the exact href/title pairs for this directory"
	2145	+ "verified sibling chapter inventory"
2145	2146	in message
2146	2147	for message in messages
2147	2148	)
`@@ -2240,15 +2241,15 @@` async def test_successful_html_toc_edit_blocks_post_success_reread_and_steers_to
2240	2241	for message in messages
2241	2242	)
2242	2243	assert any(
2243		- "already passes the validated chapter-link check" in message
	2244	+ "already passed semantic link validation" in message
2244	2245	for message in messages
2245	2246	)
2246	2247	assert any(
2247		- "already satisfies the verified chapter-link constraints" in message
	2248	+ "already satisfies the verified link/title constraints" in message
2248	2249	for message in steering_messages
2249	2250	)
2250	2251	assert any(
2251		- "Do not reread `index.html` or files in `chapters/`" in message
	2252	+ "Do not reread" in message and "chapters" in message
2252	2253	for message in steering_messages
2253	2254	)
2254	2255	assert "validated 2 toc links in index.html" in run.response
`@@ -2334,6 +2335,7 @@` async def test_exact_prompt_finishes_when_index_toc_is_already_correct(
2334	2335	in message
2335	2336	for message in steering_messages
2336	2337	)
	2338	+ assert any(str(index_file) in message for message in steering_messages)
2337	2339	assert (
2338	2340	sum(
2339	2341	1