agentic-dev-loop 1.0.0a38__tar.gz → 1.0.0a39__tar.gz

{agentic_dev_loop-1.0.0a38/src/agentic_dev_loop.egg-info → agentic_dev_loop-1.0.0a39}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentic-dev-loop
-Version: 1.0.0a38
+Version: 1.0.0a39
 Summary: Turn an LLM into a gated, sandboxed, resumable construction loop over your codebase.
 Author: Luke Wilson
 License-Expression: Apache-2.0
@@ -260,6 +260,18 @@ run start (or when its inputs change), its `produces:` artifact survives attempt
 starts, and the dev/review agents read that digest instead of re-deriving repo
 rules and environment facts every attempt.
 
+The brief digest is mechanically coverage-checked: the four section headings
+(`Repo rules digest`, `Unit scope and lane digest`, `Environment facts`, and
+`Open risks`) must appear, every anchor extracted from the `include` files
+(markdown `##` headings, and YAML category names plus `enforcement_levels`)
+must appear on its own line (case-insensitive, whitespace-collapsed, `**`
+decoration allowed), and every `env_facts` entry must appear verbatim. A miss
+re-runs the brief agent once per missing set with a `## Coverage retry`
+correction note, bounded to three retries per input set; if the same items are
+still dropped after the cap, the run fails and `last-error.md` names the
+persistent drops. Include files with no extractable anchors pass vacuously, and
+unusual YAML rule shapes are under-checked, never over-checked.
+
 ### Secrets (`secrets:`) - refs only, never values
 
 Secret values never belong in the pipeline yaml, the workspace, or `state_dir`.

{agentic_dev_loop-1.0.0a38 → agentic_dev_loop-1.0.0a39}/README.md

@@ -218,6 +218,18 @@ run start (or when its inputs change), its `produces:` artifact survives attempt
 starts, and the dev/review agents read that digest instead of re-deriving repo
 rules and environment facts every attempt.
 
+The brief digest is mechanically coverage-checked: the four section headings
+(`Repo rules digest`, `Unit scope and lane digest`, `Environment facts`, and
+`Open risks`) must appear, every anchor extracted from the `include` files
+(markdown `##` headings, and YAML category names plus `enforcement_levels`)
+must appear on its own line (case-insensitive, whitespace-collapsed, `**`
+decoration allowed), and every `env_facts` entry must appear verbatim. A miss
+re-runs the brief agent once per missing set with a `## Coverage retry`
+correction note, bounded to three retries per input set; if the same items are
+still dropped after the cap, the run fails and `last-error.md` names the
+persistent drops. Include files with no extractable anchors pass vacuously, and
+unusual YAML rule shapes are under-checked, never over-checked.
+
 ### Secrets (`secrets:`) - refs only, never values
 
 Secret values never belong in the pipeline yaml, the workspace, or `state_dir`.

{agentic_dev_loop-1.0.0a38 → agentic_dev_loop-1.0.0a39}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "agentic-dev-loop"
-version = "1.0.0a38"
+version = "1.0.0a39"
 description = "Turn an LLM into a gated, sandboxed, resumable construction loop over your codebase."
 readme = "README.md"
 requires-python = ">=3.12"

agentic_dev_loop-1.0.0a39/src/agentic_dev_loop/engine/brief_coverage.py

