`873539b`

Strengthen first-file write retries

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

SHA: 873539bc38b6b34463c156edf85b5291f9454cd2
Parents: 9dceae8
Tree: ee2b0be

2 changed files

Status	File	+	-
M	`src/loader/runtime/repair.py`	121	36
M	`tests/test_repair.py`	138	8

src/loader/runtime/repair.pymodified

          retry_number: int,
          max_empty_retries: int,
      ) -> str | None:
 -        if not self._has_confirmed_output_file_progress(dod):
 -            return None
 -        if self._has_confirmed_substantive_output_file_progress(dod):
 +        has_confirmed_output_file_progress = self._has_confirmed_output_file_progress(
 +            dod
 +        )
 +        has_confirmed_substantive_output_file_progress = (
 +            self._has_confirmed_substantive_output_file_progress(dod)
 +        )
 +        if has_confirmed_substantive_output_file_progress:
              return None
          next_missing_artifact = self._preferred_resume_missing_artifact(dod)
              dod,
              missing_artifact=next_missing_artifact,
+         )
 +        if (
 +            next_pending
 +            and not _todo_is_mutation_step(next_pending)
 +            and not _todo_is_consistency_review_step(next_pending)
 +        ):
 +            return None
 +        if not has_confirmed_output_file_progress and any(
 +            str(raw_path).strip() for raw_path in dod.touched_files
 +        ):
 +            return None
          inferred_pending_target = (
              self._infer_pending_item_output_target(dod, next_pending)
              if next_pending
              project_root=self.context.project_root,
              todo_label=next_pending or "",
+         )
 -        if next_pending and _todo_is_mutation_step(next_pending):
 +        if (
 +            next_pending
 +            and _todo_is_mutation_step(next_pending)
 +            and not todo_describes_broad_setup_step(next_pending)
 +        ):
              first_line = (
 -                f"Continue `{next_pending}` by creating `{concrete_target.name}`."
 +                "Resume with this exact next step: continue "
 +                f"`{next_pending}` by creating `{concrete_target.name}`."
+             )
          else:
 -            first_line = f"Create `{concrete_target.name}` now."
 -        compact_retry = True
 +            first_line = (
 +                f"Resume with this exact next step: create `{concrete_target.name}`."
 +            )
 -        lines = [
 -            first_line,
 -            self._mutation_tool_scaffold(concrete_target, tool_name="write"),
 -        ]
 +        lines: list[str] = []
 +        if (
 +            not has_confirmed_output_file_progress
 +            and next_missing_artifact is not None
 +            and not next_missing_artifact[1]
 +        ):
 +            lines.append(
 +                "Next missing planned artifact: "
 +                f"{self._format_artifact_label(concrete_target, expect_directory=False)}"
 +            )
 +        lines.extend(
 +            [
 +                first_line,
 +                "Prefer one `write(content=...)` call for "
 +                f"`{display_runtime_path(concrete_target)}` before more research.",
 +                self._mutation_tool_scaffold(concrete_target, tool_name="write"),
 +            ]
 +        )
 +        if (
 +            next_pending
 +            and todo_describes_aggregate_mutation(next_pending)
 +            and not todo_describes_broad_setup_step(next_pending)
 +        ):
 +            lines.insert(
 +                2,
 +                f"It is the next concrete output needed to continue `{next_pending}`.",
 +            )
 +        if not concrete_target.parent.exists():
 +            lines.append(
 +                "The `write` tool can create that file's parent directories automatically, "
 +                "so do the write in one step instead of stopping for a separate mkdir."
 +            )
          if outline_label:
              lines.append(
                  f"Use the existing outline label `{outline_label}` for that file so it matches the current guide structure."
+             )
 -        html_scaffold_line = self._known_existing_html_scaffold_line(
 -            concrete_target,
 -            require_first_substantive_output=True,
 -        )
 -        if html_scaffold_line:
 -            lines.append(html_scaffold_line)
 -        html_starter_line = self._known_html_starter_shape_line(
 -            concrete_target,
 -            require_first_substantive_output=True,
 -            retry_number=retry_number,
 -            outline_label=outline_label,
 -        )
 -        if html_starter_line:
 -            lines.append(html_starter_line)
 -        html_payload_line = self._known_minimal_html_payload_line(
 -            concrete_target,
 +        self._append_concrete_html_write_cues(
 +            lines,
 +            target=concrete_target,
              outline_label=outline_label,
              retry_number=retry_number,
 +            has_confirmed_output_file_progress=has_confirmed_output_file_progress,
 +            has_confirmed_substantive_output_file_progress=(
 +                has_confirmed_substantive_output_file_progress
 +            ),
+         )
 -        if html_payload_line:
 -            lines.append(html_payload_line)
          if (
 -            not compact_retry
 -            and _should_encourage_initial_version(
 +            _should_encourage_initial_version(
                  target=concrete_target,
 -                has_confirmed_output_file_progress=True,
 -                has_confirmed_substantive_output_file_progress=False,
 +                has_confirmed_output_file_progress=has_confirmed_output_file_progress,
 +                has_confirmed_substantive_output_file_progress=(
 +                    has_confirmed_substantive_output_file_progress
 +                ),
+             )
          ):
              lines.append(
                      has_confirmed_output_file_progress
                      and not has_confirmed_substantive_output_file_progress
                  ),
 +                allow_initial_concrete_output=False,
                  retry_number=retry_number,
                  outline_label=outline_label,
+             )
              has_confirmed_output_file_progress
              and not has_confirmed_substantive_output_file_progress
+         )
 +        initial_concrete_output = (
 +            not has_confirmed_output_file_progress
 +            and not has_confirmed_substantive_output_file_progress
 +        )
          html_scaffold_line = self._known_existing_html_scaffold_line(
              target,
              require_first_substantive_output=first_substantive_output,
                      and retry_number >= 4
+                 )
              ),
 +            allow_initial_concrete_output=initial_concrete_output,
              retry_number=retry_number,
              outline_label=outline_label,
