agentic-dev-loop 1.0.0a43__tar.gz → 1.0.0a45__tar.gz

{agentic_dev_loop-1.0.0a43/src/agentic_dev_loop.egg-info → agentic_dev_loop-1.0.0a45}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentic-dev-loop
-Version: 1.0.0a43
+Version: 1.0.0a45
 Summary: Turn an LLM into a gated, sandboxed, resumable construction loop over your codebase.
 Author: Luke Wilson
 License-Expression: Apache-2.0
@@ -249,12 +249,13 @@ steps:
 | --- | --- |
 | `agent:` / `command:` / `action:` | Exactly one per step. Agents live in `agents_dir` as `<name>.agent.md`; commands run sandboxed (mechanical, never an LLM call). `commit` is the sole host-side built-in action; consumer actions are sandbox-executed, command-shaped scripts (see [Host boundary](#host-boundary-security-model)). |
 | `produces:` / `artifact:` + `verdicts:` | Hygiene-tracked outputs vs verdict-parsed routing. The **last** `VERDICT:` line wins; stale artifacts are deleted at each attempt start. |
-| `brief_inputs:` | Optional agent-step input spec: `{ include: [<paths/globs>], env_facts: [<strings>] }`. The engine resolves the include list against the workspace, passes the resolved docs + include contents + env facts as that step's task message, and regenerates the step only when those inputs change. A produces-only agent step such as `brief` is the documented pattern for per-run context digestion. |
+| `brief_inputs:` | Optional agent-step input spec: `{ include: [<paths/globs>], env_facts: [<strings>], sections: [<headings>] }`. The engine resolves the include list against the workspace, passes the resolved docs + include contents + env facts as that step's task message, and regenerates the step only when those inputs change. `sections` is the ordered list of digest headings the brief must emit (default `[Repo rules digest, Unit scope digest, Environment facts, Open risks]`; non-empty and unique). A produces-only agent step such as `brief` is the documented pattern for per-run context digestion. |
 | `terminal_timeout:` | Optional agent-step per-action timeout in seconds (gt 0). `SandboxTerminalExecutor` uses it when the agent leaves the terminal action timeout unset, overriding the SDK tool's default. `None` = current behavior. |
 | `finalize_nudge_turns:` | Optional agent-step final-response nudge (gt 0). Requires `max_iterations:` and must be less than it. At `max_iterations - finalize_nudge_turns` completed turns the engine injects one advisory turn ("`N turns remain: produce your final response now`"), exactly once; the agent may still exhaust its turns and existing stuck/unclear handling applies unchanged. Absent = current behavior. Provisional pending one consumer run (revert if noisy or the raised cap inflates cost). |
 | `custom_prompt:` | Planned (planning-docs/040). Optional agent-step value: literal text, or a path whose file contents are read at load time, appended verbatim to the agent prompt at context assembly (after the prompt, before the task/artifacts). A value that looks like a path but names no file is a validation error. Agent steps only. |
 | `on_pass:` / `on_fail:` | A step name, terminal `success`/`failure`, or `{goto: X, retry: true}`. No loops happen unless you write them. |
 | `env:` / `setup:` / `network:` | `env:` declares step vars (fixed safe base + declared vars only); `setup:` provisions the sandbox before the step runs (command or agent steps; network ON; stamp-cached, re-runs when the pipeline's lockfiles change); `network: true` lets a command/agent step reach the hosts its `egress:` allowlist names (default off) - see [Per-stage networking](#per-stage-networking). |
+| `setup_probe:` | Optional consumer-authored in-container probe run on a warm `setup:` stamp instead of the venv probe. Exit 0 trusts the stamp (skips); any nonzero re-provisions with network on (fail toward freshness). The probe text is NOT part of the stamp key, so a probe-only change needs `--refresh` or `--clean-stamps` to take effect. Example (asserting a warmed esbuild binary is Linux-shaped): `file frontend-editor/node_modules/esbuild/bin/esbuild | grep -q ELF`. |
 | `mounts:` / `egress:` | Per-step workspace isolation. `mounts:` lists `{path, mode}` entries (`rw`/`ro`, default `ro`) and is **strict-by-default** - empty/missing mounts nothing; only declared-rw paths sync back to the repo. `egress:` is `{class, presets, targets}` (`class: browser` = broad-but-logged; otherwise a strict allowlist). See [Per-stage networking](#per-stage-networking) and [docs/setup.md](docs/setup.md). |
 | `secrets:` (top-level) / step `secrets:` | Declares secret **refs only - never values**; each step opts in to the refs it needs. Resolved host-side and injected into that step's exec env only. See [Secrets](#secrets--refs-only-never-values). |
 | `isolation:` (optional) | Configures the sandbox - image override, resource caps, `allow_git_mutations`, `seccomp_profile`. It can never disable it. See [browser sandbox](docs/browser-sandbox.md). |
@@ -270,12 +271,14 @@ 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
+The brief digest is mechanically coverage-checked: the configured
+`brief_inputs.sections` headings must each appear on their own line, 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. The section list feeds both the
+engine-embedded brief prompt and the coverage gate, so the two can never
+disagree; 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

{agentic_dev_loop-1.0.0a43 → agentic_dev_loop-1.0.0a45}/README.md

@@ -205,12 +205,13 @@ steps:
 | --- | --- |
 | `agent:` / `command:` / `action:` | Exactly one per step. Agents live in `agents_dir` as `<name>.agent.md`; commands run sandboxed (mechanical, never an LLM call). `commit` is the sole host-side built-in action; consumer actions are sandbox-executed, command-shaped scripts (see [Host boundary](#host-boundary-security-model)). |
 | `produces:` / `artifact:` + `verdicts:` | Hygiene-tracked outputs vs verdict-parsed routing. The **last** `VERDICT:` line wins; stale artifacts are deleted at each attempt start. |
-| `brief_inputs:` | Optional agent-step input spec: `{ include: [<paths/globs>], env_facts: [<strings>] }`. The engine resolves the include list against the workspace, passes the resolved docs + include contents + env facts as that step's task message, and regenerates the step only when those inputs change. A produces-only agent step such as `brief` is the documented pattern for per-run context digestion. |
+| `brief_inputs:` | Optional agent-step input spec: `{ include: [<paths/globs>], env_facts: [<strings>], sections: [<headings>] }`. The engine resolves the include list against the workspace, passes the resolved docs + include contents + env facts as that step's task message, and regenerates the step only when those inputs change. `sections` is the ordered list of digest headings the brief must emit (default `[Repo rules digest, Unit scope digest, Environment facts, Open risks]`; non-empty and unique). A produces-only agent step such as `brief` is the documented pattern for per-run context digestion. |
 | `terminal_timeout:` | Optional agent-step per-action timeout in seconds (gt 0). `SandboxTerminalExecutor` uses it when the agent leaves the terminal action timeout unset, overriding the SDK tool's default. `None` = current behavior. |
 | `finalize_nudge_turns:` | Optional agent-step final-response nudge (gt 0). Requires `max_iterations:` and must be less than it. At `max_iterations - finalize_nudge_turns` completed turns the engine injects one advisory turn ("`N turns remain: produce your final response now`"), exactly once; the agent may still exhaust its turns and existing stuck/unclear handling applies unchanged. Absent = current behavior. Provisional pending one consumer run (revert if noisy or the raised cap inflates cost). |
 | `custom_prompt:` | Planned (planning-docs/040). Optional agent-step value: literal text, or a path whose file contents are read at load time, appended verbatim to the agent prompt at context assembly (after the prompt, before the task/artifacts). A value that looks like a path but names no file is a validation error. Agent steps only. |
 | `on_pass:` / `on_fail:` | A step name, terminal `success`/`failure`, or `{goto: X, retry: true}`. No loops happen unless you write them. |
 | `env:` / `setup:` / `network:` | `env:` declares step vars (fixed safe base + declared vars only); `setup:` provisions the sandbox before the step runs (command or agent steps; network ON; stamp-cached, re-runs when the pipeline's lockfiles change); `network: true` lets a command/agent step reach the hosts its `egress:` allowlist names (default off) - see [Per-stage networking](#per-stage-networking). |
+| `setup_probe:` | Optional consumer-authored in-container probe run on a warm `setup:` stamp instead of the venv probe. Exit 0 trusts the stamp (skips); any nonzero re-provisions with network on (fail toward freshness). The probe text is NOT part of the stamp key, so a probe-only change needs `--refresh` or `--clean-stamps` to take effect. Example (asserting a warmed esbuild binary is Linux-shaped): `file frontend-editor/node_modules/esbuild/bin/esbuild | grep -q ELF`. |
 | `mounts:` / `egress:` | Per-step workspace isolation. `mounts:` lists `{path, mode}` entries (`rw`/`ro`, default `ro`) and is **strict-by-default** - empty/missing mounts nothing; only declared-rw paths sync back to the repo. `egress:` is `{class, presets, targets}` (`class: browser` = broad-but-logged; otherwise a strict allowlist). See [Per-stage networking](#per-stage-networking) and [docs/setup.md](docs/setup.md). |
 | `secrets:` (top-level) / step `secrets:` | Declares secret **refs only - never values**; each step opts in to the refs it needs. Resolved host-side and injected into that step's exec env only. See [Secrets](#secrets--refs-only-never-values). |
 | `isolation:` (optional) | Configures the sandbox - image override, resource caps, `allow_git_mutations`, `seccomp_profile`. It can never disable it. See [browser sandbox](docs/browser-sandbox.md). |
@@ -226,12 +227,14 @@ 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
+The brief digest is mechanically coverage-checked: the configured
+`brief_inputs.sections` headings must each appear on their own line, 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. The section list feeds both the
+engine-embedded brief prompt and the coverage gate, so the two can never
+disagree; 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

{agentic_dev_loop-1.0.0a43 → agentic_dev_loop-1.0.0a45}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "agentic-dev-loop"
-version = "1.0.0a43"
+version = "1.0.0a45"
 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.0a43 → agentic_dev_loop-1.0.0a45}/src/agentic_dev_loop/core/config.py

@@ -25,6 +25,16 @@ HOST_ONLY_MOUNT_DIRS = frozenset({".venv"})
 KNOWN_EGRESS_PRESETS = frozenset({"package-registries"})
 EGRESS_CLASSES = frozenset({"allowlist", "browser"})
 
+# The neutral default section headings a brief step must emit (046). A
+# consumer overrides them via `brief_inputs.sections`; the coverage gate
+# and the embedded brief prompt both render from this list.
+DEFAULT_BRIEF_SECTIONS = [
+    "Repo rules digest",
+    "Unit scope digest",
+    "Environment facts",
+    "Open risks",
+]
+
 
 def _validate_mount_path(path: str) -> str:
     """Validate one repo-relative mount path (BR-1.3).
@@ -318,8 +328,9 @@ class BriefInputsSpec(BaseModel):
 
     include: list[str] = []
     env_facts: list[str] = []
+    sections: list[str] = DEFAULT_BRIEF_SECTIONS
 
-    @field_validator("include", "env_facts", mode="before")
+    @field_validator("include", "env_facts", "sections", mode="before")
     @classmethod
     def _coerce_list(cls, v: Any) -> Any:
         return [v] if isinstance(v, str) else v
@@ -338,6 +349,21 @@ class BriefInputsSpec(BaseModel):
                     "brief_inputs.env_facts entries must be non-empty strings")
         return v
 
+    @field_validator("sections")
+    @classmethod
+    def _valid_sections(cls, v: list[str]) -> list[str]:
+        for section in v:
+            if not isinstance(section, str) or not section.strip():
+                raise ValueError(
+                    "brief_inputs.sections entries must be non-empty strings")
+        if not v:
+            raise ValueError(
+                "brief_inputs.sections must be a non-empty list of headings")
+        if len(set(v)) != len(v):
+            raise ValueError(
+                "brief_inputs.sections entries must be unique")
+        return v
+
 
 class StepConfig(BaseModel):
     """One pipeline step. Its type IS the key it carries: exactly one of
@@ -362,6 +388,7 @@ class StepConfig(BaseModel):
     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
+    setup_probe: str | None = None  # 045: consumer probe replacing the venv probe on a warm stamp; requires `setup`; probe text is NOT part of the stamp key (a probe-only change needs --refresh/--clean-stamps)
     forbidden_commands: list[str] = []  # banned-command regex deny-list (036 D1)
     network: bool = False  # per-stage egress (command/agent + sandbox actions; host-side actions reject at registry time)
     # unit-5: per-step mount granularity + egress policy. Empty mounts =
@@ -420,6 +447,13 @@ class StepConfig(BaseModel):
             raise ValueError("custom_prompt must be a non-empty string")
         return v
 
+    @field_validator("setup_probe")
+    @classmethod
+    def _nonempty_setup_probe(cls, v: str | None) -> str | None:
+        if v is not None and not v.strip():
+            raise ValueError("setup_probe must be a non-empty string")
+        return v
+
     @model_validator(mode="after")
     def _check_shape(self) -> "StepConfig":
         for key in ("agent", "action", "command"):
@@ -494,6 +528,10 @@ class StepConfig(BaseModel):
             raise ValueError(
                 f"step {self.name!r}: 'setup' is only allowed on 'command' or 'agent' steps"
             )
+        if self.setup_probe is not None and self.setup is None:
+            raise ValueError(
+                f"step {self.name!r}: 'setup_probe' requires 'setup'"
+            )
         # `network` is NOT rejected here: the schema can't tell a host-side
         # built-in action (e.g. `commit`, which must never take egress) from
         # a sandbox-executed consumer action (which may, like a command step).

{agentic_dev_loop-1.0.0a43 → agentic_dev_loop-1.0.0a45}/src/agentic_dev_loop/engine/agents.py

@@ -16,6 +16,7 @@ from openhands.tools.task_tracker import TaskTrackerTool  # noqa: F401 - registe
 from openhands.tools.terminal import TerminalTool  # noqa: F401 - registers "terminal"
 
 from .forbidden import ForbiddenRule, match_forbidden_command
+from .brief_prompt import render_brief_prompt
 from .isolation import (SandboxError, SandboxExecutionRequest, command_argv,
                         resolve_sandbox_env)
 
@@ -59,6 +60,24 @@ def load_agent(agents_dir: Path | str, name: str, llm: LLM) -> "Agent":
     return agent_definition_to_factory(agent_def)(llm)
 
 
+def load_brief_agent(name: str, sections: list[str], llm: LLM) -> "Agent":
+    """Build the brief agent from the engine-embedded prompt (046).
+
+    The brief prompt is engine-owned and versioned; it is never loaded from
+    ``agents_dir``. The OUTPUT contract's headings are rendered from the
+    configured ``brief_inputs.sections``, so the prompt and the coverage gate
+    share one list and cannot diverge (043)."""
+    from openhands.sdk.subagent.registry import agent_definition_to_factory
+    from openhands.sdk.subagent.schema import AgentDefinition
+
+    agent_def = AgentDefinition(
+        name=name,
+        tools=["terminal"],
+        system_prompt=render_brief_prompt(sections),
+    )
+    return agent_definition_to_factory(agent_def)(llm)
+
+
 class SandboxTerminalExecutor(ToolExecutor):
     """A stateless terminal executor: each action is a fresh ``Sandbox.run``
     (no persistent shell session). ``is_input`` degrades to an unsupported

{agentic_dev_loop-1.0.0a43 → agentic_dev_loop-1.0.0a45}/src/agentic_dev_loop/engine/brief_coverage.py

@@ -12,13 +12,6 @@ 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."""
@@ -38,11 +31,6 @@ def _normalize_line(line: str) -> str:
     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.
 
@@ -75,16 +63,17 @@ def extract_anchors(content: str) -> list[str]:
 
 
 def missing_anchors(brief_text: str, anchors: list[str],
-                    env_facts: list[str]) -> list[str]:
+                    env_facts: list[str], sections: 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."""
+    Required section headings (from the configured ``brief_inputs.sections``)
+    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:
+    for section in sections:
         if _normalize(section) not in lines:
             missing.append(section)
     for anchor in anchors:

agentic_dev_loop-1.0.0a45/src/agentic_dev_loop/engine/brief_prompt.md

@@ -0,0 +1,46 @@
+# Brief Agent
+
+You are the per-run context digester for a gated construction loop. You run
+once per run (or once when the inputs change) and turn a closed input set into
+a compact brief that the dev and review agents reuse on every attempt.
+
+## WORKFLOW
+
+1. Read every input section in the task message below. The inputs are the
+   resolved unit/plan docs, the listed repo-rule files, and the
+   `Environment facts` block. That is the closed list - nothing else.
+2. Digest the inputs into the configured sections named in OUTPUT below.
+   Digest, do not transcribe: the brief is compact working memory, not a copy
+   of the inputs.
+3. State the brief in your final response. The pipeline captures it as
+   `attempt-brief.md`.
+
+## RULES
+
+- One pass, no exploration. Read the listed inputs, emit the brief, finish.
+  Do not explore, do not verify, do not run commands, and do not read anything
+  not listed in the task message. Your inputs are already embedded in the task
+  message; the terminal is available only if a listed input must be re-read.
+- Prior verdicts and feedback are deliberately absent from your inputs. They
+  reach the dev and review agents through a separate notes channel every
+  attempt. Do not invent them and do not re-derive them.
+- The repo-rules digest is structural: one line per top-level section of each
+  repo-rule input. Markdown anchors are the `##` headings: keep each heading
+  verbatim, then compress that section's rules into the one line that follows
+  it. YAML anchors are each `- name:` entry under `categories:` plus the
+  `enforcement_levels` preamble: keep each name verbatim. No top-level section
+  or category may be dropped; merging is allowed only between a section and
+  its own subsections. The anchor line holds the heading and nothing else; the
+  compressed rules go on the following line:
+
+  - general_principles
+    Simplest thing that works; defer decisions to the last responsible moment.
+
+  A line like `general_principles: Simplest thing that works; ...` does not
+  satisfy coverage; the heading must be the only text on its line.
+- Keep the environment-facts entries verbatim: each fact and the behavior it
+  implies travel together.
+- ASCII only. Do not use em dash characters.
+- If the task message carries a `## Coverage retry` section, regenerate the
+  brief so every listed item appears, verbatim where the contract requires
+  verbatim. No exploration: the listed items are the only correction signal.

agentic_dev_loop-1.0.0a45/src/agentic_dev_loop/engine/brief_prompt.py

@@ -0,0 +1,47 @@
+"""Bundled brief-agent prompt (046).
+
+The brief prompt is an engine-owned resource, versioned with the engine so the
+prompt contract and the coverage gate cannot drift (the 043 divergence class).
+The static prose is packaged and read at runtime like the 034 error guide; the
+section-dependent OUTPUT block is rendered here from the configured
+``brief_inputs.sections`` list, so one list feeds the prompt and the gate.
+
+``BRIEF_PROMPT_VERSION`` joins the brief digest hash: an engine upgrade (or a
+sections edit) busts a cached digest and forces a fresh capture.
+"""
+
+from __future__ import annotations
+
+from importlib.resources import files
+
+BRIEF_PROMPT_RESOURCE = "brief_prompt.md"
+BRIEF_PROMPT_VERSION = "1"
+
+
+def load_template() -> str:
+    """The static brief-prompt prose (header, workflow, rules)."""
+    return (files("agentic_dev_loop.engine")
+            .joinpath(BRIEF_PROMPT_RESOURCE)
+            .read_text(encoding="utf-8"))
+
+
+def _output_block(sections: list[str]) -> str:
+    """Render the OUTPUT contract from the configured section headings."""
+    headings = "\n\n".join(f"## {section}" for section in sections)
+    names = ", ".join(f"`## {section}`" for section in sections)
+    return (
+        "## OUTPUT\n\n"
+        "Start your final response with exactly this structure. Each configured "
+        "section heading appears as its own `## ` line, followed by the "
+        "compressed content for that section (write `None` when a section has "
+        "nothing):\n\n"
+        f"{headings}\n\n"
+        f"The section headings must appear exactly as written above: {names}. "
+        "Do not shorten or rename them, and do not merge a section with "
+        "another section."
+    )
+
+
+def render_brief_prompt(sections: list[str]) -> str:
+    """The full brief prompt: static prose plus the section-rendered OUTPUT."""
+    return load_template() + "\n\n" + _output_block(sections)

{agentic_dev_loop-1.0.0a43 → agentic_dev_loop-1.0.0a45}/src/agentic_dev_loop/engine/dryrun.py

@@ -25,12 +25,16 @@ from .secrets import scan_env_files
 
 def _validate_agents(cfg: PipelineConfig, agents_dir: Path) -> None:
     """Every `agent:` step must resolve to an existing file under agents_dir
-    (the same fail-fast `load_agent` enforces at run time)."""
+    (the same fail-fast `load_agent` enforces at run time).
+
+    The brief prompt is engine-embedded (046), so a ``brief_inputs:`` step is
+    exempt from the agents_dir lookup - it never reads a vendored file."""
     for step in cfg.steps:
-        if step.agent is not None:
-            path = agents_dir / f"{step.agent}.agent.md"
-            if not path.is_file():
-                raise FileNotFoundError(f"Agent file not found: {path}")
+        if step.agent is None or step.brief_inputs is not None:
+            continue
+        path = agents_dir / f"{step.agent}.agent.md"
+        if not path.is_file():
+            raise FileNotFoundError(f"Agent file not found: {path}")
 
 
 def _validate_actions(cfg: PipelineConfig, registry: Registry) -> None:

{agentic_dev_loop-1.0.0a43 → agentic_dev_loop-1.0.0a45}/src/agentic_dev_loop/engine/isolation.py

@@ -534,11 +534,19 @@ def venv_probe_command() -> str:
     )
 
 
+def probe_argv(probe_cmd: str, container: str, workspace: str) -> list[str]:
+    """``docker exec`` argv that runs an arbitrary in-container probe command
+    (045) inside the already-running execution container against the
+    bind-mounted workspace. ``probe_cmd`` is a consumer-authored shell command
+    string passed verbatim to ``/bin/sh -c``."""
+    return ["docker", "exec", "-w", workspace, container,
+            "/bin/sh", "-c", probe_cmd]
+
+
 def venv_probe_argv(container: str, workspace: str) -> list[str]:
     """``docker exec`` argv that runs the venv probe inside the (already
     running) execution container against the bind-mounted workspace."""
-    return ["docker", "exec", "-w", workspace, container,
-            "/bin/sh", "-c", venv_probe_command()]
+    return probe_argv(venv_probe_command(), container, workspace)
 
 
 def venv_probe_state(stdout: str, exit_code: int | None) -> str:
@@ -1133,7 +1141,7 @@ class DockerBackend(Sandbox):
                                        self._sync_excludes)
 
     def provision(self, setup_cmd: str, stamp_key: str, stamp_dir: str,
-                  force: bool) -> None:
+                  force: bool, setup_probe: str | None = None) -> None:
         """Run one ``setup:`` hook in the provision container (network ON),
         stamp-cached. Nonzero exit → AE-SBX-009, no stamp written.
 
@@ -1143,13 +1151,21 @@ class DockerBackend(Sandbox):
         broken in the Linux container. A ``broken`` probe removes the venv
         (fail loud if removal is impossible) and falls through to re-provision;
         ``valid``/``missing``/``unknown`` keep the stamp skip.
+
+        045: when ``setup_probe`` is set it replaces the venv probe for this
+        hook. Exit 0 trusts the stamp (skip); any nonzero - a broken artifact
+        or a failed probe run - falls through to re-provision (fail toward
+        freshness).
         """
         if not force and read_stamp(Path(stamp_dir), stamp_key):
-            if self._probe_venv() == "broken":
+            if setup_probe is not None:
+                if self._probe(setup_probe).exit_code == 0:
+                    return
+            else:
+                if self._probe_venv() != "broken":
+                    return
                 remove_sandbox_venv(self._workspace,
                                     sandbox_venv_dir=self._sandbox_venv_dir)
-            else:
-                return
         payload = docker_provision_payload(
             run_id=self._run_id, image=self._image, workspace=self._workspace,
             setup_cmd=setup_cmd, sandbox_venv_dir=self._sandbox_venv_dir,
@@ -1162,13 +1178,18 @@ class DockerBackend(Sandbox):
                 f"- stamp not written (docs/setup.md §5)")
         write_stamp(Path(stamp_dir), stamp_key)
 
+    def _probe(self, probe_cmd: str) -> CmdResult:
+        """Run an arbitrary in-container probe command (045). The workdir
+        follows the export root when one is materialised, else the workspace."""
+        workdir = self._export_root or self._workspace
+        return self._runner.run(
+            probe_argv(probe_cmd, self._container, workdir), timeout=30)
+
     def _probe_venv(self) -> str:
         """Run the in-container venv probe and classify it (016 self-heal).
         With an export the venv is mounted at ``{export}/.venv-sandbox``, so
         the probe workdir follows the export root."""
-        workdir = self._export_root or self._workspace
-        res = self._runner.run(
-            venv_probe_argv(self._container, workdir), timeout=30)
+        res = self._probe(venv_probe_command())
         return venv_probe_state(res.stdout, res.exit_code)
 
     # -- execution ----------------------------------------------------------
@@ -1903,7 +1924,8 @@ def _declared_setups(cfg: PipelineConfig, workspace: Path):
         if step.setup is not None and (
             step.command is not None or step.agent is not None
         ):
-            yield step.setup, setup_stamp_key(step.setup, hashes)
+            yield (step.setup, setup_stamp_key(step.setup, hashes),
+                   step.setup_probe)
 
 
 def isolation_state_dir(cfg: PipelineConfig) -> Path:
@@ -2017,10 +2039,11 @@ def startup_sandbox(cfg: PipelineConfig, *, workspace: Path,
         _announce("execution container started")
         if refresh is None:
             refresh = bool(cfg.isolation and cfg.isolation.refresh)
-        for setup_cmd, stamp_key in _declared_setups(cfg, workspace):
+        for setup_cmd, stamp_key, setup_probe in _declared_setups(cfg, workspace):
             _announce(f"provisioning setup (stamp {stamp_key[:8]})")
             backend.provision(setup_cmd, stamp_key,
-                              str(iso_state_dir / "stamps"), force=refresh)
+                              str(iso_state_dir / "stamps"), force=refresh,
+                              setup_probe=setup_probe)
         _announce("sandbox ready")
         return backend
     except BaseException:

{agentic_dev_loop-1.0.0a43 → agentic_dev_loop-1.0.0a45}/src/agentic_dev_loop/engine/stages.py

@@ -32,8 +32,9 @@ from langgraph.graph import END
 from openhands.sdk import Conversation
 
 from .agent_error_guide import guide_section
-from .agents import load_agent, register_sandbox_terminal
+from .agents import load_agent, load_brief_agent, register_sandbox_terminal
 from .brief_coverage import extract_anchors, missing_anchors
+from .brief_prompt import BRIEF_PROMPT_VERSION
 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
@@ -173,7 +174,11 @@ class Runtime:
                              if step is not None else None),
                     forbidden_commands=forbidden_commands,
                     allowlist=allowlist)
-            agent = load_agent(self.agents_dir, agent_name, self.llm)
+            if step is not None and step.brief_inputs is not None:
+                agent = load_brief_agent(
+                    agent_name, step.brief_inputs.sections, self.llm)
+            else:
+                agent = load_agent(self.agents_dir, agent_name, self.llm)
             callbacks = []
             if finalize_controller is not None:
                 callbacks.append(finalize_controller.on_event)
@@ -543,6 +548,14 @@ def brief_inputs_hash(runtime: Runtime, step: StepConfig,
     brief step, otherwise the existing digest is reused without an LLM call."""
     sections, env_facts = _brief_sections(runtime, step, docs, doc_sources)
     digest = hashlib.sha256()
+    # 046, D6: the embedded prompt version and the configured section headings
+    # join the hash, so an engine upgrade or a sections edit busts the cached
+    # digest and forces a fresh capture.
+    digest.update(BRIEF_PROMPT_VERSION.encode("utf-8"))
+    digest.update(b"\0")
+    for section in step.brief_inputs.sections:
+        digest.update(section.encode("utf-8"))
+        digest.update(b"\0")
     for key in sorted(sections):
         digest.update(key.encode("utf-8"))
         digest.update(b"\0")
@@ -751,6 +764,20 @@ def make_agent_node(runtime: Runtime, step: StepConfig):
     return node
 
 
+def _warn_vendored_brief(runtime: Runtime, step: StepConfig) -> None:
+    """Warn once per load when a vendored brief prompt exists (046, D5).
+
+    The embedded prompt is authoritative, so a leftover
+    ``<agents_dir>/<agent>.agent.md`` for a ``brief_inputs:`` step is ignored;
+    the warning names it without failing the run."""
+    vendored = runtime.agents_dir / f"{step.agent}.agent.md"
+    if vendored.is_file():
+        print(
+            f"[{runtime.cfg.name}] ignoring vendored brief prompt {vendored} - "
+            "the engine-embedded prompt is authoritative",
+            file=sys.stderr, flush=True)
+
+
 def make_brief_node(runtime: Runtime, step: StepConfig):
     """Node closure for a ``brief_inputs:`` agent step (033).
 
@@ -768,6 +795,7 @@ def make_brief_node(runtime: Runtime, step: StepConfig):
     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)
+    _warn_vendored_brief(runtime, step)
 
     def node(state: dict) -> dict:
         attempt = state["attempt"]
@@ -780,6 +808,8 @@ def make_brief_node(runtime: Runtime, step: StepConfig):
             anchors = _brief_anchors(runtime, step)
             env_facts = (list(step.brief_inputs.env_facts)
                          if step.brief_inputs is not None else [])
+            sections = (list(step.brief_inputs.sections)
+                        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)
@@ -793,7 +823,7 @@ def make_brief_node(runtime: Runtime, step: StepConfig):
         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):
+        if reused and not missing_anchors(existing, anchors, env_facts, sections):
             print(f"[{subject}] {step.name} brief inputs unchanged - reusing.",
                   flush=True)
             merged = {**state["step_verdicts"], step.name: "pass"}
@@ -802,7 +832,7 @@ def make_brief_node(runtime: Runtime, step: StepConfig):
         coverage_note = None
         if reused:
             coverage_note = _coverage_note_text(
-                missing_anchors(existing, anchors, env_facts))
+                missing_anchors(existing, anchors, env_facts, sections))
         message = build_brief_context(runtime, step, state["docs"],
                                       state.get("doc_sources"),
                                       coverage_note=coverage_note)