@@ -0,0 +1,96 @@
+"""Mechanical coverage gate for the brief step's section-anchored digest (041).
+
+The brief agent's prompt contract (Part A) promises a structure-preserving
+digest: every top-level section or category name survives on its own line.
+Prompt compliance is not a guarantee, so this module derives the required
+anchors from the include files themselves and checks the captured digest
+against them. The brief node owns the retry budget; these functions stay pure
+and file-agnostic.
+"""
+
+from __future__ import annotations
+
+import re
+
+_REQUIRED_SECTIONS = (
+    "Repo rules digest",
+    "Unit scope and lane digest",
+    "Environment facts",
+    "Open risks",
+)
+
+
+def _normalize(text: str) -> str:
+    """Case-fold and collapse whitespace - the matching normal form."""
+    return " ".join(text.split()).casefold()
+
+
+def _normalize_line(line: str) -> str:
+    """Normalize one digest line, stripping the decorations Part A permits.
+
+    A compliant digest writes anchors as headings on their own line, wrapped
+    in ``**`` and (for the four section headings) prefixed with ``##``. List
+    bullets are tolerated; the whole-line comparison is what makes a mid-line
+    prose mention fail."""
+    stripped = line.strip().replace("**", "")
+    stripped = re.sub(r"^#+\s*", "", stripped)
+    stripped = re.sub(r"^[-*+]\s+", "", stripped)
+    return _normalize(stripped)
+
+
+def required_sections() -> list[str]:
+    """The four template headings the brief must emit."""
+    return list(_REQUIRED_SECTIONS)
+
+
+def extract_anchors(content: str) -> list[str]:
+    """Derive the mechanical anchor set from one include file.
+
+    Markdown contributes every ``## `` heading. YAML contributes each
+    ``- name:`` value under a ``categories:`` block plus the
+    ``enforcement_levels`` key. Anchors are normalized once, at extraction,
+    and de-duplicated in first-seen order."""
+    anchors: list[str] = []
+    in_categories = False
+    for raw in content.splitlines():
+        line = raw.rstrip()
+        stripped = line.strip()
+        if not stripped:
+            continue
+        if stripped == "enforcement_levels:":
+            anchors.append(_normalize("enforcement_levels"))
+        if stripped == "categories:":
+            in_categories = True
+            continue
+        if in_categories:
+            if not line[:1].isspace():
+                in_categories = False
+            else:
+                match = re.match(r"-\s*name:\s*(.+)$", stripped)
+                if match:
+                    anchors.append(_normalize(match.group(1).strip()))
+        if line.startswith("## "):
+            anchors.append(_normalize(line[3:].strip()))
+    return list(dict.fromkeys(anchors))
+
+
+def missing_anchors(brief_text: str, anchors: list[str],
+                    env_facts: list[str]) -> list[str]:
+    """Return every required item the captured brief fails to cover.
+
+    Required section headings and anchors are matched line-anchored
+    (case-insensitive, whitespace-collapsed, ``**`` decoration stripped). Env
+    facts are matched verbatim, exactly as handed to the brief agent. An empty
+    list means the digest passes coverage."""
+    missing: list[str] = []
+    lines = {_normalize_line(line) for line in brief_text.splitlines()}
+    for section in _REQUIRED_SECTIONS:
+        if _normalize(section) not in lines:
+            missing.append(section)
+    for anchor in anchors:
+        if anchor not in lines:
+            missing.append(anchor)
+    for fact in env_facts:
+        if fact not in brief_text:
+            missing.append(fact)
+    return missing

{agentic_dev_loop-1.0.0a38 → agentic_dev_loop-1.0.0a39}/src/agentic_dev_loop/engine/graph.py

@@ -43,6 +43,11 @@ def _merge_artifacts(a: dict[str, str], b: dict[str, str]) -> dict[str, str]:
     return {**a, **b}
 
 
