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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentic-dev-loop
-Version: 1.0.0a29
+Version: 1.0.0a31
 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`.
@@ -528,6 +541,28 @@ dotnet restore --locked-mode      # installs exactly packages.lock.json
 Keep the lockfile tracked (do not gitignore it) and re-run the locked restore
 to prove it holds from a clean cache before setting `deps_policy: locked`.
 
+## Agent-facing error guide
+
+The engine bundles an always-on guide for the engine error codes an agent
+can actually observe while running terminal commands. The guide lives at
+`src/agentic_dev_loop/engine/agent_error_guide.md`, versioned with the engine
+code that emits the codes, and is injected into every agent step's task
+context at assembly time. There is no opt-in and no opt-out in v1; command
+and action steps never receive it because no agent reads them.
+
+Each agent-visible code has exactly one table row, shaped like this:
+
+| Code | Meaning | Correct response |
+| --- | --- | --- |
+| AE-SBX-016 | The loop refused to sync an edit because the real repo changed underneath on a path this workspace also touches; the file in this workspace is stale and its edits will not be applied. | The command is not the problem: retry once, do not edit or work around the named path, and mention the code in your final response if it persists. |
+
+The guide is consumer-agnostic: it explains the general mechanism and never
+names a consumer or a consumer domain rule ID. If an ID must appear inside a
+quoted engine message, the placeholder `<domain-rule-id>` is used. Any engine
+change that adds or changes an agent-visible error code must update the guide
+in the same commit; the test suite enforces the pairing by parsing the
+agent-visible `SandboxError` raise sites against the bundled table.
+
 ## Host boundary (security model)
 
 The orchestrator, tool layer, and the `commit` action run in the **host

{agentic_dev_loop-1.0.0a29 → agentic_dev_loop-1.0.0a31}/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`.
@@ -486,6 +499,28 @@ dotnet restore --locked-mode      # installs exactly packages.lock.json
 Keep the lockfile tracked (do not gitignore it) and re-run the locked restore
 to prove it holds from a clean cache before setting `deps_policy: locked`.
 
+## Agent-facing error guide
+
+The engine bundles an always-on guide for the engine error codes an agent
+can actually observe while running terminal commands. The guide lives at
+`src/agentic_dev_loop/engine/agent_error_guide.md`, versioned with the engine
+code that emits the codes, and is injected into every agent step's task
+context at assembly time. There is no opt-in and no opt-out in v1; command
+and action steps never receive it because no agent reads them.
+
+Each agent-visible code has exactly one table row, shaped like this:
+
+| Code | Meaning | Correct response |
+| --- | --- | --- |
+| AE-SBX-016 | The loop refused to sync an edit because the real repo changed underneath on a path this workspace also touches; the file in this workspace is stale and its edits will not be applied. | The command is not the problem: retry once, do not edit or work around the named path, and mention the code in your final response if it persists. |
+
+The guide is consumer-agnostic: it explains the general mechanism and never
+names a consumer or a consumer domain rule ID. If an ID must appear inside a
+quoted engine message, the placeholder `<domain-rule-id>` is used. Any engine
+change that adds or changes an agent-visible error code must update the guide
+in the same commit; the test suite enforces the pairing by parsing the
+agent-visible `SandboxError` raise sites against the bundled table.
+
 ## Host boundary (security model)
 
 The orchestrator, tool layer, and the `commit` action run in the **host

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "agentic-dev-loop"
-version = "1.0.0a29"
+version = "1.0.0a31"
 description = "Turn an LLM into a gated, sandboxed, resumable construction loop over your codebase."
 readme = "README.md"
 requires-python = ">=3.12"
@@ -68,6 +68,7 @@ where = ["src"]
 
 [tool.setuptools.package-data]
 agentic_dev_loop = ["py.typed"]
+"agentic_dev_loop.engine" = ["*.md"]
 "agentic_dev_loop.engine.seccomp" = ["*.json"]
 
 [tool.pytest.ini_options]

{agentic_dev_loop-1.0.0a29 → agentic_dev_loop-1.0.0a31}/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.0a31/src/agentic_dev_loop/engine/agent_error_guide.md

@@ -0,0 +1,6 @@
+| Code | Meaning | Correct response |
+| --- | --- | --- |
+| AE-SBX-008 | The sandbox refused a git mutation command. Only the single commit step may change git state; agents never commit, branch, tag, or otherwise mutate git. | Do not run the command or any git mutation again. Continue without touching git and leave committing to the commit step. |
+| AE-SBX-010 | The sandbox could not create the execution container for the command, so the command did not run. | The command is not the problem: retry once; if it persists, mention the code in your final response and stop. |
+| AE-SBX-016 | The loop refused to sync an edit because the real repo changed underneath on a path this workspace also touches; the file in this workspace is stale and its edits will not be applied. | The command is not the problem: retry once, do not edit or work around the named path, and mention the code in your final response if it persists. |
+| AE-SBX-018 | The network egress proxy for this step stopped, so the sandbox refused the command rather than run without enforcement. | The command is not the problem: do not retry it, mention the code in your final response, and stop. |

agentic_dev_loop-1.0.0a31/src/agentic_dev_loop/engine/agent_error_guide.py

@@ -0,0 +1,26 @@
+"""Bundled agent-facing error guide (034).
+
+The guide table is an engine-owned resource, versioned with the engine so the
+codes and their guidance cannot drift. Every agent step's task context gets
+the table injected at assembly time; command and action steps never do (no
+agent reads them).
+"""
+
+from __future__ import annotations
+
+from importlib.resources import files
+
+GUIDE_RESOURCE = "agent_error_guide.md"
+GUIDE_HEADING = "Agent-facing error guide"
+
+
+def load_guide() -> str:
+    """The bundled guide table text."""
+    return (files("agentic_dev_loop.engine")
+            .joinpath(GUIDE_RESOURCE)
+            .read_text(encoding="utf-8"))
+
+
+def guide_section() -> str:
+    """The guide block injected into an agent step's task context."""
+    return f"## {GUIDE_HEADING}\n\n{load_guide()}"

{agentic_dev_loop-1.0.0a29 → agentic_dev_loop-1.0.0a31}/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.0a31}/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.0a31}/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.0a31}/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