agentic-dev-loop 1.0.0a29__tar.gz → 1.0.0a30__tar.gz

{agentic_dev_loop-1.0.0a29/src/agentic_dev_loop.egg-info → agentic_dev_loop-1.0.0a30}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentic-dev-loop
-Version: 1.0.0a29
+Version: 1.0.0a30
 Summary: Turn an LLM into a gated, sandboxed, resumable construction loop over your codebase.
 Author: Luke Wilson
 License-Expression: Apache-2.0
@@ -192,6 +192,13 @@ max_attempts: 10                                        # CLI --max-attempts ove
 agents_dir: sdk_agents                                  # your <name>.agent.md files
 
 steps:
+  - name: brief
+    agent: brief
+    produces: attempt-brief.md
+    max_iterations: 12
+    brief_inputs: { include: [AGENTS.md, coding-standards-ddd.yaml], env_facts: ["the workspace is an export with no .git; verify with find/ls, never git status"] }
+    on_pass: dev
+
   - name: dev
     agent: dev
     produces: implementation-summary.md
@@ -229,6 +236,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. |
 | `stop_when:` | Optional agent-step termination: `{ green_command: <argv regex>, post_green_turns: <int, default 2> }`. When the agent's most recent terminal observation matching `green_command` exits 0 and no workspace writes have happened since, the engine injects one nudge turn, allows `post_green_turns` further turns, then closes the conversation. Absent = run to finish. |
 | `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. |
 | `on_pass:` / `on_fail:` | A step name, terminal `success`/`failure`, or `{goto: X, retry: true}`. No loops happen unless you write them. |
@@ -243,6 +251,11 @@ steps:
 | `caches:` / `sync_excludes:` | Top-level run-wide lists. `caches:` names repo-relative toolchain cache dirs bind-mounted rw from the real workspace (auto-created if missing); a `setup:` hook can warm them (the provision container carries the same cache mounts); `sync_excludes:` names scratch paths skipped from both the export copy and sync-back (wildcard `*` spans separators, so `**/bin/**` matches a `/bin/` segment at any depth). Both default to `[]`. See [docs/setup.md](docs/setup.md). |
 | `merge_on_conflict:` | Top-level run-wide list of append-style logs (same path vocabulary as `sync_excludes:`, default `[]`). A concurrent host edit to a listed path is union-merged instead of raising: the host file wins and the sandbox's export-only lines are appended in order; both sides converge and the run continues. See [docs/setup.md](docs/setup.md). |
 
+A `brief_inputs:` step is the per-run context-digestion pattern: it runs once at
+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.
+
 ### Secrets (`secrets:`) - refs only, never values
 
 Secret values never belong in the pipeline yaml, the workspace, or `state_dir`.

{agentic_dev_loop-1.0.0a29 → agentic_dev_loop-1.0.0a30}/README.md

@@ -150,6 +150,13 @@ max_attempts: 10                                        # CLI --max-attempts ove
 agents_dir: sdk_agents                                  # your <name>.agent.md files
 
 steps:
+  - name: brief
+    agent: brief
+    produces: attempt-brief.md
+    max_iterations: 12
+    brief_inputs: { include: [AGENTS.md, coding-standards-ddd.yaml], env_facts: ["the workspace is an export with no .git; verify with find/ls, never git status"] }
+    on_pass: dev
+
   - name: dev
     agent: dev
     produces: implementation-summary.md
@@ -187,6 +194,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. |
 | `stop_when:` | Optional agent-step termination: `{ green_command: <argv regex>, post_green_turns: <int, default 2> }`. When the agent's most recent terminal observation matching `green_command` exits 0 and no workspace writes have happened since, the engine injects one nudge turn, allows `post_green_turns` further turns, then closes the conversation. Absent = run to finish. |
 | `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. |
 | `on_pass:` / `on_fail:` | A step name, terminal `success`/`failure`, or `{goto: X, retry: true}`. No loops happen unless you write them. |
@@ -201,6 +209,11 @@ steps:
 | `caches:` / `sync_excludes:` | Top-level run-wide lists. `caches:` names repo-relative toolchain cache dirs bind-mounted rw from the real workspace (auto-created if missing); a `setup:` hook can warm them (the provision container carries the same cache mounts); `sync_excludes:` names scratch paths skipped from both the export copy and sync-back (wildcard `*` spans separators, so `**/bin/**` matches a `/bin/` segment at any depth). Both default to `[]`. See [docs/setup.md](docs/setup.md). |
 | `merge_on_conflict:` | Top-level run-wide list of append-style logs (same path vocabulary as `sync_excludes:`, default `[]`). A concurrent host edit to a listed path is union-merged instead of raising: the host file wins and the sandbox's export-only lines are appended in order; both sides converge and the run continues. See [docs/setup.md](docs/setup.md). |
 
+A `brief_inputs:` step is the per-run context-digestion pattern: it runs once at
+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.
+
 ### Secrets (`secrets:`) - refs only, never values
 
 Secret values never belong in the pipeline yaml, the workspace, or `state_dir`.

{agentic_dev_loop-1.0.0a29 → agentic_dev_loop-1.0.0a30}/pyproject.toml

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

@@ -335,6 +335,39 @@ class StopWhenSpec(BaseModel):
         return v
 
 
+class BriefInputsSpec(BaseModel):
+    """Optional ``brief_inputs:`` on an agent step (033): the closed input
+    list a brief agent digests once per run. ``include`` is repo-relative
+    paths/globs (wildcards allowed); ``env_facts`` are the stable environment
+    facts handed to the agent verbatim so it never discovers them by running
+    commands. Both accept a single string or a list; unknown keys fail at
+    load."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    include: list[str] = []
+    env_facts: list[str] = []
+
+    @field_validator("include", "env_facts", mode="before")
+    @classmethod
+    def _coerce_list(cls, v: Any) -> Any:
+        return [v] if isinstance(v, str) else v
+
+    @field_validator("include")
+    @classmethod
+    def _valid_include(cls, v: list[str]) -> list[str]:
+        return [_validate_declared_path(p, allow_wildcards=True) for p in v]
+
+    @field_validator("env_facts")
+    @classmethod
+    def _valid_env_facts(cls, v: list[str]) -> list[str]:
+        for fact in v:
+            if not isinstance(fact, str) or not fact.strip():
+                raise ValueError(
+                    "brief_inputs.env_facts entries must be non-empty strings")
+        return v
+
+
 class StepConfig(BaseModel):
     """One pipeline step. Its type IS the key it carries: exactly one of
     `agent`, `action`, or `command` - empty values do not count, anything
@@ -354,6 +387,7 @@ class StepConfig(BaseModel):
     timeout: float | None = Field(default=None, gt=0)  # seconds, command steps only
     terminal_timeout: float | None = Field(default=None, gt=0)  # seconds, agent steps only (032)
     stop_when: StopWhenSpec | None = None  # agent steps only (032)
+    brief_inputs: BriefInputsSpec | None = None  # agent steps only (033)
     env: dict[str, str | None] | None = None  # NFR-1: null = inherit host value
     setup: str | None = None  # BR-13: command steps only
     network: bool = False  # per-stage egress (command/agent + sandbox actions; host-side actions reject at registry time)
@@ -426,6 +460,20 @@ class StepConfig(BaseModel):
             raise ValueError(
                 f"step {self.name!r}: 'stop_when' requires 'agent'"
             )
+        if self.brief_inputs is not None and self.agent is None:
+            raise ValueError(
+                f"step {self.name!r}: 'brief_inputs' requires 'agent'"
+            )
+        if (self.brief_inputs is not None
+                and (self.artifact is not None or self.verdicts is not None)):
+            raise ValueError(
+                f"step {self.name!r}: 'brief_inputs' is only valid on a "
+                "produces-only agent step"
+            )
+        if self.brief_inputs is not None and not self.produces:
+            raise ValueError(
+                f"step {self.name!r}: 'brief_inputs' requires 'produces'"
+            )
         if self.setup is not None and self.command is None and self.agent is None:
             raise ValueError(
                 f"step {self.name!r}: 'setup' is only allowed on 'command' or 'agent' steps"

{agentic_dev_loop-1.0.0a29 → agentic_dev_loop-1.0.0a30}/src/agentic_dev_loop/engine/dryrun.py

@@ -17,6 +17,7 @@ from .hostboundary import check_orchestrator_install, check_tooling_integrity
 from .loaders import resolve_docs
 from .isolation import (isolation_state_dir, resolve_effective_profile,
                         resolve_image_ref, resolved_seccomp_profile)
+from .stages import validate_brief_inputs
 from .registry import (Registry, default_registry, load_extensions,
                        validate_action_mounts_egress, validate_action_network)
 from .secrets import scan_env_files
@@ -137,8 +138,10 @@ def dry_run(cfg_path, args, registry: Registry | None = None) -> int:
     _validate_agents(cfg, base / cfg.agents_dir)
     _validate_actions(cfg, registry)
     resolved_seccomp_profile(cfg)  # fails loud on an unknown bundled:<name>
+    for step in cfg.steps:
+        validate_brief_inputs(Path.cwd(), step)
 
-    loader, docs, subject = resolve_docs(cfg, base, registry, args)
+    loader, docs, subject, _doc_sources = resolve_docs(cfg, base, registry, args)
     image, memory, cpus = _resolved_image(cfg)
     state_dir = isolation_state_dir(cfg)
 

{agentic_dev_loop-1.0.0a29 → agentic_dev_loop-1.0.0a30}/src/agentic_dev_loop/engine/extensions/aidlc.py

@@ -21,8 +21,15 @@ from pathlib import Path
 _DOC_SUFFIXES = (".md", ".yaml", ".yml", ".txt")
 
 
-def resolve_unit_docs(docs_dir: Path | str, unit_slug: str) -> dict[str, str]:
+def resolve_unit_docs_with_sources(
+        docs_dir: Path | str, unit_slug: str
+        ) -> tuple[dict[str, str], dict[str, Path]]:
+    """Resolve one AI-DLC unit into (docs, sources). ``docs`` maps each
+    doc's workspace-relative key to its content; ``sources`` maps the same
+    key to its on-disk file so the brief regeneration gate can re-read it
+    (033 D4)."""
     docs: dict[str, str] = {}
+    sources: dict[str, Path] = {}
     docs_dir = Path(docs_dir)
     unit_slug = unit_slug.strip()
 
@@ -47,6 +54,7 @@ def resolve_unit_docs(docs_dir: Path | str, unit_slug: str) -> dict[str, str]:
         if file.is_file() and file.suffix in _DOC_SUFFIXES:
             key = file.relative_to(unit_dir).as_posix()
             docs[key] = file.read_text(encoding="utf-8")
+            sources[key] = file
 
     # At this point docs holds only unit-dir files - an empty load means the
     # pipeline would build context from inception docs alone (the 2026-07-19
@@ -63,6 +71,7 @@ def resolve_unit_docs(docs_dir: Path | str, unit_slug: str) -> dict[str, str]:
         for file in sorted(inception.iterdir()):
             if file.is_file() and file.suffix in (".md", ".txt"):
                 docs[f"inception/{file.name}"] = file.read_text(encoding="utf-8")
+                sources[f"inception/{file.name}"] = file
 
     # The unit's code-generation plans are the build spec - absent is fine,
     # present is how the spec reaches agents.
@@ -70,7 +79,13 @@ def resolve_unit_docs(docs_dir: Path | str, unit_slug: str) -> dict[str, str]:
     if plans_dir.is_dir():
         for file in sorted(plans_dir.glob(f"{unit_slug}-*-code-generation-plan.md")):
             docs[f"plans/{file.name}"] = file.read_text(encoding="utf-8")
+            sources[f"plans/{file.name}"] = file
+
+    return docs, sources
+
 
+def resolve_unit_docs(docs_dir: Path | str, unit_slug: str) -> dict[str, str]:
+    docs, _ = resolve_unit_docs_with_sources(docs_dir, unit_slug)
     return docs
 
 
@@ -116,6 +131,13 @@ class AidlcDocumentLoader:
         unit = args.aidlc_unit or get_current_unit(self.docs_dir)
         return resolve_unit_docs(self.docs_dir, unit), f"unit {unit}"
 
+    def sources(self, args: argparse.Namespace) -> dict[str, Path]:
+        """Source path for every resolved doc key (033): the regeneration
+        gate re-reads these from disk so a mid-run unit-plan edit is detected."""
+        unit = args.aidlc_unit or get_current_unit(self.docs_dir)
+        _, sources = resolve_unit_docs_with_sources(self.docs_dir, unit)
+        return sources
+
 
 class AidlcExtension:
     name = "ai-dlc"

{agentic_dev_loop-1.0.0a29 → agentic_dev_loop-1.0.0a30}/src/agentic_dev_loop/engine/graph.py

@@ -28,8 +28,9 @@ from .secrets import resolve_secrets, scan_env_files
 from .registry import (Registry, default_registry, load_extensions,
                        validate_action_mounts_egress, validate_action_network)
 from .stages import (Runtime, clear_attempt_artifacts,
-                     make_action_node, make_agent_node, make_bump_node,
-                     make_command_node, make_router, success_node)
+                     make_action_node, make_agent_node, make_brief_node,
+                     make_bump_node, make_command_node, make_router,
+                     success_node)
 
 CHECKPOINT_DB = "loop-checkpoints.sqlite"  # under state_dir, one DB per workspace
 
@@ -47,6 +48,7 @@ class LoopState(TypedDict):
     every other key is last-write-wins."""
     subject: str
     docs: dict[str, str]
+    doc_sources: dict[str, str]        # doc key -> source path (033 regeneration gate)
     artifacts: Annotated[dict[str, str], _merge_artifacts]  # step name -> artifact text
     attempt: int
     max_attempts: int
@@ -61,6 +63,7 @@ class LoopState(TypedDict):
     step_verdicts: dict[str, str | None]  # per-step pass/fail/None(unclear)
     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)
 
 
 def build_graph(runtime: Runtime, checkpointer=None):
@@ -83,7 +86,10 @@ def build_graph(runtime: Runtime, checkpointer=None):
     graph = StateGraph(LoopState)
     for step in runtime.cfg.steps:
         if step.kind == "agent":
-            node = make_agent_node(runtime, step)
+            if step.brief_inputs is not None:
+                node = make_brief_node(runtime, step)
+            else:
+                node = make_agent_node(runtime, step)
         elif step.kind == "command":
             node = make_command_node(runtime, step)
         else:
@@ -178,14 +184,15 @@ def _run_pipeline(cfg, base, registry, state_dir, max_attempts, args, viz_bus,
     if resume:
         initial = None  # state (docs/subject/artifacts) comes from the checkpoint
     else:
-        _loader, docs, subject = resolve_docs(cfg, base, registry, args)
+        _loader, docs, subject, doc_sources = resolve_docs(cfg, base, registry, args)
         # A fresh run owns state_dir: drop cross-run leftovers (a previous
         # failure's last-error.md, stale artifacts) so nothing mistakes
         # them for this run's output. --resume keeps them.
-        clear_attempt_artifacts(runtime)
+        clear_attempt_artifacts(runtime, exempt_run_scoped=False)
         initial: LoopState = {
             "subject": subject,
             "docs": docs,
+            "doc_sources": doc_sources,
             "artifacts": {},
             "attempt": 1,
             "max_attempts": max_attempts,
@@ -204,6 +211,7 @@ def _run_pipeline(cfg, base, registry, state_dir, max_attempts, args, viz_bus,
             "step_verdicts": {},
             "retry_target": None,
             "thread_id": thread_id,
+            "brief_hashes": {},
         }
     bus = viz_bus
     with SqliteSaver.from_conn_string(db) as saver:

{agentic_dev_loop-1.0.0a29 → agentic_dev_loop-1.0.0a30}/src/agentic_dev_loop/engine/loaders.py

@@ -71,6 +71,12 @@ class PlanDocumentLoader:
         docs = resolve_plan_docs(args.plan)
         return docs, f"plan {args.plan.name}"
 
+    def sources(self, args: argparse.Namespace) -> dict[str, Path]:
+        """Source path for every resolved doc key (033): the regeneration
+        gate re-reads these from disk so a mid-run plan edit is detected."""
+        path = Path(args.plan)
+        return {path.name: path}
+
 
 def select_loader(registry: Registry, args: argparse.Namespace) -> DocumentLoader | None:
     """The document-loader coexistence model - load many, invoke one:
@@ -103,11 +109,15 @@ def select_loader(registry: Registry, args: argparse.Namespace) -> DocumentLoade
 
 
 def resolve_docs(cfg: PipelineConfig, base: Path, registry: Registry,
-                 args) -> tuple[DocumentLoader | None, dict[str, str], str]:
+                 args) -> tuple[DocumentLoader | None, dict[str, str], str,
+                                dict[str, str]]:
     """Select and invoke the document loader, then append the pipeline's
     additional_files (resolved relative to the pipeline file's dir;
-    listed-but-missing fails fast). Returns (loader, docs, subject)."""
+    listed-but-missing fails fast). Returns (loader, docs, subject,
+    doc_sources) - the source path for every loader/additional_files doc key
+    so the brief regeneration gate can re-read them from disk (033 D4)."""
     loader = select_loader(registry, args)
+    sources: dict[str, str] = {}
     if loader is not None:
         docs, subject = loader.resolve(args)
         if not docs:
@@ -116,6 +126,10 @@ def resolve_docs(cfg: PipelineConfig, base: Path, registry: Registry,
             raise RuntimeError(
                 f"Document loader {loader.name!r} returned no docs - "
                 "refusing to build context from nothing")
+        loader_sources = getattr(loader, "sources", None)
+        if callable(loader_sources):
+            for name, path in loader_sources(args).items():
+                sources[name] = str(Path(path).resolve())
     else:
         docs, subject = {}, cfg.name
     for rel in cfg.additional_files:
@@ -123,4 +137,5 @@ def resolve_docs(cfg: PipelineConfig, base: Path, registry: Registry,
         if not path.is_file():
             raise FileNotFoundError(f"additional_files entry not found: {path}")
         docs[path.name] = path.read_text(encoding="utf-8")
-    return loader, docs, subject
+        sources[path.name] = str(path.resolve())
+    return loader, docs, subject, sources

{agentic_dev_loop-1.0.0a29 → agentic_dev_loop-1.0.0a30}/src/agentic_dev_loop/engine/stages.py

@@ -19,6 +19,7 @@ pipeline config; the fixed policies stay here, not in config:
 
 from __future__ import annotations
 
+import hashlib
 import os
 import re
 import subprocess
@@ -33,6 +34,7 @@ from openhands.sdk import Conversation
 
 from .agents import load_agent, register_sandbox_terminal
 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
 from .egress_policy import assemble_egress_policy
 from .isolation import SandboxExecutionRequest, command_argv, resolve_sandbox_env
@@ -406,14 +408,152 @@ def declared_artifacts(cfg: PipelineConfig) -> list[str]:
     return files
 
 
-def clear_attempt_artifacts(runtime: Runtime) -> None:
+def run_scoped_artifacts(cfg: PipelineConfig) -> list[str]:
+    """Artifacts that live for the whole run, not one attempt (033).
+
+    A ``brief_inputs:`` step is the documented pattern: its digest is
+    created once at run start and reused by every attempt, so its declared
+    outputs are exempt from per-attempt hygiene."""
+    files = []
+    for step in cfg.steps:
+        if step.brief_inputs is None:
+            continue
+        files.extend(step.produces)
+        if step.artifact is not None:
+            files.append(step.artifact)
+    return files
+
+
+def clear_attempt_artifacts(runtime: Runtime, *,
+                            exempt_run_scoped: bool = True) -> None:
     """Per-attempt hygiene (fixed policy): delete every declared
     artifact/produces file + last-error.md so stale files from earlier
-    attempts or runs can't be mistaken for this attempt's output."""
+    attempts or runs can't be mistaken for this attempt's output.
+
+    Run-scoped artifacts (033) survive attempt starts and are deleted at run
+    start instead - pass ``exempt_run_scoped=False`` for that run-start sweep.
+    """
+    keep = set(run_scoped_artifacts(runtime.cfg)) if exempt_run_scoped else set()
     for name in [*declared_artifacts(runtime.cfg), LAST_ERROR]:
+        if name in keep:
+            continue
         (runtime.state_dir / name).unlink(missing_ok=True)
 
 
+def _resolve_include_spec(workspace: Path, spec: str) -> list[Path]:
+    """Resolve one ``brief_inputs.include`` entry to files, sorted by their
+    workspace-relative posix path. Literal entries must name an existing file;
+    wildcard entries must match at least one file (no silent fallback)."""
+    if _has_wildcards(spec):
+        matches = sorted(
+            (p for p in workspace.glob(spec) if p.is_file()),
+            key=lambda p: p.relative_to(workspace).as_posix())
+    else:
+        path = workspace / spec
+        if not path.is_file():
+            raise FileNotFoundError(
+                f"brief_inputs include entry not found: {spec}")
+        matches = [path]
+    if not matches:
+        raise FileNotFoundError(
+            f"brief_inputs include entry matched no files: {spec}")
+    return matches
+
+
+def resolve_brief_inputs(runtime: Runtime, step: StepConfig
+                         ) -> tuple[dict[str, str], list[str]]:
+    """Resolve ``brief_inputs.include`` against the workspace into
+    ``{workspace-relative-path: content}`` and return the env-facts list."""
+    if step.brief_inputs is None:
+        return {}, []
+    included: dict[str, str] = {}
+    for spec in step.brief_inputs.include:
+        for path in _resolve_include_spec(runtime.workspace, spec):
+            key = path.relative_to(runtime.workspace).as_posix()
+            included.setdefault(key, path.read_text(encoding="utf-8"))
+    return included, list(step.brief_inputs.env_facts)
+
+
+def validate_brief_inputs(workspace: Path, step: StepConfig) -> None:
+    """Fail fast on ``brief_inputs.include`` entries that name no files (033).
+
+    The no-silent-fallback rule demands these surface at load/--dry-run time,
+    not on the brief step's first run."""
+    if step.brief_inputs is None:
+        return
+    for spec in step.brief_inputs.include:
+        _resolve_include_spec(workspace, spec)
+
+
+def _resolved_loader_docs(docs: dict[str, str] | None,
+                          doc_sources: dict[str, str] | None) -> dict[str, str]:
+    """The loader/`additional_files` docs for the brief hash and message.
+
+    When source paths are known (033 D4), re-read them from disk so a
+    mid-run edit to the unit plan or an additional file changes the hash -
+    the run-start snapshot alone would miss it. Doc keys without a tracked
+    source keep their snapshot content (third-party loaders)."""
+    if not doc_sources:
+        return dict(docs or {})
+    resolved = dict(docs or {})
+    for name, source in doc_sources.items():
+        resolved[name] = Path(source).read_text(encoding="utf-8")
+    return resolved
+
+
+def _brief_sections(runtime: Runtime, step: StepConfig,
+                    docs: dict[str, str] | None,
+                    doc_sources: dict[str, str] | None = None
+                    ) -> tuple[dict[str, str], list[str]]:
+    """The brief's full resolved input set: the loader docs (unit plan,
+    additional_files) re-read from disk where their sources are known, merged
+    with the closed include-file set, plus the env-facts list. Duplicate
+    names are de-duplicated; the loader doc already carries that input, so
+    the include copy is not repeated."""
+    sections: dict[str, str] = {}
+    for name, content in _resolved_loader_docs(docs, doc_sources).items():
+        sections.setdefault(name, content)
+    included, env_facts = resolve_brief_inputs(runtime, step)
+    for name, content in included.items():
+        sections.setdefault(name, content)
+    return sections, env_facts
+
+
+def brief_inputs_hash(runtime: Runtime, step: StepConfig,
+                      docs: dict[str, str] | None = None,
+                      doc_sources: dict[str, str] | None = None) -> str:
+    """Hash the resolved brief inputs (033): loader docs + include-file
+    contents + env facts. Used by the regeneration gate - a change re-runs the
+    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()
+    for key in sorted(sections):
+        digest.update(key.encode("utf-8"))
+        digest.update(b"\0")
+        digest.update(sections[key].encode("utf-8"))
+        digest.update(b"\0")
+    for fact in env_facts:
+        digest.update(fact.encode("utf-8"))
+        digest.update(b"\0")
+    return digest.hexdigest()
+
+
+def build_brief_context(runtime: Runtime, step: StepConfig,
+                        docs: dict[str, str],
+                        doc_sources: dict[str, str] | None = None) -> str:
+    """Assemble the brief agent's task message (033): 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."""
+    sections, env_facts = _brief_sections(runtime, step, docs, doc_sources)
+    parts = [f"## {name}\n\n{content}" for name, content in sections.items()]
+    if env_facts:
+        parts.append("## Environment facts\n\n"
+                     + "\n".join(f"- {fact}" for fact in env_facts))
+    return "\n\n".join(parts)
+
+
 def _unclear_target(runtime: Runtime, step: StepConfig) -> str:
     """Where the unclear-verdict retry loops to: on_fail's goto when that is
     a step, else the entry step (the consumer always looped back to dev)."""
@@ -555,6 +695,70 @@ def make_agent_node(runtime: Runtime, step: StepConfig):
     return node
 
 
+def make_brief_node(runtime: Runtime, step: StepConfig):
+    """Node closure for a ``brief_inputs:`` agent step (033).
+
+    The brief is an ordinary capture-applying agent step with one extra rule:
+    it runs once per input set. The resolved inputs are hashed when the brief
+    is written; on re-entry with an unchanged hash and an existing digest the
+    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."""
+    captures = step.artifact is not None or bool(step.produces)
+
+    def node(state: dict) -> dict:
+        attempt = state["attempt"]
+        subject = state["subject"]
+        max_iterations = step.max_iterations or DEFAULT_MAX_ITERATIONS
+
+        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"))
+        except Exception:
+            err = redact_values(traceback.format_exc(), runtime.secrets.values())
+            print(err[-4000:], file=sys.stderr, flush=True)
+            runtime.state_dir.mkdir(parents=True, exist_ok=True)
+            (runtime.state_dir / LAST_ERROR).write_text(
+                f"# Brief step failed\n\n```\n{err[-4000:]}\n```\n",
+                encoding="utf-8")
+            return {"failed": True, "failed_step": step.name}
+
+        print(f"[{subject}] Running {step.agent} agent...", flush=True)
+        result = runtime.run_agent(step.agent, message,
+                                    max_iterations=max_iterations, step=step)
+        if not result.ok:
+            print(f"[{subject}] {step.name} agent failed on attempt {attempt}.",
+                  flush=True)
+            return {"failed": True, "failed_step": step.name}
+
+        if result.capture_error is not None:
+            print(f"[{subject}] {step.name} agent produced no final response on "
+                  f"attempt {attempt}, retrying.", flush=True)
+            merged = {**state["step_verdicts"], step.name: None}
+            return {"step_verdicts": merged,
+                    "notes": [_unclear_note(runtime, step, attempt, None,
+                                            result.truncated, max_iterations)],
+                    "retry_target": _unclear_target(runtime, step)}
+
+        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}
+        return update
+
+    return node
+
+
 def make_command_node(runtime: Runtime, step: StepConfig):
     """Node closure for a mechanical command step. The exit code is the sole
     verdict: 0 ⇒ pass, anything else (nonzero, signal-killed, not-found, or
@@ -748,9 +952,27 @@ def make_bump_node(runtime: Runtime):
 
     def node(state: dict) -> dict:
         clear_attempt_artifacts(runtime)
-        return {"attempt": state["attempt"] + 1,
-                "step_verdicts": {},
-                "failed": False}
+        update = {"attempt": state["attempt"] + 1,
+                  "step_verdicts": {},
+                  "failed": False}
+        # 033 regeneration gate: if a brief step's resolved inputs changed
+        # since it was written (a mid-run edit to AGENTS.md or the unit plan),
+        # re-enter that brief step so it regenerates once and refreshes its
+        # hash. Unchanged inputs keep the failing step's retry_target.
+        for step in runtime.cfg.steps:
+            if step.brief_inputs is None:
+                continue
+            try:
+                current = brief_inputs_hash(runtime, step,
+                                            state.get("docs", {}),
+                                            state.get("doc_sources"))
+            except Exception:
+                update["retry_target"] = step.name
+                break
+            if state.get("brief_hashes", {}).get(step.name) != current:
+                update["retry_target"] = step.name
+                break
+        return update
 
     return node