+def _merge_counts(a: dict[str, int], b: dict[str, int]) -> dict[str, int]:
+    """Accumulate the per-step brief coverage retry counts (041)."""
+    return {**a, **b}
+
+
 class LoopState(TypedDict):
     """State threaded through the graph. `notes` accumulates across attempts
     (append reducer), `artifacts` accumulates across stages (merge reducer);
@@ -65,6 +70,7 @@ class LoopState(TypedDict):
     retry_target: str | None           # where the bump node loops back to
     thread_id: str
     brief_hashes: Annotated[dict[str, str], _merge_artifacts]  # step name -> input hash (033)
+    brief_retries: Annotated[dict[str, int], _merge_counts]  # step name -> coverage retries used (041)
 
 
 def build_graph(runtime: Runtime, checkpointer=None):
@@ -215,6 +221,7 @@ def _run_pipeline(cfg, base, registry, state_dir, max_attempts, args, viz_bus,
             "retry_target": None,
             "thread_id": thread_id,
             "brief_hashes": {},
+            "brief_retries": {},
         }
     bus = viz_bus
     with SqliteSaver.from_conn_string(db) as saver:

{agentic_dev_loop-1.0.0a38 → agentic_dev_loop-1.0.0a39}/src/agentic_dev_loop/engine/stages.py

@@ -34,6 +34,7 @@ from openhands.sdk import Conversation
 
 from .agent_error_guide import guide_section
 from .agents import load_agent, register_sandbox_terminal
+from .brief_coverage import extract_anchors, missing_anchors
 from agentic_dev_loop.core.config import TERMINALS, PipelineConfig, Route, StepConfig, route_target
 from agentic_dev_loop.core.paths import _has_wildcards
 from .deps import extension_message, parse_missing_dependencies, policy_injection
@@ -57,6 +58,7 @@ if TYPE_CHECKING:
 DEFAULT_MAX_ITERATIONS = 500
 DEFAULT_COMMAND_TIMEOUT = 600.0  # seconds - a pytest-class suite budget
 LAST_ERROR = "last-error.md"
+COVERAGE_RETRY_CAP = 3  # per-run brief coverage re-runs before the run fails (041)
 ARTIFACT_CONTEXT_CAP = 24_000  # chars per artifact injected into a step's context
 CUSTOM_PROMPT_HEADING = "Run-specific instructions"
 
@@ -554,6 +556,23 @@ def resolve_brief_inputs(runtime: Runtime, step: StepConfig
     return included, list(step.brief_inputs.env_facts)
 
 
+def _brief_anchors(runtime: Runtime, step: StepConfig) -> list[str]:
+    """The mechanical anchor set for a brief step (041), derived from the
+    resolved ``brief_inputs.include`` files only - plan docs reach dev/review
+    verbatim through the loader channel, so their sections need no anchor
+    enforcement. Duplicate headings across files merge into one anchor."""
+    included, _ = resolve_brief_inputs(runtime, step)
+    anchors: list[str] = []
+    for content in included.values():
+        anchors.extend(extract_anchors(content))
+    return list(dict.fromkeys(anchors))
+
+
+def _coverage_note_text(missing: list[str]) -> str:
+    """The missing-items list for the ``## Coverage retry`` section (041)."""
+    return "\n".join(f"- {item}" for item in missing)
+
+
 def validate_brief_inputs(workspace: Path, step: StepConfig) -> None:
     """Fail fast on ``brief_inputs.include`` entries that name no files (033).
 
@@ -620,13 +639,16 @@ def brief_inputs_hash(runtime: Runtime, step: StepConfig,
 
 def build_brief_context(runtime: Runtime, step: StepConfig,
                         docs: dict[str, str],
-                        doc_sources: dict[str, str] | None = None) -> str:
+                        doc_sources: dict[str, str] | None = None,
+                        coverage_note: str | None = None) -> str:
     """Assemble the brief agent's task message (033): the always-on
     agent-facing error guide (034), the resolved unit/plan docs (re-read from
     disk where sources are known), the closed ``brief_inputs.include`` file
     set, the run-specific instructions appended from ``custom_prompt`` (040),
-    and the env-facts block. Prior verdicts and feedback are deliberately
-    absent - the notes channel delivers them per attempt."""
+    and the env-facts block. A ``coverage_note`` (041) appends a correction
+    request against the digest contract - it is not prior verdicts or
+    feedback, so the 033 rule is unaffected. Prior verdicts and feedback are
+    deliberately absent - the notes channel delivers them per attempt."""
     sections, env_facts = _brief_sections(runtime, step, docs, doc_sources)
     parts = [guide_section()]
     parts += [f"## {name}\n\n{content}" for name, content in sections.items()]
@@ -635,6 +657,13 @@ def build_brief_context(runtime: Runtime, step: StepConfig,
     if env_facts:
         parts.append("## Environment facts\n\n"
                      + "\n".join(f"- {fact}" for fact in env_facts))
+    if coverage_note is not None:
+        parts.append(
+            "## Coverage retry\n\n"
+            "The captured brief is missing the following required items. "
+            "Regenerate the digest so every listed item appears on its own "
+            "line, verbatim where the contract requires verbatim:\n\n"
+            + coverage_note)
     return "\n\n".join(parts)
 
 
@@ -789,7 +818,13 @@ def make_brief_node(runtime: Runtime, step: StepConfig):
     LLM call is skipped entirely. A changed include file or env fact re-runs
     the step and refreshes the hash. Prior verdicts and feedback never enter
     the brief message - they already reach dev/review through the notes
-    channel."""
+    channel.
+
+    The 041 coverage gate runs after every successful capture AND on the reuse
+    path: the four section headings, the include-file anchors, and the env
+    facts must all survive. A miss consumes one per-run retry unit (cap 3) and
+    re-runs the agent with a ``## Coverage retry`` correction note. Exhausting
+    the budget writes last-error.md and fails the run."""
     captures = step.artifact is not None or bool(step.produces)
 
     def node(state: dict) -> dict:
@@ -800,14 +835,9 @@ def make_brief_node(runtime: Runtime, step: StepConfig):
         try:
             current_hash = brief_inputs_hash(runtime, step, state["docs"],
                                              state.get("doc_sources"))
-            if (state.get("artifacts", {}).get(step.name) is not None
-                    and state.get("brief_hashes", {}).get(step.name) == current_hash):
-                print(f"[{subject}] {step.name} brief inputs unchanged - reusing.",
-                      flush=True)
-                merged = {**state["step_verdicts"], step.name: "pass"}
-                return {"step_verdicts": merged, "failed": False}
-            message = build_brief_context(runtime, step, state["docs"],
-                                          state.get("doc_sources"))
+            anchors = _brief_anchors(runtime, step)
+            env_facts = (list(step.brief_inputs.env_facts)
+                         if step.brief_inputs is not None else [])
         except Exception:
             err = redact_values(traceback.format_exc(), runtime.secrets.values())
             print(err[-4000:], file=sys.stderr, flush=True)
@@ -817,6 +847,24 @@ def make_brief_node(runtime: Runtime, step: StepConfig):
                 encoding="utf-8")
             return {"failed": True, "failed_step": step.name}
 
