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

{agentic_dev_loop-1.0.0a37/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.0a37
+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.0a37 → 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.0a37 → 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.0a37"
+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.0a37 → agentic_dev_loop-1.0.0a39}/src/agentic_dev_loop/core/config.py

@@ -389,6 +389,7 @@ class StepConfig(BaseModel):
     stop_when: StopWhenSpec | None = None  # agent steps only (032)
     finalize_nudge_turns: int | None = Field(default=None, gt=0)  # agent steps only (035)
     brief_inputs: BriefInputsSpec | None = None  # agent steps only (033)
+    custom_prompt: str | None = None  # agent steps only (040); file path resolved at load
     env: dict[str, str | None] | None = None  # NFR-1: null = inherit host value
     setup: str | None = None  # BR-13: command steps only
     forbidden_commands: list[str] = []  # banned-command regex deny-list (036 D1)
@@ -441,6 +442,13 @@ class StepConfig(BaseModel):
                     f"regex: {e}") from e
         return v
 
+    @field_validator("custom_prompt")
+    @classmethod
+    def _nonempty_custom_prompt(cls, v: str | None) -> str | None:
+        if v is not None and not v.strip():
+            raise ValueError("custom_prompt must be a non-empty string")
+        return v
+
     @model_validator(mode="after")
     def _check_shape(self) -> "StepConfig":
         for key in ("agent", "action", "command"):
@@ -501,6 +509,10 @@ class StepConfig(BaseModel):
             raise ValueError(
                 f"step {self.name!r}: 'brief_inputs' requires 'agent'"
             )
+        if self.custom_prompt is not None and self.agent is None:
+            raise ValueError(
+                f"step {self.name!r}: 'custom_prompt' requires 'agent'"
+            )
         if (self.brief_inputs is not None
                 and (self.artifact is not None or self.verdicts is not None)):
             raise ValueError(
@@ -797,6 +809,28 @@ class PipelineConfig(BaseModel):
         return self
 
 
+def _custom_prompt_looks_like_path(value: str) -> bool:
+    """040/D2: a value counts as path-shaped when it carries a path
+    separator or a file extension (a dot). A path-shaped value that names no
+    existing file is a hard error, never silent text."""
+    return "/" in value or "\\" in value or Path(value).suffix != ""
+
+
+def resolve_custom_prompt(value: str, pipeline_dir: Path, step_name: str) -> str:
+    """Resolve a ``custom_prompt`` value (040/D2): an existing file
+    (relative to the pipeline's directory, or absolute) is read as the
+    prompt; any other value is literal text. A path-shaped value that names
+    no file fails loud, naming the path."""
+    candidate = Path(value)
+    path = candidate if candidate.is_absolute() else pipeline_dir / candidate
+    if path.is_file():
+        return path.read_text(encoding="utf-8")
+    if _custom_prompt_looks_like_path(value):
+        raise ValueError(
+            f"step {step_name!r}: 'custom_prompt' file not found: {value}")
+    return value
+
+
 def default_state_dir(pipeline_path: Path) -> str:
     """The new run-state default (Q1): checkpoint DB + last-error.md live OUTSIDE
     the workspace mount, under ~/.agentic-dev-loop/runs/<pipeline-hash>/ where
@@ -816,4 +850,10 @@ def load_config(path: Path) -> PipelineConfig:
         )
     if "state_dir" not in data:
         data["state_dir"] = default_state_dir(path)
-    return PipelineConfig.model_validate(data)
+    cfg = PipelineConfig.model_validate(data)
+    pipeline_dir = path.resolve().parent
+    for step in cfg.steps:
+        if step.custom_prompt is not None:
+            step.custom_prompt = resolve_custom_prompt(
+                step.custom_prompt, pipeline_dir, step.name)
+    return cfg

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.0a37 → 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.0a37 → 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,7 +58,15 @@ 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"
+
+
+def custom_prompt_section(text: str) -> str:
+    """The per-step ``custom_prompt`` section (040): appended verbatim, no
+    rewording, under a fixed heading."""
+    return f"## {CUSTOM_PROMPT_HEADING}\n\n{text}"
 
 
 class _TurnPauseController:
@@ -432,15 +441,19 @@ def _artifact_file(runtime: Runtime, step_name: str) -> str | None:
 
 def build_context(runtime: Runtime, docs: dict[str, str], subject: str,
                   notes: list[str] | None = None,
-                  artifacts: dict[str, str] | None = None) -> str:
+                  artifacts: dict[str, str] | None = None,
+                  custom_prompt: str | None = None) -> str:
     """Assemble the attempt's shared message: the always-on agent-facing error
-    guide (034), subject, doc bundle, the canonical dependency-policy paragraph
-    (021), the expected-output-paths section generated from step defs (a prompt
-    merely naming files lets agents skip them), accumulated stage artifacts
-    (027), and previous-attempt notes."""
+    guide (034), subject, doc bundle, the run-specific instructions appended
+    from the step's ``custom_prompt`` (040), the canonical dependency-policy
+    paragraph (021), the expected-output-paths section generated from step
+    defs (a prompt merely naming files lets agents skip them), accumulated
+    stage artifacts (027), and previous-attempt notes."""
     parts = [f"You are working on {subject}.\n", guide_section()]
     for name, content in docs.items():
         parts.append(f"## {name}\n\n{content}")
+    if custom_prompt:
+        parts.append(custom_prompt_section(custom_prompt))
     if artifacts:
         parts.append("## Stage artifacts")
         for step_name, content in artifacts.items():
@@ -543,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).
 
