`6236b4d`

Steer structural HTML repairs

Authored by mfwolffe <wolffemf@dukes.jmu.edu> 1 week ago

SHA: 6236b4d4c3d85c4e3ed6fa14721a2790b37ad941
Parents: 3f4faaf
Tree: 0a212d2

8 changed files

Status	File	+	-
M	`src/loader/runtime/finalization.py`	16	2
M	`src/loader/runtime/repair.py`	24	16
M	`src/loader/runtime/repair_focus.py`	49	0
M	`src/loader/runtime/tool_batches.py`	13	11
M	`src/loader/runtime/turn_completion.py`	25	16
M	`tests/test_finalization.py`	35	0
M	`tests/test_repair.py`	42	0
M	`tests/test_turn_completion.py`	76	0

src/loader/runtime/finalization.pymodified

  from .logging import get_runtime_logger
  from .memory import MemoryStore
  from .policy_timeline import append_verification_timeline_entry
 +from .repair_focus import html_repair_issue_is_structural
  from .session import normalize_usage
  from .tracing import RuntimeTracer
  from .verification_observations import (
      lines = ["Repair focus:"]
      lines.extend(_html_quality_repair_target_lines(targets))
      primary = targets[0]
 +    if html_repair_issue_is_structural(primary.issue):
 +        immediate_step = (
 +            f"- Immediate next step: replace `{primary.artifact_path}` with one complete "
 +            "valid HTML document that preserves the page content while fixing the "
 +            "listed structure issue."
 +        )
 +    else:
 +        immediate_step = (
 +            f"- Immediate next step: edit `{primary.artifact_path}` with a substantial "
 +            "expansion or replacement that satisfies its listed quality issue."
 +        )
      lines.extend(
+         [
 -            f"- Immediate next step: edit `{primary.artifact_path}` with a substantial "
 -            "expansion or replacement that satisfies its listed quality issue.",
 +            immediate_step,
              *_html_quality_repair_strategy_lines(),
              "- Repair every listed quality target in order before any final answer; "
              "do not stop after touching only the first file.",
  def _html_quality_repair_strategy_lines() -> list[str]:
      return [
 +        "- If a target mentions duplicate closing tags, closing tags in the wrong order, "
 +        "or content after `</html>`, replace the malformed file with one complete "
 +        "valid HTML document; do not append more content after an existing closing tag.",
          "- If a target says thin content, add enough concrete prose to comfortably "
          "exceed the expected text-character floor; if it says insufficient "
          "structured content, add enough real sections, lists, code, tables, or "

src/loader/runtime/repair.pymodified

  from .repair_focus import (
      ActiveRepairContext,
      extract_active_repair_context,
 +    html_repair_issue_is_structural,
      recent_repair_mutation_context_failed,
 +    repair_line_is_html_quality,
 +    repair_line_matches_target,
+ )
  from .workflow import (
      infer_output_outline_label,
+             (
                  line
                  for line in repair.repair_lines
 -                if target in line and _repair_line_is_html_quality(line)
 +                if repair_line_matches_target(line, target)
 +                and _repair_line_is_html_quality(line)
              ),
              next(
+                 (
+         ]
          if issue_line:
              lines.append(f"- Current verifier issue: {issue_line[2:] if issue_line.startswith('- ') else issue_line}")
 -        force_write = recent_repair_mutation_context_failed(
 +        structural_issue = html_repair_issue_is_structural(issue_line)
 +        force_write = structural_issue or recent_repair_mutation_context_failed(
              self.context.session.messages,
              target,
+         )
          if force_write:
 +            structural_suffix = (
 +                " Ensure the replacement has exactly one closing `</body>` tag, "
 +                "exactly one closing `</html>` tag, and no content after `</html>`."
 +                if structural_issue
 +                else ""
 +            )
 +            reason = (
 +                "- The active verifier is reporting malformed HTML document "
 +                "structure. "
 +                if structural_issue
 +                else "- Recent `edit`/`patch` attempts for this same target failed "
 +                "against stale or malformed context. "
 +            )
              lines.extend(
+                 [
 -                    "- Recent `edit`/`patch` attempts for this same target failed "
 -                    "against stale or malformed context. Use exactly one "
 +                    reason
 +                    + "Use exactly one "
                      "`write(file_path=..., content=...)` call now with a complete "
 -                    "valid HTML document for that file.",
 +                    f"valid HTML document for that file.{structural_suffix}",
                      "- Do not call `read`, `edit`, `patch`, TodoWrite, or a final "
                      "summary on this retry; emit the `write` mutation tool call now.",
+                 ]
  def _repair_line_is_html_quality(line: str) -> bool:
 -    lowered = line.lower()
 -    return any(
 -        phrase in lowered
 -        for phrase in (
 -            "thin content",
 -            "insufficient structured content",
 -            "content-quality",
 -            "quality target",
 -            "html guide content quality",
 -        )
 -    )
 +    return repair_line_is_html_quality(line)
  def _should_encourage_initial_version(

src/loader/runtime/repair_focus.pymodified

      "structured patch hunks overlap",
      "failed to complete the operation after",
+ )
 +_HTML_REPAIR_ISSUE_MARKERS = (
 +    "thin content",
 +    "insufficient structured content",
 +    "content-quality",
 +    "content quality",
 +    "quality target",
 +    "html guide content quality",
 +    "expected exactly one closing </body>",
 +    "expected exactly one closing </html>",
 +    "content appears after closing </html>",
 +    "closing </body> appears after closing </html>",
 +    "missing <h1>",
 +)
 +_HTML_STRUCTURAL_REPAIR_MARKERS = (
 +    "expected exactly one closing </body>",
 +    "expected exactly one closing </html>",
 +    "content appears after closing </html>",
 +    "closing </body> appears after closing </html>",
 +)
  @dataclass(frozen=True)
      return False
 +def repair_line_is_html_quality(line: str) -> bool:
 +    """Return whether a repair-focus line describes generated HTML quality."""
++
 +    lowered = str(line or "").lower()
 +    return any(marker in lowered for marker in _HTML_REPAIR_ISSUE_MARKERS)
++
++
 +def repair_line_matches_target(line: str, target: str) -> bool:
 +    """Return whether a repair-focus line refers to the target path."""
++
 +    line_text = str(line or "")
 +    target_text = str(target or "").strip()
 +    if not line_text or not target_text:
 +        return False
 +    normalized_target = normalize_repair_path(target_text)
 +    if target_text in line_text or (normalized_target and normalized_target in line_text):
 +        return True
 +    for candidate in re.findall(r"`([^`]+)`", line_text):
 +        if normalize_repair_path(candidate) == normalized_target:
 +            return True
 +    return False
++
++
 +def html_repair_issue_is_structural(line: str) -> bool:
 +    """Return whether an HTML quality issue is about document structure."""
++
 +    lowered = str(line or "").lower()
 +    return any(marker in lowered for marker in _HTML_STRUCTURAL_REPAIR_MARKERS)
++
++
  def normalize_repair_path(raw_path: str) -> str:
      text = str(raw_path or "").strip()
      if not text:

src/loader/runtime/tool_batches.pymodified

  from .recovery import RecoveryContext, detect_missing_mutation_payload
  from .repair_focus import (
      extract_active_repair_context,
 +    html_repair_issue_is_structural,
      path_within_allowed_roots,
      recent_repair_mutation_context_failed,
 +    repair_line_is_html_quality,
+ )
  from .safeguard_services import extract_shell_text_rewrite_target
  from .tool_batch_checks import ToolBatchConfidenceGate, ToolBatchVerificationGate
                  if repair_issue
                  else f"- Improve `{target}` until it satisfies the active content-quality verifier.\n"
+             )
 +            structural_repair = html_repair_issue_is_structural(repair_issue)
              force_write = recent_repair_mutation_context_failed(
                  self.context.session.messages,
                  target,
+             )
 -            if force_write:
 +            if force_write or structural_repair:
 +                structural_suffix = (
 +                    " Ensure the replacement has exactly one closing `</body>` tag, "
 +                    "exactly one closing `</html>` tag, and no content after `</html>`."
 +                    if structural_repair
 +                    else ""
 +                )
                  immediate_step = (
                      f"- Immediate next step: rewrite `{target}` with one `write` call.\n"
 -                    "- Recent `edit`/`patch` attempts for this file failed against stale "
 -                    "or malformed context. Use `write(file_path=..., content=...)` with "
 +                    "- Use `write(file_path=..., content=...)` with "
                      "a complete valid HTML document, and do not call `read`, `edit`, "
 -                    "`patch`, or TodoWrite again first."
 +                    f"`patch`, or TodoWrite again first.{structural_suffix}"
+                 )
              else:
                  immediate_step = (
  def _repair_line_is_html_quality(line: str) -> bool:
 -    lowered = str(line or "").lower()
 -    return (
 -        "thin content" in lowered
 -        or "insufficient structured content" in lowered
 -        or "content-quality" in lowered
 -        or "content quality" in lowered
 -    )
 +    return repair_line_is_html_quality(line)
  def _next_quality_repair_path(repair: Any, *, changed_path: str) -> str:

src/loader/runtime/turn_completion.pymodified

  from .repair import ResponseRepairer
  from .repair_focus import (
      extract_active_repair_context,
 +    html_repair_issue_is_structural,
      recent_repair_mutation_context_failed,
 +    repair_line_is_html_quality,
 +    repair_line_matches_target,
+ )
  from .rollback import RollbackPlan
  from .verification_observations import VerificationObservation
      if not target_text:
          return None
 -    force_write = recent_repair_mutation_context_failed(
 +    stale_context = recent_repair_mutation_context_failed(
          cast(list[Message], messages),
          target_text,
+     )
+         (
              line[2:] if line.startswith("- ") else line
              for line in repair.repair_lines
 -            if target_text in line and _repair_line_is_html_quality(line)
 +            if repair_line_matches_target(line, target_text)
 +            and _repair_line_is_html_quality(line)
          ),
          "",
+     )
      issue_sentence = f" Current verifier issue: {issue_line}" if issue_line else ""
 +    structural_issue = html_repair_issue_is_structural(issue_line)
 +    force_write = stale_context or structural_issue
      if force_write:
 +        structural_sentence = (
 +            " Ensure the replacement has exactly one closing `</body>` tag, "
 +            "exactly one closing `</html>` tag, and no content after `</html>`."
 +            if structural_issue
 +            else ""
 +        )
 +        failure_reason = (
 +            "The active verifier is reporting malformed HTML document structure. "
 +            if structural_issue and not stale_context
 +            else "Recent `patch`/`edit` attempts for this same file failed because their "
 +            "remembered context was stale or malformed. "
 +        )
          prompt = (
              "[CONTINUE QUALITY REPAIR]\n"
              "You just described a content-quality repair, but did not execute it. "
 -            "Recent `patch`/`edit` attempts for this same file failed because their "
 -            "remembered context was stale or malformed. "
 +            f"{failure_reason}"
              f"Emit exactly one `write(file_path=..., content=...)` tool call for `{target_text}` now."
              f"{issue_sentence} "
              "Write a complete valid HTML document for this file that preserves the chapter topic "
 -            "and satisfies the listed quality issue. Do not call `read`, `edit`, `patch`, "
 +            f"and satisfies the listed quality issue.{structural_sentence} Do not call `read`, `edit`, `patch`, "
              "`TodoWrite`, or summarize."
+         )
          return InProgressContinuation(prompt=prompt, target=None)
          "content-quality" in lowered
          or "thin content" in lowered
          or "insufficient structured content" in lowered
 +        or "expected exactly one closing" in lowered
 +        or "content appears after closing </html>" in lowered
+     )
      if not (
          latest_user_content.startswith("[CONTINUE QUALITY REPAIR]")
  def _repair_line_is_html_quality(line: str) -> bool:
 -    lowered = line.lower()
 -    return any(
 -        phrase in lowered
 -        for phrase in (
 -            "thin content",
 -            "insufficient structured content",
 -            "content-quality",
 -            "quality target",
 -            "html guide content quality",
 -        )
 -    )
 +    return repair_line_is_html_quality(line)
  def _next_missing_planned_artifact(

tests/test_finalization.pymodified

      assert str(third_chapter.resolve(strict=False)) in repair.allowed_paths
 +def test_verification_repair_guidance_prioritizes_structural_html_quality_issue(
 +    temp_dir: Path,
 +) -> None:
 +    chapter = temp_dir / "guides" / "nginx" / "chapters" / "08-troubleshooting.html"
 +    chapter.parent.mkdir(parents=True)
 +    chapter.write_text(
 +        "<!DOCTYPE html><html><body><h1>Troubleshooting</h1></body></html>\n"
 +        "<p>Trailing content.</p>\n"
 +    )
 +    dod = create_definition_of_done("Create an equally thorough HTML guide.")
 +    dod.evidence = [
 +        VerificationEvidence(
 +            command="quality",
 +            passed=False,
 +            output=(
 +                "HTML guide content quality issues:\n"
 +                f"{chapter}: expected exactly one closing </html> tag (found 2)\n"
 +            ),
 +        )
 +    ]
++
 +    guidance = _build_verification_repair_guidance(
 +        dod,
 +        project_root=temp_dir,
 +    )
 +    repair = extract_active_repair_context([Message(role=Role.USER, content=guidance)])
++
 +    assert f"Improve `{chapter}`: expected exactly one closing </html> tag" in guidance
 +    assert f"Immediate next step: replace `{chapter}` with one complete" in guidance
 +    assert "replace the malformed file with one complete valid HTML document" in guidance
 +    assert "do not append more content after an existing closing tag" in guidance
 +    assert repair is not None
 +    assert repair.artifact_path == str(chapter.resolve(strict=False))
++
++
  def test_verification_repair_guidance_keeps_multi_file_quality_worklist(
      temp_dir: Path,
  ) -> None:

tests/test_repair.pymodified

      assert "Do not call `read`, `edit`, `patch`, TodoWrite" in decision.retry_message
 +def test_empty_response_retry_forces_write_for_structural_html_repair(
 +    temp_dir: Path,
 +) -> None:
 +    context = build_context(
 +        temp_dir=temp_dir,
 +        use_react=False,
 +    )
 +    repairer = ResponseRepairer(context)
 +    chapter = temp_dir / "guides" / "nginx" / "chapters" / "08-troubleshooting.html"
 +    chapter.parent.mkdir(parents=True)
 +    chapter.write_text(
 +        "<!DOCTYPE html><html><body><h1>Troubleshooting</h1></body></html>\n"
 +        "<p>Trailing content.</p>\n"
 +    )
 +    context.session.append(
 +        Message(
 +            role=Role.USER,
 +            content=(
 +                "Repair focus:\n"
 +                f"- Improve `{chapter}`: content appears after closing </html>.\n"
 +                f"- Immediate next step: replace `{chapter}` with one complete valid HTML document.\n"
 +            ),
 +        )
 +    )
 +    dod = create_definition_of_done("Create an equally thorough HTML guide.")
 +    dod.touched_files = [str(chapter)]
++
 +    decision = repairer.handle_empty_response(
 +        task="Create an equally thorough HTML guide.",
 +        original_task=None,
 +        empty_retry_count=1,
 +        max_empty_retries=2,
 +        dod=dod,
 +    )
++
 +    assert decision.should_continue is True
 +    assert decision.retry_message is not None
 +    assert "content appears after closing </html>" in decision.retry_message
 +    assert "Use exactly one `write(file_path=..., content=...)`" in decision.retry_message
 +    assert "exactly one closing `</body>` tag" in decision.retry_message
++
++
  def test_empty_response_retry_mentions_write_can_create_missing_parent_directories(
      temp_dir: Path,
  ) -> None:

tests/test_turn_completion.pymodified

      assert "Do not call `read`, `edit`, `patch`, `TodoWrite`, or summarize." in message
 +@pytest.mark.asyncio
 +async def test_turn_completion_forces_write_for_structural_html_repair(
 +    temp_dir: Path,
 +) -> None:
 +    backend = ScriptedBackend()
 +    config = non_streaming_config()
 +    config.reasoning.completion_check = False
 +    agent = Agent(
 +        backend=backend,
 +        config=config,
 +        project_root=temp_dir,
 +    )
 +    runtime = ConversationRuntime(agent)
 +    events = []
++
 +    async def capture(event) -> None:
 +        events.append(event)
++
 +    prepared = await runtime.turn_preparation.prepare(
 +        task="Create an equally thorough HTML guide.",
 +        emit=capture,
 +        requested_mode="execute",
 +        original_task=None,
 +        on_user_question=None,
 +    )
 +    await runtime.phase_tracker.enter(
 +        TurnPhase.ASSISTANT,
 +        capture,
 +        detail="Requesting assistant response",
 +        reason_code="request_assistant_response",
 +    )
++
 +    chapter = temp_dir / "guides" / "nginx" / "chapters" / "08-troubleshooting.html"
 +    chapter.parent.mkdir(parents=True)
 +    chapter.write_text(
 +        "<!DOCTYPE html><html><body><h1>Troubleshooting</h1></body></html>\n"
 +        "<p>Trailing content.</p>\n"
 +    )
 +    prepared.definition_of_done.touched_files.append(str(chapter))
 +    agent.session.append(
 +        Message(
 +            role=Role.USER,
 +            content=(
 +                "Repair focus:\n"
 +                f"- Improve `{chapter}`: expected exactly one closing </html> tag (found 2).\n"
 +                f"- Immediate next step: replace `{chapter}` with one complete valid HTML document.\n"
 +            ),
 +        )
 +    )
++
 +    content = "I will fix the malformed troubleshooting HTML structure."
 +    decision = await runtime.turn_completion.handle_text_response(
 +        content=content,
 +        response_content=content,
 +        task=prepared.task,
 +        effective_task=prepared.effective_task,
 +        iterations=1,
 +        max_iterations=agent.config.max_iterations,
 +        actions_taken=[],
 +        continuation_count=0,
 +        dod=prepared.definition_of_done,
 +        emit=capture,
 +        summary=prepared.summary,
 +        executor=prepared.executor,
 +        rollback_plan=prepared.rollback_plan,
 +    )
++
 +    assert decision.action == TurnCompletionAction.CONTINUE
 +    message = agent.session.messages[-1].content
 +    assert message.startswith("[CONTINUE QUALITY REPAIR]")
 +    assert "malformed HTML document structure" in message
 +    assert "expected exactly one closing </html>" in message
 +    assert "exactly one closing `</body>` tag" in message
 +    assert "exactly one `write(file_path=..., content=...)`" in message
++
++
  @pytest.mark.asyncio
  async def test_turn_completion_continues_queued_quality_repair_after_summary(
      temp_dir: Path,