+        existing = state.get("artifacts", {}).get(step.name)
+        reused = (existing is not None
+                  and state.get("brief_hashes", {}).get(step.name) == current_hash)
+
+        if reused and not missing_anchors(existing, anchors, env_facts):
+            print(f"[{subject}] {step.name} brief inputs unchanged - reusing.",
+                  flush=True)
+            merged = {**state["step_verdicts"], step.name: "pass"}
+            return {"step_verdicts": merged, "failed": False}
+
+        coverage_note = None
+        if reused:
+            coverage_note = _coverage_note_text(
+                missing_anchors(existing, anchors, env_facts))
+        message = build_brief_context(runtime, step, state["docs"],
+                                      state.get("doc_sources"),
+                                      coverage_note=coverage_note)
+
         print(f"[{subject}] Running {step.agent} agent...", flush=True)
         result = runtime.run_agent(step.agent, message,
                                     max_iterations=max_iterations, step=step)
@@ -834,11 +882,38 @@ def make_brief_node(runtime: Runtime, step: StepConfig):
                                             result.truncated, max_iterations)],
                     "retry_target": _unclear_target(runtime, step)}
 
+        missing = missing_anchors(result.response or "", anchors, env_facts)
+        if missing:
+            prev_hash = state.get("brief_hashes", {}).get(step.name)
+            retries = (0 if prev_hash != current_hash
+                       else state.get("brief_retries", {}).get(step.name, 0))
+            if retries >= COVERAGE_RETRY_CAP:
+                dropped = "\n".join(f"- {item}" for item in missing)
+                runtime.state_dir.mkdir(parents=True, exist_ok=True)
+                (runtime.state_dir / LAST_ERROR).write_text(
+                    f"# Brief coverage failed\n\n"
+                    f"The brief step repeatedly dropped the following "
+                    f"required items:\n\n{dropped}\n",
+                    encoding="utf-8")
+                print(f"[{subject}] {step.name} brief coverage retries exhausted - "
+                      f"persistent drops: {', '.join(missing)}", flush=True)
+                return {"failed": True, "failed_step": step.name}
+            print(f"[{subject}] {step.name} brief coverage miss on attempt "
+                  f"{attempt}, retrying.", flush=True)
+            merged = {**state["step_verdicts"], step.name: None}
+            update = {"step_verdicts": merged, "retry_target": step.name}
+            if captures and result.response is not None:
+                update["artifacts"] = {step.name: result.response}
+                update["brief_hashes"] = {step.name: current_hash}
+                update["brief_retries"] = {step.name: retries + 1}
+            return update
+
         merged = {**state["step_verdicts"], step.name: "pass"}
         update = {"step_verdicts": merged, "failed": False}
         if captures and result.response is not None:
             update["artifacts"] = {step.name: result.response}
             update["brief_hashes"] = {step.name: current_hash}
+            update["brief_retries"] = {step.name: 0}
         return update
 
     return node

