agentic-dev-loop 1.0.0a48__tar.gz → 1.0.0a49__tar.gz

{agentic_dev_loop-1.0.0a48/src/agentic_dev_loop.egg-info → agentic_dev_loop-1.0.0a49}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentic-dev-loop
-Version: 1.0.0a48
+Version: 1.0.0a49
 Summary: Turn an LLM into a gated, sandboxed, resumable construction loop over your codebase.
 Author: Luke Wilson
 License-Expression: Apache-2.0
@@ -206,10 +206,11 @@ agents_dir: sdk_agents                                  # your <name>.agent.md f
 
 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"] }
+    reasoning_effort: medium
+    brief_inputs:
+      include: [AGENTS.md, coding-standards-ddd.yaml]
+      sections: [Repo rules digest, Unit scope digest, Environment facts, Open risks]
+      env_facts: ["the workspace is an export with no .git; verify with find/ls, never git status"]
     on_pass: dev
 
   - name: dev
@@ -249,9 +250,9 @@ steps:
 
 | Key | Notes |
 | --- | --- |
-| `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)). |
+| `agent:` / `command:` / `action:` / `brief_inputs:` | 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)). `brief_inputs:` is a native brief step - see its row below. |
 | `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>], 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. |
+| `brief_inputs:` | The discriminator for a native brief step: `{ include: [<paths/globs>], env_facts: [<strings>], sections: [<headings>] }`. There is no `agent:`, `produces:`, or `max_iterations:` - the prompt is engine-embedded, the capture file is `attempt-brief.md`, and the iteration cap is 12, all engine-owned. The engine resolves the include list against the workspace, passes the resolved docs + include contents + env facts as the 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). `name` stays free-form, so multiple brief steps are allowed. |
 | `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. |
@@ -294,9 +295,9 @@ Recommended lane defaults (guidance only, not enforced):
 | review | xhigh | shortest lane, highest stakes: a missed detection sails past the last gate into commit |
 
 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.
+run start (or when its inputs change), its engine-owned `attempt-brief.md`
+digest 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 configured
 `brief_inputs.sections` headings must each appear on their own line, every

{agentic_dev_loop-1.0.0a48 → agentic_dev_loop-1.0.0a49}/README.md

@@ -162,10 +162,11 @@ agents_dir: sdk_agents                                  # your <name>.agent.md f
 
 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"] }
+    reasoning_effort: medium
+    brief_inputs:
+      include: [AGENTS.md, coding-standards-ddd.yaml]
+      sections: [Repo rules digest, Unit scope digest, Environment facts, Open risks]
+      env_facts: ["the workspace is an export with no .git; verify with find/ls, never git status"]
     on_pass: dev
 
   - name: dev
@@ -205,9 +206,9 @@ steps:
 
 | Key | Notes |
 | --- | --- |
-| `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)). |
+| `agent:` / `command:` / `action:` / `brief_inputs:` | 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)). `brief_inputs:` is a native brief step - see its row below. |
 | `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>], 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. |
+| `brief_inputs:` | The discriminator for a native brief step: `{ include: [<paths/globs>], env_facts: [<strings>], sections: [<headings>] }`. There is no `agent:`, `produces:`, or `max_iterations:` - the prompt is engine-embedded, the capture file is `attempt-brief.md`, and the iteration cap is 12, all engine-owned. The engine resolves the include list against the workspace, passes the resolved docs + include contents + env facts as the 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). `name` stays free-form, so multiple brief steps are allowed. |
 | `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. |
@@ -250,9 +251,9 @@ Recommended lane defaults (guidance only, not enforced):
 | review | xhigh | shortest lane, highest stakes: a missed detection sails past the last gate into commit |
 
 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.
+run start (or when its inputs change), its engine-owned `attempt-brief.md`
+digest 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 configured
 `brief_inputs.sections` headings must each appear on their own line, every

{agentic_dev_loop-1.0.0a48 → agentic_dev_loop-1.0.0a49}/pyproject.toml

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

@@ -35,6 +35,13 @@ DEFAULT_BRIEF_SECTIONS = [
     "Open risks",
 ]
 
+# 049: a brief step is engine-owned end to end - the capture file and the
+# iteration cap are fixed, not configurable. Downstream consumers (capture
+# write, hygiene, context, retry classification) keep reading `produces` and
+# `max_iterations`; parse-time normalization applies these after validation.
+BRIEF_PRODUCES = ["attempt-brief.md"]
+BRIEF_MAX_ITERATIONS = 12
+
 # 047: the full SDK reasoning_effort literal, passed through verbatim. The
 # engine is provider-generic, so it validates shape only - whether a given
 # provider accepts every value (notably "none") is operator risk (D3).