+         )
          html_payload_line = self._known_minimal_html_payload_line(
              target,
              outline_label=outline_label,
 +            allow_initial_concrete_output=initial_concrete_output,
              retry_number=retry_number,
+         )
          if html_payload_line:
          target: Path,
          *,
          require_first_substantive_output: bool,
 +        allow_initial_concrete_output: bool,
          retry_number: int,
          outline_label: str | None,
      ) -> str | None:
 -        if not require_first_substantive_output or retry_number < 1:
 +        if (
 +            not require_first_substantive_output
 +            and not allow_initial_concrete_output
 +        ) or retry_number < 1:
              return None
          if target.suffix.lower() not in {".html", ".htm"}:
              return None
 -        label = outline_label.strip() if outline_label and outline_label.strip() else "this chapter"
 +        label = (
 +            outline_label.strip()
 +            if outline_label and outline_label.strip()
 +            else self._fallback_html_label(target)
 +        )
 +        if self._is_index_html_target(target):
 +            return (
 +                f"If you get stuck, start with `<!DOCTYPE html>`, `<title>{label}</title>`, "
 +                f"`<h1>{label}</h1>`, a short intro paragraph, and a linked chapter list that points at the guide pages you will create under `chapters/`."
 +            )
          return (
              f"If you get stuck, start with `<title>{label}</title>`, "
              f"`<h1>{label}</h1>`, one introductory paragraph, a couple of `<h2>` "
          target: Path,
          *,
          outline_label: str | None,
 +        allow_initial_concrete_output: bool,
          retry_number: int,
      ) -> str | None:
          if retry_number < 5:
          if target.suffix.lower() not in {".html", ".htm"}:
              return None
 -        label = outline_label.strip() if outline_label and outline_label.strip() else target.stem
 +        label = (
 +            outline_label.strip()
 +            if outline_label and outline_label.strip()
 +            else self._fallback_html_label(target)
 +        )
 +        if self._is_index_html_target(target):
 +            return (
 +                "If blanking continues, use this minimal starter payload shape inside the `write` call now: "
 +                f"`<!DOCTYPE html><html lang=\"en\"><head><meta charset=\"UTF-8\"><meta name=\"viewport\" "
 +                f"content=\"width=device-width, initial-scale=1.0\"><title>{label}</title></head><body>"
 +                f"<div class=\"container\"><h1>{label}</h1><p>...</p><nav><ul>"
 +                "<li><a href=\"chapters/01-...html\">Chapter 1: ...</a></li>"
 +                "<li><a href=\"chapters/02-...html\">Chapter 2: ...</a></li>"
 +                "</ul></nav></div></body></html>` and refine it later."
 +            )
          return (
              "If blanking continues, use this minimal starter payload shape inside the `write` call now: "
              f"`<!DOCTYPE html><html lang=\"en\"><head><meta charset=\"UTF-8\"><meta name=\"viewport\" "
              "</div></body></html>` and refine it later."
+         )
 +    @staticmethod
 +    def _is_index_html_target(target: Path) -> bool:
 +        return target.name.lower() in {"index.html", "index.htm"}