{agentic_dev_loop-1.0.0a38 → agentic_dev_loop-1.0.0a39/src/agentic_dev_loop.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentic-dev-loop
-Version: 1.0.0a38
+Version: 1.0.0a39
 Summary: Turn an LLM into a gated, sandboxed, resumable construction loop over your codebase.
 Author: Luke Wilson
 License-Expression: Apache-2.0
@@ -260,6 +260,18 @@ run start (or when its inputs change), its `produces:` artifact survives attempt
 starts, and the dev/review agents read that digest instead of re-deriving repo
 rules and environment facts every attempt.
 
+The brief digest is mechanically coverage-checked: the four section headings
+(`Repo rules digest`, `Unit scope and lane digest`, `Environment facts`, and
+`Open risks`) must appear, every anchor extracted from the `include` files
+(markdown `##` headings, and YAML category names plus `enforcement_levels`)
+must appear on its own line (case-insensitive, whitespace-collapsed, `**`
+decoration allowed), and every `env_facts` entry must appear verbatim. A miss
+re-runs the brief agent once per missing set with a `## Coverage retry`
+correction note, bounded to three retries per input set; if the same items are
+still dropped after the cap, the run fails and `last-error.md` names the
+persistent drops. Include files with no extractable anchors pass vacuously, and
+unusual YAML rule shapes are under-checked, never over-checked.
+
 ### Secrets (`secrets:`) - refs only, never values
 
 Secret values never belong in the pipeline yaml, the workspace, or `state_dir`.

{agentic_dev_loop-1.0.0a38 → agentic_dev_loop-1.0.0a39}/src/agentic_dev_loop.egg-info/SOURCES.txt

@@ -20,6 +20,7 @@ src/agentic_dev_loop/engine/agent_error_guide.md
 src/agentic_dev_loop/engine/agent_error_guide.py
 src/agentic_dev_loop/engine/agents.py
 src/agentic_dev_loop/engine/allowlist.py
+src/agentic_dev_loop/engine/brief_coverage.py
 src/agentic_dev_loop/engine/cli.py
 src/agentic_dev_loop/engine/deps.py
 src/agentic_dev_loop/engine/dryrun.py
@@ -53,6 +54,7 @@ tests/test_032_stop_when_green.py
 tests/test_033_brief_step.py
 tests/test_035_finalize_nudge.py
 tests/test_036_banned_commands_and_lane_boundary.py
+tests/test_041_brief_coverage.py
 tests/test_actions.py
 tests/test_agent_error_guide.py
 tests/test_agents.py

{agentic_dev_loop-1.0.0a38 → agentic_dev_loop-1.0.0a39}/tests/test_033_brief_step.py

@@ -42,6 +42,15 @@ def _load(tmp_path, data):
     return load_config(p)
 
 
+BRIEF_OK = (
+    "## Repo rules digest\n\nREPO RULES\n\n"
+    "## Unit scope and lane digest\n\nSCOPE\n\n"
+    "## Environment facts\n\n- offline; never fetch\n\n"
+    "## Open risks\n\nNone\n"
+)
+BRIEF_OK_NEW = BRIEF_OK.replace("SCOPE", "SCOPE NEW")
+
+
 BRIEF_STEP = {
     "name": "brief",
     "agent": "brief",
@@ -303,11 +312,11 @@ class TestBriefInputsHash:
 
 class TestBriefNode:
     def test_first_run_calls_agent_and_stores_hash(self, runtime, fake_agents):
-        fake_agents.set("brief", [("write", "attempt-brief.md", "BRIEF BODY")])
+        fake_agents.set("brief", [("write", "attempt-brief.md", BRIEF_OK)])
         update = make_brief_node(runtime, runtime.cfg.steps[0])(make_state())
         assert update["step_verdicts"] == {"brief": "pass"}
         assert update["failed"] is False
-        assert update["artifacts"] == {"brief": "BRIEF BODY"}
+        assert update["artifacts"] == {"brief": BRIEF_OK}
         assert update["brief_hashes"] == {
             "brief": brief_inputs_hash(runtime, runtime.cfg.steps[0],
                                        make_state()["docs"])}
@@ -316,7 +325,7 @@ class TestBriefNode:
         assert "## Environment facts\n\n- offline; never fetch" in msg
 
     def test_unchanged_inputs_skip_llm(self, runtime, fake_agents):
-        fake_agents.set("brief", [("write", "attempt-brief.md", "BRIEF BODY")])
+        fake_agents.set("brief", [("write", "attempt-brief.md", BRIEF_OK)])
         node = make_brief_node(runtime, runtime.cfg.steps[0])
         first = node(make_state())
         second = node(make_state(artifacts=first["artifacts"],
@@ -326,15 +335,15 @@ class TestBriefNode:
 
     def test_changed_inputs_rerun(self, runtime, fake_agents):
         fake_agents.set("brief", [
-            ("write", "attempt-brief.md", "OLD"),
-            ("write", "attempt-brief.md", "NEW"),
+            ("write", "attempt-brief.md", BRIEF_OK),
+            ("write", "attempt-brief.md", BRIEF_OK_NEW),
         ])
         node = make_brief_node(runtime, runtime.cfg.steps[0])
         first = node(make_state())
         (runtime.workspace / "AGENTS.md").write_text("EDITED")
         second = node(make_state(artifacts=first["artifacts"],
                                  brief_hashes=first["brief_hashes"]))
-        assert second["artifacts"] == {"brief": "NEW"}
+        assert second["artifacts"] == {"brief": BRIEF_OK_NEW}
         assert fake_agents.agents_called() == ["brief", "brief"]
 
     def test_loader_doc_disk_edit_reruns_brief(self, runtime, fake_agents,
@@ -342,8 +351,8 @@ class TestBriefNode:
         plan = tmp_path / "plan.md"
         plan.write_text("PLAN V1")
         fake_agents.set("brief", [
-            ("write", "attempt-brief.md", "OLD"),
-            ("write", "attempt-brief.md", "NEW"),
+            ("write", "attempt-brief.md", BRIEF_OK),
+            ("write", "attempt-brief.md", BRIEF_OK_NEW),
         ])
         node = make_brief_node(runtime, runtime.cfg.steps[0])
         first = node(make_state(docs={"plan.md": "PLAN V1"},
@@ -354,7 +363,7 @@ class TestBriefNode:
                                  doc_sources={"plan.md": str(plan)},
                                  artifacts=first["artifacts"],
                                  brief_hashes=first["brief_hashes"]))
-        assert second["artifacts"] == {"brief": "NEW"}
+        assert second["artifacts"] == {"brief": BRIEF_OK_NEW}
         assert fake_agents.agents_called() == ["brief", "brief"]
 
     def test_empty_response_is_unclear(self, runtime, fake_agents):
@@ -569,7 +578,14 @@ class TestBriefPipeline:
         monkeypatch.chdir(repo)
         monkeypatch.setenv("TEST_LLM_KEY", "sk-test")
 
-        fake_agents.set("brief", [("write", "attempt-brief.md", "BRIEF DIGEST")])
+        brief_digest = (
+            "## Repo rules digest\n\nREPO RULES\n\n"
+            "## Unit scope and lane digest\n\nBRIEF DIGEST\n\n"
+            "## Environment facts\n\n"
+            "- the workspace is an export with no .git; verify with find/ls, never git status\n\n"
+            "## Open risks\n\nNone\n"
+        )
+        fake_agents.set("brief", [("write", "attempt-brief.md", brief_digest)])
         fake_agents.set("dev", [("write", "implementation-summary.md", "did the work")])
 
         ok, attempts = run_pipeline("pipeline.yaml", _args())

agentic_dev_loop-1.0.0a39/tests/test_041_brief_coverage.py

@@ -0,0 +1,254 @@
+"""Brief coverage gate (041): anchor extraction and the coverage check over
+the captured brief, plus the brief node's bounded retry and failure path."""
+
+from pathlib import Path
+
+import pytest
+
+from openhands.sdk import LLM
+
+from agentic_dev_loop.core.config import PipelineConfig
+from agentic_dev_loop.engine.brief_coverage import (
+    extract_anchors,
+    missing_anchors,
+    required_sections,
+)
+from agentic_dev_loop.engine.registry import default_registry
+from agentic_dev_loop.engine.stages import (
+    Runtime,
+    brief_inputs_hash,
+    make_brief_node,
+)
+
+ROOT = Path(__file__).resolve().parents[1]
+AGENTS_MD = (ROOT / "AGENTS.md").read_text(encoding="utf-8")
+STANDARDS_YAML = (ROOT / "coding-standards-ddd.yaml").read_text(encoding="utf-8")
+
+
+def _brief_ok() -> str:
+    return (
+        "## Repo rules digest\n\n"
+        "**Error handling**\nNever fall back silently.\n\n"
+        "**Mock policy**\nNo mocks unless unavoidable.\n\n"
+        "## Unit scope and lane digest\n\nunit scope\n\n"
+        "## Environment facts\n\n- offline; never fetch\n\n"
+        "## Open risks\n\nNone\n"
+    )
+
+
+def _brief_missing_mock() -> str:
+    return _brief_ok().replace("**Mock policy**\nNo mocks unless unavoidable.\n\n", "")
+
+
+def _merge_state(state, update):
+    merged = dict(state)
+    for key, value in update.items():
+        if key in ("artifacts", "brief_hashes", "brief_retries"):
+            merged[key] = {**state.get(key, {}), **value}
+        else:
+            merged[key] = value
+    return merged
+
+
+def _make_cfg(steps):
+    return PipelineConfig.model_validate({
+        "name": "t",
+        "llm": {"model": "m", "api_key_env": "K"},
+        "agents_dir": "agents",
+        "lockfiles": ["uv.lock"],
+        "steps": steps,
+    })
+
+
+def _make_state(**over):
+    state = {"subject": "unit u", "docs": {"plan.md": "THE PLAN"},
+             "artifacts": {}, "attempt": 1, "max_attempts": 10, "notes": [],
+             "failed": False, "step_verdicts": {}, "retry_target": None,
+             "thread_id": "t1", "brief_hashes": {}, "brief_retries": {}}
+    state.update(over)
+    return state
+
+
+@pytest.fixture
+def runtime(tmp_path, fake_sandbox):
+    state_dir = tmp_path / ".pr"
+    state_dir.mkdir()
+    (tmp_path / "AGENTS.md").write_text(
+        "## Error handling\n\nNever fall back silently.\n\n"
+        "## Mock policy\n\nNo mocks unless unavoidable.\n")
+    steps = [
+        {"name": "brief", "agent": "brief", "produces": "attempt-brief.md",
+         "max_iterations": 12,
+         "brief_inputs": {"include": ["AGENTS.md"],
+                          "env_facts": ["offline; never fetch"]},
+         "on_pass": "dev"},
+        {"name": "dev", "agent": "dev", "produces": "implementation-summary.md",
+         "on_pass": "success"},
+    ]
+    return Runtime(cfg=_make_cfg(steps), registry=default_registry(),
+                   llm=LLM(model="openai/test-model", api_key="sk-test"),
+                   agents_dir=tmp_path / "agents", state_dir=state_dir,
+                   workspace=tmp_path, sandbox=fake_sandbox)
+
+
+class TestExtractAnchors:
+    def test_required_sections_are_the_four_template_headings(self):
+        assert required_sections() == [
+            "Repo rules digest",
+            "Unit scope and lane digest",
+            "Environment facts",
+            "Open risks",
+        ]
+
+    def test_markdown_headings_from_real_agents_md(self):
+        anchors = extract_anchors(AGENTS_MD)
+        assert anchors == [
+            "default development mode - ask before coding",
+            "slash commands",
+            "github urls",
+            "file search",
+            "group session mode",
+            "error handling",
+            "em dash ban",
+            "consumer name ban",
+            "debugging",
+            "reverse engineering undocumented systems",
+            "development workflow",
+            "backward compatibility",
+            "mock policy",
+            "sdk compat shims",
+        ]
+
+    def test_yaml_categories_and_enforcement_levels_from_real_file(self):
+        anchors = extract_anchors(STANDARDS_YAML)
+        assert anchors == [
+            "enforcement_levels",
+            "general_principles",
+            "architecture_and_boundaries",
+            "domain_and_persistence",
+            "error_handling",
+            "coding_style",
+            "services_are_exceptions",
+            "stack_conventions",
+            "forbidden_patterns",
+        ]
+
+    def test_plain_file_has_no_anchors(self):
+        assert extract_anchors("just prose\nno headings here\n") == []
+
+
+class TestMissingAnchors:
+    def test_all_present_passes(self):
+        assert missing_anchors(_brief_ok(),
+                               ["error handling", "mock policy"],
+                               ["offline; never fetch"]) == []
+
+    def test_missing_anchor_is_named(self):
+        assert "mock policy" in missing_anchors(
+            _brief_missing_mock(), ["error handling", "mock policy"],
+            ["offline; never fetch"])
+
+    def test_missing_section_heading_is_named(self):
+        text = _brief_ok().replace("## Open risks\n\nNone\n", "")
+        assert "Open risks" in missing_anchors(
+            text, ["error handling", "mock policy"], ["offline; never fetch"])
+
+    def test_altered_env_fact_is_named(self):
+        text = _brief_ok().replace("offline; never fetch", "offline maybe")
+        assert "offline; never fetch" in missing_anchors(
+            text, ["error handling", "mock policy"], ["offline; never fetch"])
+
+    def test_mid_line_mention_does_not_satisfy(self):
+        text = _brief_ok().replace(
+            "**Error handling**\nNever fall back silently.\n\n",
+            "See error handling for the rules.\n\n")
+        assert "error handling" in missing_anchors(
+            text, ["error handling", "mock policy"], ["offline; never fetch"])
+
+    def test_case_and_whitespace_variants_pass(self):
+        text = _brief_ok().replace(
+            "**Error handling**", "**  ERROR   HANDLING  **")
+        assert missing_anchors(text, ["error handling", "mock policy"],
+                               ["offline; never fetch"]) == []
+
+    def test_bold_wrapped_heading_passes(self):
+        assert missing_anchors(_brief_ok(), ["error handling", "mock policy"],
+                               ["offline; never fetch"]) == []
+
+
+class TestBriefNodeCoverage:
+    def test_miss_returns_retry_note_and_reruns(self, runtime, fake_agents):
+        good = _brief_ok()
+        bad = _brief_missing_mock()
+        fake_agents.set("brief", [
+            ("write", "attempt-brief.md", bad),
+            ("write", "attempt-brief.md", good),
+        ])
+        node = make_brief_node(runtime, runtime.cfg.steps[0])
+        state = _make_state()
+
+        first = node(state)
+        assert first["step_verdicts"] == {"brief": None}
+        assert first["retry_target"] == "brief"
+        assert first["brief_retries"] == {"brief": 1}
+        assert first["artifacts"] == {"brief": bad}
+        assert first["brief_hashes"] == {
+            "brief": brief_inputs_hash(runtime, runtime.cfg.steps[0],
+                                       state["docs"])}
+
+        second = node(_merge_state(state, first))
+        assert second["step_verdicts"] == {"brief": "pass"}
+        assert second["failed"] is False
+        assert second["artifacts"] == {"brief": good}
+        assert second["brief_retries"] == {"brief": 0}
+        assert fake_agents.agents_called() == ["brief", "brief"]
+        messages = fake_agents.messages_for("brief")
+        assert "## Coverage retry" in messages[1]
+        assert "mock policy" in messages[1]
+
+    def test_cap_exhausted_writes_last_error_and_fails(self, runtime,
+                                                       fake_agents):
+        bad = _brief_missing_mock()
+        fake_agents.set("brief", [("write", "attempt-brief.md", bad)])
+        node = make_brief_node(runtime, runtime.cfg.steps[0])
+        state = _make_state()
+
+        for _ in range(3):
+            update = node(state)
+            assert update.get("failed") is not True
+            state = _merge_state(state, update)
+
+        update = node(state)
+        assert update["failed"] is True
+        assert update["failed_step"] == "brief"
+        assert fake_agents.agents_called() == ["brief", "brief", "brief", "brief"]
+        error = (runtime.state_dir / "last-error.md").read_text(encoding="utf-8")
+        assert "Brief coverage failed" in error
+        assert "mock policy" in error
+
+    def test_reused_digest_failing_coverage_regenerates(self, runtime,
+                                                        fake_agents):
+        good = _brief_ok()
+        bad = _brief_missing_mock()
+        fake_agents.set("brief", [("write", "attempt-brief.md", good)])
+        node = make_brief_node(runtime, runtime.cfg.steps[0])
+        state = _make_state(artifacts={"brief": bad},
+                            brief_hashes={"brief": brief_inputs_hash(
+                                runtime, runtime.cfg.steps[0],
+                                _make_state()["docs"])})
+        update = node(state)
+        assert update["artifacts"] == {"brief": good}
+        assert fake_agents.agents_called() == ["brief"]
+        (message,) = fake_agents.messages_for("brief")
+        assert "## Coverage retry" in message
+
+    def test_passing_reused_digest_skips_llm(self, runtime, fake_agents):
+        good = _brief_ok()
+        node = make_brief_node(runtime, runtime.cfg.steps[0])
+        state = _make_state(artifacts={"brief": good},
+                            brief_hashes={"brief": brief_inputs_hash(
+                                runtime, runtime.cfg.steps[0],
+                                _make_state()["docs"])})
+        update = node(state)
+        assert update == {"step_verdicts": {"brief": "pass"}, "failed": False}
+        assert fake_agents.agents_called() == []

{agentic_dev_loop-1.0.0a38 → agentic_dev_loop-1.0.0a39}/tests/test_e2e_fixtures.py

@@ -62,9 +62,20 @@ def _script_test(*behaviors):
     _COMMAND_QUEUE[:] = list(behaviors)
 
 
+_BRIEF_DIGEST = (
+    "## Repo rules digest\n\n# AGENTS.md\n# coding-standards-ddd.yaml\n\n"
+    "## Unit scope and lane digest\n\nplan scope\n\n"
+    "## Environment facts\n\n"
+    "- the workspace is an export with no .git; verify with find/ls, never git status\n"
+    "- the sandbox is network-off by default; never run package-manager fetches\n"
+    "- Python packages resolve from .venv-sandbox; run .venv-sandbox/bin/python\n\n"
+    "## Open risks\n\nNone\n"
+)
+
+
 def _passing_scripts(fake_agents, **overrides):
     scripts = {
-        "brief": [("write", "attempt-brief.md", "Brief digest.\n")],
+        "brief": [("write", "attempt-brief.md", _BRIEF_DIGEST)],
         "dev": [("write", "implementation-summary.md", "Implemented the fix.\n")],
         "review": [("write", "review-findings.md",
                     "Looks good.\n\nVERDICT: APPROVED\n")],