@@ -372,9 +379,9 @@ class BriefInputsSpec(BaseModel):
 
 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
-    else fails to load. See the `kind` property (the single discriminator
-    graph-building dispatches on)."""
+    `agent`, `action`, `command`, or `brief_inputs` - empty values do not
+    count, anything else fails to load. See the `kind` property (the single
+    discriminator graph-building dispatches on)."""
     model_config = ConfigDict(extra="forbid")
 
     name: str
@@ -413,10 +420,12 @@ class StepConfig(BaseModel):
 
     @property
     def kind(self) -> str:
-        """The step's type: 'agent', 'command', or 'action'. Which of the
-        three keys is set is the ONLY signal; validation has already
+        """The step's type: 'brief', 'agent', 'command', or 'action'. Which
+        of the four keys is set is the ONLY signal; validation has already
         guaranteed exactly one is set and non-empty by the time any instance
         exists."""
+        if self.brief_inputs is not None:
+            return "brief"
         if self.agent is not None:
             return "agent"
         if self.command is not None:
@@ -470,11 +479,48 @@ class StepConfig(BaseModel):
                 raise ValueError(
                     f"step {self.name!r}: {key!r} must be a non-empty string"
                 )
-        if sum(k is not None for k in (self.agent, self.action, self.command)) != 1:
+        if sum(k is not None for k in
+               (self.agent, self.action, self.command, self.brief_inputs)) != 1:
             raise ValueError(
-                f"step {self.name!r}: exactly one of 'agent', 'action', or "
-                "'command' is required"
+                f"step {self.name!r}: exactly one of 'agent', 'action', "
+                "'command', or 'brief_inputs' is required"
             )
+        if self.brief_inputs is not None:
+            if self.produces:
+                raise ValueError(
+                    f"step {self.name!r}: 'brief_inputs' steps write "
+                    f"{BRIEF_PRODUCES[0]!r}; drop 'produces'")
+            if self.artifact is not None:
+                raise ValueError(
+                    f"step {self.name!r}: 'brief_inputs' steps have no "
+                    "verdicts; drop 'artifact'")
+            if self.verdicts is not None:
+                raise ValueError(
+                    f"step {self.name!r}: 'brief_inputs' steps have no "
+                    "verdicts; drop 'verdicts'")
+            if self.params:
+                raise ValueError(
+                    f"step {self.name!r}: 'brief_inputs' steps take no "
+                    "'params'")
+            if self.max_iterations is not None:
+                raise ValueError(
+                    f"step {self.name!r}: 'brief_inputs' steps use the "
+                    f"engine cap ({BRIEF_MAX_ITERATIONS}); drop "
+                    "'max_iterations'")
+            if self.timeout is not None:
+                raise ValueError(
+                    f"step {self.name!r}: 'timeout' is command-only; drop it "
+                    "from a 'brief_inputs' step")
+            if self.custom_prompt is not None:
+                raise ValueError(
+                    f"step {self.name!r}: the brief prompt is engine-owned; "
+                    "drop 'custom_prompt'")
+            if self.finalize_nudge_turns is not None:
+                raise ValueError(
+                    f"step {self.name!r}: 'brief_inputs' steps have no "
+                    "verdicts; drop 'finalize_nudge_turns'")
+            self.produces = list(BRIEF_PRODUCES)
+            self.max_iterations = BRIEF_MAX_ITERATIONS
         if self.command is not None:
             for field, empty in (("artifact", None), ("verdicts", None),
                                  ("produces", []), ("params", {}),
@@ -495,9 +541,11 @@ class StepConfig(BaseModel):
             raise ValueError(
                 f"step {self.name!r}: 'timeout' requires 'command'"
             )
-        if self.terminal_timeout is not None and self.agent is None:
+        if (self.terminal_timeout is not None
+                and self.agent is None and self.brief_inputs is None):
             raise ValueError(
-                f"step {self.name!r}: 'terminal_timeout' requires 'agent'"
+                f"step {self.name!r}: 'terminal_timeout' requires 'agent' or "
+                "'brief_inputs'"
             )
         if self.finalize_nudge_turns is not None and self.agent is None:
             raise ValueError(
@@ -514,37 +562,20 @@ class StepConfig(BaseModel):
                 f"step {self.name!r}: 'finalize_nudge_turns' must be less "
                 "than 'max_iterations'"
             )
-        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.custom_prompt is not None and self.agent is None:
             raise ValueError(
                 f"step {self.name!r}: 'custom_prompt' requires 'agent'"
             )
-        if (self.brief_inputs is not None
-                and (self.artifact is not None or self.verdicts is not None)):
-            raise ValueError(
-                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:
+        if (self.setup is not None and self.command is None
+                and self.agent is None and self.brief_inputs is None):
             raise ValueError(
-                f"step {self.name!r}: 'setup' is only allowed on 'command' or 'agent' steps"
+                f"step {self.name!r}: 'setup' is only allowed on 'command', "
+                "'agent', or 'brief_inputs' 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).
-        # That distinction is enforced once the registry is known - see
-        # `validate_action_network` (020).
         if self.secrets and self.action is not None:
             raise ValueError(
                 f"step {self.name!r}: 'secrets' is only allowed on 'agent' or "

{agentic_dev_loop-1.0.0a48 → agentic_dev_loop-1.0.0a49}/src/agentic_dev_loop/engine/agents.py

@@ -25,6 +25,12 @@ if TYPE_CHECKING:
 
     from .isolation import Sandbox
 
+# 049, D3: the internal brief agent name is a fixed UUID4 string, never the
+# literal "brief", so a consumer vendoring a `brief.agent.md` cannot mint a
+# second AgentDefinition under the same name. The vendored-file warning still
+# keys on the literal filename `brief.agent.md` (that is the file to delete).
+BRIEF_AGENT_NAME = "4f1c9e2b-7a3d-4e5f-8b6c-0d1a2f3c4d5e"
+
 
 def load_agent(agents_dir: Path | str, name: str, llm: LLM) -> "Agent":
     """Load `<agents_dir>/<name>.agent.md` and build the Agent via the SDK

