`3719f44`

Require fuller multi-page guides

Authored by

espadonne 2 weeks ago

SHA: 3719f4431684609a1cc91e140601ea2f5bf5edb5
Parents: 365993c
Tree: 5759936

3 changed files

Status	File	+	-
M	`src/loader/runtime/dod.py`	104	12
M	`tests/test_dod.py`	76	0
M	`tests/test_tool_batches.py`	2	11

src/loader/runtime/dod.pymodified

      "develop",
      "developing",
+ )
 +_MINIMUM_SUBSTANTIVE_HTML_GUIDE_PAGES = 4
  @dataclass
      project_root: Path,
      task_statement: str,
  ) -> str | None:
 -    html_paths = _multi_page_html_quality_paths(dod, project_root=project_root)
 -    if len(html_paths) < 4:
 -        return None
      if not _task_requires_substantive_html_guide_quality(task_statement):
          return None
 +    html_paths = _multi_page_html_quality_paths(dod, project_root=project_root)
 +    requires_multiple_pages = _requires_multiple_html_pages(
 +        dod,
 +        project_root=project_root,
 +    )
 +    if requires_multiple_pages and len(html_paths) < _MINIMUM_SUBSTANTIVE_HTML_GUIDE_PAGES:
 +        return "\n".join(
 +            [
 +                "python3 - <<'PY'",
 +                f"minimum_pages = {_MINIMUM_SUBSTANTIVE_HTML_GUIDE_PAGES}",
 +                f"found_pages = {len(html_paths)}",
 +                "print('HTML guide content quality issues:')",
 +                "print(",
 +                "    f'insufficient HTML page count ({found_pages} files, expected at least {minimum_pages})'",
 +                ")",
 +                "raise SystemExit(1)",
 +                "PY",
 +            ]
 +        )
 +    if len(html_paths) < _MINIMUM_SUBSTANTIVE_HTML_GUIDE_PAGES:
 +        return None
      path_literals = ", ".join(repr(str(path)) for path in html_paths)
      return "\n".join(
          for target, expect_directory in targets
      ):
          return False
 +    if _substantive_multi_page_html_guide_is_incomplete(
 +        dod,
 +        project_root=project_root,
 +    ):
 +        return False
      return not _planned_html_outputs_have_missing_local_links(
          dod,
          project_root=project_root,
          project_root=project_root,
          max_paths=24,
+     )
 -    planned_html = [
 -        target
 -        for target, expect_directory in planned_targets
 -        if not expect_directory and target.suffix.lower() in {".html", ".htm"}
 -    ]
 -    if planned_html:
 -        return planned_html
 +    paths: list[Path] = []
 +    seen: set[str] = set()
++
 +    for target, expect_directory in planned_targets:
 +        if expect_directory:
 +            if not target.exists():
 +                continue
 +            try:
 +                discovered = sorted(path for path in target.rglob("*.html") if path.is_file())
 +            except OSError:
 +                continue
 +            for path in discovered:
 +                key = str(path)
 +                if key in seen:
 +                    continue
 +                seen.add(key)
 +                paths.append(path)
 +            continue
 +        if target.suffix.lower() not in {".html", ".htm"} or not target.exists():
 +            continue
 +        key = str(target)
 +        if key in seen:
 +            continue
 +        seen.add(key)
 +        paths.append(target)
++
 +    if paths:
 +        return paths
      touched_html = []
      for path_str in dod.touched_files:
      return list(dict.fromkeys(touched_html))
 +def _requires_multiple_html_pages(
 +    dod: DefinitionOfDone,
 +    *,
 +    project_root: Path,
 +) -> bool:
 +    planned_targets = collect_planned_artifact_targets(
 +        dod,
 +        project_root=project_root,
 +        max_paths=24,
 +    )
 +    if any(
 +        expect_directory
 +        and planned_directory_requires_generated_files(
 +            dod,
 +            target=target,
 +            project_root=project_root,
 +        )
 +        for target, expect_directory in planned_targets
 +    ):
 +        return True
++
 +    planned_html = [
 +        target
 +        for target, expect_directory in planned_targets
 +        if not expect_directory and target.suffix.lower() in {".html", ".htm"}
 +    ]
 +    if len(planned_html) > 1:
 +        return True
++
 +    lowered = dod.task_statement.lower()
 +    return "chapter" in lowered or "chapters" in lowered
++
++
 +def _substantive_multi_page_html_guide_is_incomplete(
 +    dod: DefinitionOfDone,
 +    *,
 +    project_root: Path,
 +) -> bool:
 +    if not _task_requires_substantive_html_guide_quality(dod.task_statement):
 +        return False
 +    if not _requires_multiple_html_pages(dod, project_root=project_root):
 +        return False
 +    html_paths = _multi_page_html_quality_paths(dod, project_root=project_root)
 +    return len(html_paths) < _MINIMUM_SUBSTANTIVE_HTML_GUIDE_PAGES