@@ -824,7 +854,7 @@ 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)
+        missing = missing_anchors(result.response or "", anchors, env_facts, sections)
         if missing:
             prev_hash = state.get("brief_hashes", {}).get(step.name)
             retries = (0 if prev_hash != current_hash

{agentic_dev_loop-1.0.0a43 → agentic_dev_loop-1.0.0a45/src/agentic_dev_loop.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentic-dev-loop
-Version: 1.0.0a43
+Version: 1.0.0a45
 Summary: Turn an LLM into a gated, sandboxed, resumable construction loop over your codebase.
 Author: Luke Wilson
 License-Expression: Apache-2.0
@@ -249,12 +249,13 @@ steps:
 | --- | --- |
 | `agent:` / `command:` / `action:` | Exactly one per step. Agents live in `agents_dir` as `<name>.agent.md`; commands run sandboxed (mechanical, never an LLM call). `commit` is the sole host-side built-in action; consumer actions are sandbox-executed, command-shaped scripts (see [Host boundary](#host-boundary-security-model)). |
 | `produces:` / `artifact:` + `verdicts:` | Hygiene-tracked outputs vs verdict-parsed routing. The **last** `VERDICT:` line wins; stale artifacts are deleted at each attempt start. |
-| `brief_inputs:` | Optional agent-step input spec: `{ include: [<paths/globs>], env_facts: [<strings>] }`. The engine resolves the include list against the workspace, passes the resolved docs + include contents + env facts as that step's task message, and regenerates the step only when those inputs change. A produces-only agent step such as `brief` is the documented pattern for per-run context digestion. |
+| `brief_inputs:` | Optional agent-step input spec: `{ include: [<paths/globs>], env_facts: [<strings>], sections: [<headings>] }`. The engine resolves the include list against the workspace, passes the resolved docs + include contents + env facts as that step's task message, and regenerates the step only when those inputs change. `sections` is the ordered list of digest headings the brief must emit (default `[Repo rules digest, Unit scope digest, Environment facts, Open risks]`; non-empty and unique). A produces-only agent step such as `brief` is the documented pattern for per-run context digestion. |
 | `terminal_timeout:` | Optional agent-step per-action timeout in seconds (gt 0). `SandboxTerminalExecutor` uses it when the agent leaves the terminal action timeout unset, overriding the SDK tool's default. `None` = current behavior. |
 | `finalize_nudge_turns:` | Optional agent-step final-response nudge (gt 0). Requires `max_iterations:` and must be less than it. At `max_iterations - finalize_nudge_turns` completed turns the engine injects one advisory turn ("`N turns remain: produce your final response now`"), exactly once; the agent may still exhaust its turns and existing stuck/unclear handling applies unchanged. Absent = current behavior. Provisional pending one consumer run (revert if noisy or the raised cap inflates cost). |
 | `custom_prompt:` | Planned (planning-docs/040). Optional agent-step value: literal text, or a path whose file contents are read at load time, appended verbatim to the agent prompt at context assembly (after the prompt, before the task/artifacts). A value that looks like a path but names no file is a validation error. Agent steps only. |
 | `on_pass:` / `on_fail:` | A step name, terminal `success`/`failure`, or `{goto: X, retry: true}`. No loops happen unless you write them. |
 | `env:` / `setup:` / `network:` | `env:` declares step vars (fixed safe base + declared vars only); `setup:` provisions the sandbox before the step runs (command or agent steps; network ON; stamp-cached, re-runs when the pipeline's lockfiles change); `network: true` lets a command/agent step reach the hosts its `egress:` allowlist names (default off) - see [Per-stage networking](#per-stage-networking). |
+| `setup_probe:` | Optional consumer-authored in-container probe run on a warm `setup:` stamp instead of the venv probe. Exit 0 trusts the stamp (skips); any nonzero re-provisions with network on (fail toward freshness). The probe text is NOT part of the stamp key, so a probe-only change needs `--refresh` or `--clean-stamps` to take effect. Example (asserting a warmed esbuild binary is Linux-shaped): `file frontend-editor/node_modules/esbuild/bin/esbuild | grep -q ELF`. |
 | `mounts:` / `egress:` | Per-step workspace isolation. `mounts:` lists `{path, mode}` entries (`rw`/`ro`, default `ro`) and is **strict-by-default** - empty/missing mounts nothing; only declared-rw paths sync back to the repo. `egress:` is `{class, presets, targets}` (`class: browser` = broad-but-logged; otherwise a strict allowlist). See [Per-stage networking](#per-stage-networking) and [docs/setup.md](docs/setup.md). |
 | `secrets:` (top-level) / step `secrets:` | Declares secret **refs only - never values**; each step opts in to the refs it needs. Resolved host-side and injected into that step's exec env only. See [Secrets](#secrets--refs-only-never-values). |
 | `isolation:` (optional) | Configures the sandbox - image override, resource caps, `allow_git_mutations`, `seccomp_profile`. It can never disable it. See [browser sandbox](docs/browser-sandbox.md). |
@@ -270,12 +271,14 @@ 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
+The brief digest is mechanically coverage-checked: the configured
+`brief_inputs.sections` headings must each appear on their own line, 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. The section list feeds both the
+engine-embedded brief prompt and the coverage gate, so the two can never
+disagree; 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