{agentic_dev_loop-1.0.0a48 → agentic_dev_loop-1.0.0a49}/src/agentic_dev_loop/engine/dryrun.py

@@ -27,10 +27,11 @@ 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 brief prompt is engine-embedded (046), so a ``brief_inputs:`` step is
-    exempt from the agents_dir lookup - it never reads a vendored file."""
+    The brief prompt is engine-embedded (046), so a native ``brief_inputs:``
+    step (kind 'brief') has `agent is None` and is exempt from the agents_dir
+    lookup - it never reads a vendored file."""
     for step in cfg.steps:
-        if step.agent is None or step.brief_inputs is not None:
+        if step.agent is None:
             continue
         path = agents_dir / f"{step.agent}.agent.md"
         if not path.is_file():
@@ -79,6 +80,12 @@ def _step_summary(step: StepConfig) -> str:
             parts.append(f"produces={','.join(step.produces)}")
         if step.max_iterations is not None:
             parts.append(f"max_iterations={step.max_iterations}")
+    elif step.kind == "brief":
+        parts = [f"sections={len(step.brief_inputs.sections)}"]
+        if step.produces:
+            parts.append(f"produces={','.join(step.produces)}")
+        if step.max_iterations is not None:
+            parts.append(f"max_iterations={step.max_iterations}")
     elif step.kind == "command":
         parts = [f"command={step.command}"]
         if step.timeout is not None:

{agentic_dev_loop-1.0.0a48 → agentic_dev_loop-1.0.0a49}/src/agentic_dev_loop/engine/graph.py

@@ -93,10 +93,9 @@ def build_graph(runtime: Runtime, checkpointer=None):
     graph = StateGraph(LoopState)
     for step in runtime.cfg.steps:
         if step.kind == "agent":
-            if step.brief_inputs is not None:
-                node = make_brief_node(runtime, step)
-            else:
-                node = make_agent_node(runtime, step)
+            node = make_agent_node(runtime, step)
+        elif step.kind == "brief":
+            node = make_brief_node(runtime, step)
         elif step.kind == "command":
             node = make_command_node(runtime, step)
         else:

{agentic_dev_loop-1.0.0a48 → agentic_dev_loop-1.0.0a49}/src/agentic_dev_loop/engine/stages.py

@@ -32,7 +32,8 @@ from langgraph.graph import END
 from openhands.sdk import Conversation
 
 from .agent_error_guide import guide_section
