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

{agentic_dev_loop-1.0.0a44/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.0a44
+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,7 +249,7 @@ 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. |
@@ -271,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.0a44 → agentic_dev_loop-1.0.0a45}/README.md

@@ -205,7 +205,7 @@ 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. |
@@ -227,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.0a44 → 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.0a44"
+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.0a44 → 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

{agentic_dev_loop-1.0.0a44 → 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.0a44 → 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.0a44 → 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.0a44 → 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.0a44 → 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.0a44
+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,7 +249,7 @@ 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. |
@@ -271,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.0a44 → agentic_dev_loop-1.0.0a45}/src/agentic_dev_loop.egg-info/SOURCES.txt

@@ -21,6 +21,8 @@ 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/brief_prompt.md
+src/agentic_dev_loop/engine/brief_prompt.py
 src/agentic_dev_loop/engine/cli.py
 src/agentic_dev_loop/engine/containers.py
 src/agentic_dev_loop/engine/deps.py
@@ -55,6 +57,7 @@ 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_046_brief_prompt.py
 tests/test_actions.py
 tests/test_agent_error_guide.py
 tests/test_agents.py

{agentic_dev_loop-1.0.0a44 → agentic_dev_loop-1.0.0a45}/tests/test_033_brief_step.py

@@ -44,7 +44,7 @@ def _load(tmp_path, data):
 
 BRIEF_OK = (
     "## Repo rules digest\n\nREPO RULES\n\n"
-    "## Unit scope and lane digest\n\nSCOPE\n\n"
+    "## Unit scope digest\n\nSCOPE\n\n"
     "## Environment facts\n\n- offline; never fetch\n\n"
     "## Open risks\n\nNone\n"
 )
@@ -167,6 +167,48 @@ class TestBriefInputsConfig:
             _load(tmp_path, data)
 
 
+    def test_sections_default_neutral(self, tmp_path):
+        data = _base()
+        data["steps"] = [BRIEF_STEP, {"name": "dev", "agent": "dev",
+                                      "on_pass": "success"}]
+        brief = _load(tmp_path, data).steps[0]
+        assert brief.brief_inputs.sections == [
+            "Repo rules digest", "Unit scope digest",
+            "Environment facts", "Open risks",
+        ]
+
+    def test_sections_override(self, tmp_path):
+        data = _base()
+        step = dict(BRIEF_STEP)
+        step["brief_inputs"] = {**step["brief_inputs"],
+                                "sections": ["Rules", "Scope", "Risks"]}
+        data["steps"] = [step, {"name": "dev", "agent": "dev",
+                                "on_pass": "success"}]
+        brief = _load(tmp_path, data).steps[0]
+        assert brief.brief_inputs.sections == ["Rules", "Scope", "Risks"]
+
+    def test_sections_empty_rejected(self, tmp_path):
+        data = _base()
+        data["steps"] = [{
+            "name": "brief", "agent": "brief", "produces": "attempt-brief.md",
+            "brief_inputs": {"include": ["AGENTS.md"], "sections": []},
+            "on_pass": "success",
+        }]
+        with pytest.raises(ValidationError, match="non-empty list"):
+            _load(tmp_path, data)
+
+    def test_sections_duplicate_rejected(self, tmp_path):
+        data = _base()
+        data["steps"] = [{
+            "name": "brief", "agent": "brief", "produces": "attempt-brief.md",
+            "brief_inputs": {"include": ["AGENTS.md"],
+                             "sections": ["Rules", "Rules"]},
+            "on_pass": "success",
+        }]
+        with pytest.raises(ValidationError, match="unique"):
+            _load(tmp_path, data)
+
+
 def make_cfg(steps, **over):
     base = {"name": "t", "llm": {"model": "m", "api_key_env": "K"},
             "agents_dir": "agents", "lockfiles": ["uv.lock"], "steps": steps}
@@ -486,8 +528,6 @@ class TestDryRunBriefInputs:
             "    on_pass: success\n")
         agents = repo / "agents"
         agents.mkdir()