++
++
  def _task_requires_substantive_html_guide_quality(task_statement: str) -> bool:
      lowered = task_statement.lower()
      if not any(token in lowered for token in ("guide", "tutorial", "documentation", "docs")):
              "detailed",
              "equally",
              "cadence",
 -            "chapter",
 -            "chapters",
 +            "depth",
 +            "same structure",
 +            "same style",
+         )
+     )

tests/test_dod.pymodified

      assert any("HTML guide content quality issues:" in command for command in commands)
 +def test_derive_verification_commands_flags_insufficient_pages_for_broad_thorough_guide(
 +    tmp_path: Path,
 +) -> None:
 +    guide = tmp_path / "guide"
 +    chapters = guide / "chapters"
 +    chapters.mkdir(parents=True)
 +    (guide / "index.html").write_text("<html></html>\n")
 +    (chapters / "01-introduction.html").write_text("<h1>Intro</h1>\n")
++
 +    implementation_plan = tmp_path / "implementation.md"
 +    implementation_plan.write_text(
 +        "\n".join(
 +            [
 +                "# Implementation Plan",
 +                "",
 +                "## File Changes",
 +                f"- `{guide / 'index.html'}`",
 +                f"- `{chapters}/` (directory for chapter files)",
 +                "",
 +                "## Execution Order",
 +                "- Create chapter files with appropriate content",
 +            ]
 +        )
 +    )
++
 +    dod = create_definition_of_done(
 +        "Create an equally thorough multi-page HTML guide with chapter files."
 +    )
 +    dod.implementation_plan = str(implementation_plan)
++
 +    commands = derive_verification_commands(
 +        dod,
 +        project_root=tmp_path,
 +        task_statement=dod.task_statement,
 +        supplement_existing=True,
 +    )
++
 +    assert any("insufficient HTML page count" in command for command in commands)
++
++
  def test_collect_planned_artifact_targets_ignores_prose_path_fragments_in_refreshed_plan(
      tmp_path: Path,
  ) -> None:
      assert all_planned_artifacts_exist(dod, project_root=tmp_path) is False
 +def test_all_planned_artifacts_exist_stays_false_for_substantive_guide_with_only_one_chapter(
 +    tmp_path: Path,
 +) -> None:
 +    implementation_plan = tmp_path / "implementation.md"
 +    implementation_plan.write_text(
 +        "\n".join(
 +            [
 +                "# Implementation Plan",
 +                "",
 +                "## File Changes",
 +                f"- `{tmp_path / 'guide' / 'index.html'}`",
 +                f"- `{tmp_path / 'guide' / 'chapters'}/` (directory for chapter files)",
 +                "",
 +                "## Execution Order",
 +                "- Create chapter files with appropriate content",
 +            ]
 +        )
 +    )
++
 +    guide_root = tmp_path / "guide"
 +    chapters = guide_root / "chapters"
 +    chapters.mkdir(parents=True)
 +    (guide_root / "index.html").write_text("<html></html>\n")
 +    (chapters / "01-introduction.html").write_text("<h1>Intro</h1>\n")
++
 +    dod = create_definition_of_done("Create an equally thorough guide with chapters.")
 +    dod.implementation_plan = str(implementation_plan)
 +    dod.completed_items = ["Create chapter files with appropriate content"]
 +    dod.touched_files = [
 +        str(guide_root / "index.html"),
 +        str(chapters / "01-introduction.html"),
 +    ]
++
 +    assert all_planned_artifacts_exist(dod, project_root=tmp_path) is False
++
++
  def test_all_planned_artifacts_exist_respects_nested_file_change_entries(
      tmp_path: Path,
  ) -> None:

tests/test_tool_batches.pymodified

  @pytest.mark.asyncio
 -async def test_tool_batch_runner_glob_handoff_stays_compact_before_first_output_write(
 +async def test_tool_batch_runner_shallow_glob_does_not_handoff_before_content_read(
      temp_dir: Path,
  ) -> None:
      async def assess_confidence(
          consecutive_errors=0,
+     )
 -    assert queued_messages
 -    message = queued_messages[-1]
 -    assert "Confirmed progress:" in message
 -    assert "Next step: create `index.html`." in message
 -    assert (
 -        f"Prefer one `write` call for `{temp_dir / 'Loader' / 'guides' / 'nginx' / 'index.html'}` now."
 -        in message
 -    )
 -    assert "One declared output artifact is still missing." not in message
 -    assert "Do not reread reference material or spend the next turn on bookkeeping." in message
 +    assert queued_messages == []
  @pytest.mark.asyncio