-from .agents import load_agent, load_brief_agent, register_sandbox_terminal
+from .agents import (BRIEF_AGENT_NAME, 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
@@ -182,7 +183,7 @@ class Runtime:
             if step is not None and step.reasoning_effort is not None:
                 llm = build_llm(self.cfg.llm,
                                 reasoning_effort=step.reasoning_effort)
-            if step is not None and step.brief_inputs is not None:
+            if step is not None and step.kind == "brief":
                 agent = load_brief_agent(
                     agent_name, step.brief_inputs.sections, llm)
             else:
@@ -398,7 +399,7 @@ def build_context(runtime: Runtime, docs: dict[str, str], subject: str,
     parts.append("## Dependency policy\n\n" + policy_injection(runtime.cfg))
     lines = []
     for step in runtime.cfg.steps:
-        if step.agent is None:
+        if step.kind not in ("agent", "brief"):
             continue
         for produced in step.produces:
             lines.append(f"{step.name} agent writes: `{prompt_dir(runtime)}/{produced}`")
@@ -428,7 +429,7 @@ def run_scoped_artifacts(cfg: PipelineConfig) -> list[str]:
     outputs are exempt from per-attempt hygiene."""
     files = []
     for step in cfg.steps:
-        if step.brief_inputs is None:
+        if step.kind != "brief":
             continue
         files.extend(step.produces)
         if step.artifact is not None:
@@ -778,7 +779,7 @@ def _warn_vendored_brief(runtime: Runtime, step: StepConfig) -> None:
     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"
+    vendored = runtime.agents_dir / "brief.agent.md"
     if vendored.is_file():
         print(
             f"[{runtime.cfg.name}] ignoring vendored brief prompt {vendored} - "
@@ -845,8 +846,8 @@ def make_brief_node(runtime: Runtime, step: StepConfig):
                                       state.get("doc_sources"),
                                       coverage_note=coverage_note)
 
-        print(f"[{subject}] Running {step.agent} agent...", flush=True)
-        result = runtime.run_agent(step.agent, message,
+        print(f"[{subject}] Running {step.name} agent...", flush=True)
+        result = runtime.run_agent(BRIEF_AGENT_NAME, message,
                                     max_iterations=max_iterations, step=step)
         if not result.ok:
             print(f"[{subject}] {step.name} agent failed on attempt {attempt}.",
@@ -1125,7 +1126,7 @@ def make_bump_node(runtime: Runtime):
         # 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:
+            if step.kind != "brief":
                 continue
             try:
                 current = brief_inputs_hash(runtime, step,

{agentic_dev_loop-1.0.0a48 → agentic_dev_loop-1.0.0a49/src/agentic_dev_loop.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentic-dev-loop
-Version: 1.0.0a48
+Version: 1.0.0a49
 Summary: Turn an LLM into a gated, sandboxed, resumable construction loop over your codebase.
 Author: Luke Wilson
 License-Expression: Apache-2.0
@@ -206,10 +206,11 @@ agents_dir: sdk_agents                                  # your <name>.agent.md f
 
 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"] }
+    reasoning_effort: medium
+    brief_inputs:
+      include: [AGENTS.md, coding-standards-ddd.yaml]
+      sections: [Repo rules digest, Unit scope digest, Environment facts, Open risks]
+      env_facts: ["the workspace is an export with no .git; verify with find/ls, never git status"]
     on_pass: dev
 
   - name: dev
@@ -249,9 +250,9 @@ steps:
 
 | Key | Notes |
 | --- | --- |
-| `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)). |
+| `agent:` / `command:` / `action:` / `brief_inputs:` | 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)). `brief_inputs:` is a native brief step - see its row below. |
 | `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>], 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. |
+| `brief_inputs:` | The discriminator for a native brief step: `{ include: [<paths/globs>], env_facts: [<strings>], sections: [<headings>] }`. There is no `agent:`, `produces:`, or `max_iterations:` - the prompt is engine-embedded, the capture file is `attempt-brief.md`, and the iteration cap is 12, all engine-owned. The engine resolves the include list against the workspace, passes the resolved docs + include contents + env facts as the 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). `name` stays free-form, so multiple brief steps are allowed. |
 | `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. |
@@ -294,9 +295,9 @@ Recommended lane defaults (guidance only, not enforced):
 | review | xhigh | shortest lane, highest stakes: a missed detection sails past the last gate into commit |
 
 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.
+run start (or when its inputs change), its engine-owned `attempt-brief.md`
+digest 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 configured
 `brief_inputs.sections` headings must each appear on their own line, every