++
 +    def _fallback_html_label(self, target: Path) -> str:
 +        if self._is_index_html_target(target):
 +            parent_name = target.parent.name.strip()
 +            if parent_name:
 +                return f"{parent_name.title()} Guide"
 +            return "Main Guide"
 +        return target.stem
++
      def _best_known_root_html_scaffold(self, target: Path) -> Path | None:
          normalized_target = target.expanduser().resolve(strict=False)
          if normalized_target.suffix.lower() not in {".html", ".htm"}:

tests/test_repair.pymodified

          in decision.retry_message
+     )
      assert (
 -        "Prefer one `write` call for "
 -        f"`{display_runtime_path(index_path)}` before any more reference reads."
 +        "Prefer one `write(content=...)` call for "
 +        f"`{display_runtime_path(index_path)}` before more research."
          in decision.retry_message
+     )
      assert (
          "Write a compact but real initial version of this file now, then refine or expand it in later edits."
          in decision.retry_message
+     )
 -    assert "Do not restart discovery unless one specific missing fact blocks this step." in decision.retry_message
 +    assert (
 +        "No narration, no TodoWrite, no rereads, and no empty response; emit the mutation tool call now."
 +        in decision.retry_message
 +    )
  def test_empty_response_retry_uses_directory_creation_for_setup_targets(
      assert decision.should_continue is True
      assert decision.retry_message is not None
      assert "retry 5/6" in decision.retry_message
 -    assert "Continue `Create 01-introduction.html` by creating `01-introduction.html`." in decision.retry_message
 +    assert (
 +        "Resume with this exact next step: continue `Create 01-introduction.html` "
 +        "by creating `01-introduction.html`."
 +        in decision.retry_message
 +    )
      assert 'Emit this tool shape now: `write(file_path="' in decision.retry_message
      assert "No narration, no TodoWrite, no rereads, and no empty response" in decision.retry_message
      assert "Make the next response one concrete evidence-gathering tool call" not in decision.retry_message
 +def test_empty_response_retry_adds_root_html_starter_shape_for_first_index_write(
 +    temp_dir: Path,
 +) -> None:
 +    context = build_context(
 +        temp_dir=temp_dir,
 +        use_react=False,
 +    )
 +    repairer = ResponseRepairer(context)
++
 +    guide_root = temp_dir / "guides" / "nginx"
 +    chapters = guide_root / "chapters"
 +    guide_root.mkdir(parents=True)
 +    chapters.mkdir()
 +    index_path = guide_root / "index.html"
 +    chapter_one = chapters / "01-introduction.html"
++
 +    implementation_plan = temp_dir / "implementation.md"
 +    implementation_plan.write_text(
 +        "\n".join(
 +            [
 +                "# Implementation Plan",
 +                "",
 +                "## File Changes",
 +                f"- `{guide_root}/`",
 +                f"- `{index_path}`",
 +                f"- `{chapters}/`",
 +                f"- `{chapter_one}`",
 +                "",
 +            ]
 +        )
 +    )
++
 +    dod = create_definition_of_done("Create a multi-file nginx guide.")
 +    dod.implementation_plan = str(implementation_plan)
 +    dod.completed_items.extend(
 +        [
 +            "First, examine the existing Fortran guide structure to understand the format and depth",
 +            "Create the new nginx guide directory structure",
 +        ]
 +    )
 +    dod.pending_items.append("Develop the main index.html file with proper structure")
++
 +    decision = repairer.handle_empty_response(
 +        task="Create a multi-file nginx guide.",
 +        original_task=None,
 +        empty_retry_count=2,
 +        max_empty_retries=2,
 +        dod=dod,
 +    )
++
 +    assert decision.should_continue is True
 +    assert decision.retry_message is not None
 +    assert (
 +        "If you get stuck, start with `<!DOCTYPE html>`, `<title>Nginx Guide</title>`, "
 +        "`<h1>Nginx Guide</h1>`, a short intro paragraph, and a linked chapter list that "
 +        "points at the guide pages you will create under `chapters/`."
 +        in decision.retry_message
 +    )
 +    assert "../index.html" not in decision.retry_message
++
++
 +def test_repeated_first_index_retry_includes_root_html_payload_shape(
 +    temp_dir: Path,
 +) -> None:
 +    context = build_context(
 +        temp_dir=temp_dir,
 +        use_react=False,
 +    )
 +    repairer = ResponseRepairer(context)
++
 +    guide_root = temp_dir / "guides" / "nginx"
 +    chapters = guide_root / "chapters"
 +    guide_root.mkdir(parents=True)
 +    chapters.mkdir()
 +    index_path = guide_root / "index.html"
 +    chapter_one = chapters / "01-introduction.html"
++
 +    implementation_plan = temp_dir / "implementation.md"
 +    implementation_plan.write_text(
 +        "\n".join(
 +            [
 +                "# Implementation Plan",
 +                "",
 +                "## File Changes",
 +                f"- `{guide_root}/`",
 +                f"- `{index_path}`",
 +                f"- `{chapters}/`",
 +                f"- `{chapter_one}`",
 +                "",
 +            ]
 +        )
 +    )
++
 +    dod = create_definition_of_done("Create a multi-file nginx guide.")
 +    dod.implementation_plan = str(implementation_plan)
 +    dod.completed_items.extend(
 +        [
 +            "First, examine the existing Fortran guide structure to understand the format and depth",
 +            "Create the new nginx guide directory structure",
 +        ]
 +    )
 +    dod.pending_items.append("Develop the main index.html file with proper structure")
++
 +    decision = repairer.handle_empty_response(
 +        task="Create a multi-file nginx guide.",
 +        original_task=None,
 +        empty_retry_count=5,
 +        max_empty_retries=6,
 +        dod=dod,
 +    )
++
 +    assert decision.should_continue is True
 +    assert decision.retry_message is not None
 +    assert "If blanking continues, use this minimal starter payload shape" in decision.retry_message
 +    assert "<title>Nginx Guide</title>" in decision.retry_message
 +    assert 'href="chapters/01-...html"' in decision.retry_message
 +    assert "../index.html" not in decision.retry_message
++
++
  def test_empty_response_retry_prefers_pending_index_over_broad_directory_headline(
      temp_dir: Path,
  ) -> None:
      assert decision.retry_message is not None
      assert "Next missing planned artifact:" not in decision.retry_message
      assert (
 -        "Continue `Create chapter files with content and structure` by creating `01-introduction.html`."
 +        "Resume with this exact next step: continue `Create chapter files with content and structure` "
 +        "by creating `01-introduction.html`."
          in decision.retry_message
+     )
      assert (
      assert decision.should_continue is True
      assert decision.retry_message is not None
      assert (
 -        f"Continue `Develop the nginx index.html file` by creating `{output_index.name}`."
 +        "Resume with this exact next step: continue `Develop the nginx index.html file` "
 +        f"by creating `{output_index.name}`."
          in decision.retry_message
+     )
      assert (
      assert decision.should_continue is True
      assert decision.retry_message is not None
      assert (
 -        "Continue `Write the introduction chapter` by creating `introduction.html`."
 +        "Resume with this exact next step: continue `Write the introduction chapter` "
 +        "by creating `introduction.html`."
          in decision.retry_message
+     )
      assert "Next declared output under `chapters/`" not in decision.retry_message
      assert decision.should_continue is True
      assert decision.retry_message is not None
      assert (
 -        "Continue `Write the introduction chapter` by creating `01-introduction.html`."
 +        "Resume with this exact next step: continue `Write the introduction chapter` "
 +        "by creating `01-introduction.html`."
          in decision.retry_message
+     )
      assert (