@@ -609,18 +639,31 @@ 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, and the env-facts block. Prior verdicts and feedback are deliberately
-    absent - the notes channel delivers them per attempt."""
+    set, the run-specific instructions appended from ``custom_prompt`` (040),
+    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()]
+    if step.custom_prompt:
+        parts.append(custom_prompt_section(step.custom_prompt))
     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)
 
 
@@ -683,7 +726,8 @@ def make_agent_node(runtime: Runtime, step: StepConfig):
         max_iterations = step.max_iterations or DEFAULT_MAX_ITERATIONS
         message = build_context(runtime, state["docs"], state["subject"],
                                 state["notes"],
-                                artifacts=state.get("artifacts", {}))
+                                artifacts=state.get("artifacts", {}),
+                                custom_prompt=step.custom_prompt)
         print(f"[{subject}] Running {step.agent} agent...", flush=True)
         result = runtime.run_agent(step.agent, message,
                                     max_iterations=max_iterations, step=step)
@@ -774,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:
@@ -785,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)
@@ -802,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)
@@ -819,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.0a37 → 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.0a37
+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.0a37 → 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.0a37 → 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",
@@ -266,6 +275,18 @@ class TestBuildBriefContext:
         assert ctx.count("## AGENTS.md") == 1
         assert "REPO RULES FROM DOCS" in ctx
 
+    def test_custom_prompt_between_docs_and_env_facts(self, runtime):
+        step = make_cfg([{
+            "name": "brief", "agent": "brief", "produces": "attempt-brief.md",
+            "brief_inputs": {"include": ["AGENTS.md"], "env_facts": ["offline"]},
+            "custom_prompt": "brief scope", "on_pass": "success",
+        }]).steps[0]
+        ctx = build_brief_context(runtime, step, {"plan.md": "THE PLAN"})
+        assert "## Run-specific instructions\n\nbrief scope" in ctx
+        assert ctx.count("## Run-specific instructions") == 1
+        assert ctx.index("## plan.md") < ctx.index("## Run-specific instructions")
+        assert ctx.index("## Run-specific instructions") < ctx.index("## Environment facts")
+
 
 class TestBriefInputsHash:
     def test_stable_and_content_sensitive(self, runtime):
@@ -291,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"])}
@@ -304,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"],
@@ -314,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,
@@ -330,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"},
@@ -342,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):
@@ -557,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())