-        (agents / "brief.agent.md").write_text(
-            "---\nname: brief\ntools: [terminal]\n---\nYou are brief.\n")
         monkeypatch.chdir(repo)
         from agentic_dev_loop.engine.dryrun import dry_run
         with pytest.raises(FileNotFoundError, match="NO-SUCH.md"):
@@ -513,8 +553,6 @@ class TestDryRunBriefInputs:
             "    on_pass: success\n")
         agents = repo / "agents"
         agents.mkdir()
-        (agents / "brief.agent.md").write_text(
-            "---\nname: brief\ntools: [terminal]\n---\nYou are brief.\n")
         monkeypatch.chdir(repo)
         from agentic_dev_loop.engine.dryrun import dry_run
         assert dry_run("pipeline.yaml",
@@ -580,7 +618,7 @@ class TestBriefPipeline:
 
         brief_digest = (
             "## Repo rules digest\n\nREPO RULES\n\n"
-            "## Unit scope and lane digest\n\nBRIEF DIGEST\n\n"
+            "## Unit scope 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"

{agentic_dev_loop-1.0.0a44 → agentic_dev_loop-1.0.0a45}/tests/test_041_brief_coverage.py

@@ -11,7 +11,6 @@ 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 (
@@ -24,6 +23,8 @@ from agentic_dev_loop.engine.stages import (
 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")
+SECTIONS = ["Repo rules digest", "Unit scope digest",
+            "Environment facts", "Open risks"]
 
 
 def _brief_ok() -> str:
@@ -31,7 +32,7 @@ def _brief_ok() -> str:
         "## 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"
+        "## Unit scope digest\n\nunit scope\n\n"
         "## Environment facts\n\n- offline; never fetch\n\n"
         "## Open risks\n\nNone\n"
     )
@@ -93,13 +94,12 @@ def runtime(tmp_path, 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_required_sections_are_config_driven(self):
+        # 046: the required set is handed in, not read from an engine constant.
+        text = _brief_ok()
+        assert missing_anchors(text, [], [], SECTIONS) == []
+        assert "Renamed section" in missing_anchors(
+            text, [], [], ["Renamed section"])
 
     def test_markdown_headings_from_real_agents_md(self):
         anchors = extract_anchors(AGENTS_MD)
@@ -142,39 +142,42 @@ class TestMissingAnchors:
     def test_all_present_passes(self):
         assert missing_anchors(_brief_ok(),
                                ["error handling", "mock policy"],
-                               ["offline; never fetch"]) == []
+                               ["offline; never fetch"], SECTIONS) == []
 
     def test_missing_anchor_is_named(self):
         assert "mock policy" in missing_anchors(
             _brief_missing_mock(), ["error handling", "mock policy"],
-            ["offline; never fetch"])
+            ["offline; never fetch"], SECTIONS)
 
     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"])
+            text, ["error handling", "mock policy"], ["offline; never fetch"],
+            SECTIONS)
 
     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"])
+            text, ["error handling", "mock policy"], ["offline; never fetch"],
+            SECTIONS)
 
     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"])
+            text, ["error handling", "mock policy"], ["offline; never fetch"],
+            SECTIONS)
 
     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"]) == []
+                               ["offline; never fetch"], SECTIONS) == []
 
     def test_bold_wrapped_heading_passes(self):
         assert missing_anchors(_brief_ok(), ["error handling", "mock policy"],
-                               ["offline; never fetch"]) == []
+                               ["offline; never fetch"], SECTIONS) == []
 
 
 class TestCoverageNoteWording:
@@ -205,6 +208,14 @@ class TestCoverageNoteWording:
 
 
 class TestBriefNodeCoverage:
+    def test_vendored_brief_prompt_warns(self, runtime, capsys):
+        runtime.agents_dir.mkdir(exist_ok=True)
+        (runtime.agents_dir / "brief.agent.md").write_text("vendored\n")
+        make_brief_node(runtime, runtime.cfg.steps[0])
+        err = capsys.readouterr().err
+        assert "ignoring vendored brief prompt" in err
+        assert "embedded prompt is authoritative" in err
+
     def test_miss_returns_retry_note_and_reruns(self, runtime, fake_agents):
         good = _brief_ok()
         bad = _brief_missing_mock()

agentic_dev_loop-1.0.0a45/tests/test_046_brief_prompt.py

@@ -0,0 +1,45 @@
+"""Brief prompt embedding (046): the OUTPUT contract renders from the
+configured section headings, so the prompt and the coverage gate share one
+list and cannot drift apart (the 043 divergence class)."""
+
+from agentic_dev_loop.engine.brief_prompt import (
+    BRIEF_PROMPT_VERSION,
+    load_template,
+    render_brief_prompt,
+)
+
+SECTIONS = ["Repo rules digest", "Unit scope digest",
+            "Environment facts", "Open risks"]
+
+
+class TestRenderBriefPrompt:
+    def test_each_configured_section_is_its_own_heading(self):
+        prompt = render_brief_prompt(SECTIONS)
+        lines = prompt.splitlines()
+        for section in SECTIONS:
+            assert f"## {section}" in lines
+
+    def test_custom_sections_rendered(self):
+        prompt = render_brief_prompt(["Rules", "Scope", "Risks"])
+        lines = prompt.splitlines()
+        assert "## Rules" in lines
+        assert "## Scope" in lines
+        assert "## Risks" in lines
+        assert "## Repo rules digest" not in lines
+
+    def test_warning_lists_configured_names(self):
+        prompt = render_brief_prompt(["Rules", "Scope", "Risks"])
+        assert "`## Rules`" in prompt
+        assert "`## Scope`" in prompt
+        assert "`## Risks`" in prompt
+        assert "Do not shorten or rename them" in prompt
+
+    def test_static_template_loads(self):
+        template = load_template()
+        assert "## WORKFLOW" in template
+        assert "## RULES" in template
+        assert "Do not use em dash characters" in template
+
+    def test_version_is_stable_string(self):
+        assert isinstance(BRIEF_PROMPT_VERSION, str)
+        assert BRIEF_PROMPT_VERSION

{agentic_dev_loop-1.0.0a44 → agentic_dev_loop-1.0.0a45}/tests/test_agents.py

@@ -9,7 +9,7 @@ import pytest
 from openhands.sdk import LLM
 from openhands.sdk.agent.agent import Agent
 
-from agentic_dev_loop.engine.agents import load_agent
+from agentic_dev_loop.engine.agents import load_agent, load_brief_agent
 
 
 @pytest.fixture
@@ -88,6 +88,25 @@ class TestLoadAgent:
         assert agent.filter_tools_regex is None
 
 
+class TestLoadBriefAgent:
+    """The brief agent is engine-embedded (046): no vendored file is read,
+    and the rendered OUTPUT contract is driven by the configured sections."""
+
+    def test_builds_embedded_agent_without_file(self, tmp_path, llm):
+        sections = ["Repo rules digest", "Unit scope digest",
+                    "Environment facts", "Open risks"]
+        agent = load_brief_agent("brief", sections, llm)
+        assert isinstance(agent, Agent)
+        assert [t.name for t in agent.tools] == ["terminal"]
+
+    def test_does_not_read_agents_dir(self, tmp_path, llm):
+        agents_dir = tmp_path / "agents"
+        agents_dir.mkdir()
+        # No brief.agent.md exists; the embedded loader must not look for one.
+        agent = load_brief_agent("brief", ["Repo rules digest"], llm)
+        assert isinstance(agent, Agent)
+
+
 from agentic_dev_loop.engine.isolation import SandboxError
 
 

{agentic_dev_loop-1.0.0a44 → agentic_dev_loop-1.0.0a45}/tests/test_e2e_fixtures.py

@@ -64,7 +64,7 @@ def _script_test(*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"
+    "## Unit scope 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"