atomicguard 2.26.1__tar.gz → 2.28.0__tar.gz

{atomicguard-2.26.1/src/atomicguard.egg-info → atomicguard-2.28.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: atomicguard
-Version: 2.26.1
+Version: 2.28.0
 Summary: A Dual-State Agent Framework for reliable LLM code generation with guard-validated loops
 Author-email: Matthew Thompson <thompsonson@gmail.com>
 Maintainer-email: Matthew Thompson <thompsonson@gmail.com>
@@ -31,6 +31,7 @@ Requires-Dist: openhands-ai>=0.27.0
 Requires-Dist: pydantic-ai>=1.0.0
 Requires-Dist: pyflakes>=3.0
 Requires-Dist: click>=8.1.0
+Requires-Dist: pyyaml>=6.0
 Provides-Extra: web
 Requires-Dist: fastapi>=0.115.0; extra == "web"
 Requires-Dist: uvicorn[standard]>=0.34.0; extra == "web"

{atomicguard-2.26.1 → atomicguard-2.28.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "atomicguard"
-version = "2.26.1"
+version = "2.28.0"
 description = "A Dual-State Agent Framework for reliable LLM code generation with guard-validated loops"
 readme = "README.md"
 license = { text = "MIT" }
@@ -40,6 +40,7 @@ dependencies = [
     "pydantic-ai>=1.0.0",
     "pyflakes>=3.0",
     "click>=8.1.0",
+    "pyyaml>=6.0",
 ]
 
 [project.urls]
@@ -180,6 +181,9 @@ ignore = [
 ]
 
 [tool.ruff.lint.per-file-ignores]
+# Vendored Raschka source — keep the diff minimal; don't lint upstream's
+# unused params or other style choices we don't own.
+"agents/double_oh_seven/agent.py" = ["ARG001", "ARG002", "ARG003"]
 # Concrete reward functions must match RewardFunctionInterface.compute()
 # signature — unused params are required by the interface contract.
 "src/atomicguard/infrastructure/rl/rewards.py" = ["ARG002"]
@@ -227,6 +231,14 @@ mypy_path = "src"
 module = "tests.*"
 disallow_untyped_defs = false
 
+[[tool.mypy.overrides]]
+module = "atomicguard.contrib.switchboard.tests.*"
+ignore_errors = true
+
+[[tool.mypy.overrides]]
+module = "atomicguard.contrib.switchboard.examples.*"
+ignore_errors = true
+
 [[tool.mypy.overrides]]
 module = ["atomicguard.web.*", "atomicguard.web.routes.*"]
 warn_return_any = false
@@ -236,6 +248,15 @@ disallow_untyped_defs = false
 module = ["examples.*"]
 ignore_errors = true
 
+[[tool.mypy.overrides]]
+# Vendored Raschka source — don't typecheck upstream code we don't own.
+module = "agents.double_oh_seven.agent"
+ignore_errors = true
+
+[[tool.mypy.overrides]]
+module = "agents.double_oh_seven.tests.*"
+ignore_errors = true
+
 [dependency-groups]
 dev = [
     "mypy>=1.19.1",

{atomicguard-2.26.1 → atomicguard-2.28.0}/src/atomicguard/__init__.py

@@ -82,7 +82,7 @@ from atomicguard.infrastructure.persistence import (
 # Visualization
 from atomicguard.visualization import export_workflow_config_html, export_workflow_html
 
-__version__ = "2.26.1"
+__version__ = "2.28.0"
 
 __all__ = [
     # Version

{atomicguard-2.26.1 → atomicguard-2.28.0}/src/atomicguard/application/agent.py

@@ -335,6 +335,7 @@ class DualStateAgent:
             escalation_feedback=escalation_feedback,
             dependency_types=dep_types,
             dependency_artifact_contexts=dep_contexts,
+            workflow_id=self._workflow_id,
         )
 
     def _refine_context(
@@ -371,4 +372,5 @@ class DualStateAgent:
             escalation_feedback=escalation_feedback,
             dependency_types=dep_types,
             dependency_artifact_contexts=dep_contexts,
+            workflow_id=self._workflow_id,
         )

{atomicguard-2.26.1 → atomicguard-2.28.0}/src/atomicguard/application/builder.py

@@ -8,15 +8,26 @@ adapter-agnostic factory that takes explicit registries.
 from __future__ import annotations
 
 import logging
+import re
 from typing import TYPE_CHECKING
 
 from atomicguard.application.action_pair import ActionPair
-from atomicguard.application.workflow import StepCallback, WorkflowOrchestrator
+from atomicguard.application.workflow import (
+    PreStepCallback,
+    StepCallback,
+    WorkflowOrchestrator,
+)
 from atomicguard.domain.prompts import PromptTemplate
 from atomicguard.guards.composite import CompositeGuard
 
+# Matches `{dep.<ap_id>.<field>}` placeholders in task / feedback / context
+# strings. Used at orchestrator-build time to validate that every referenced
+# producer AP is declared in `requires` — catches cross-AP coupling bugs
+# before runtime instead of as a misleading KeyError mid-execution.
+_DEP_PLACEHOLDER_RE = re.compile(r"\{dep\.(\w+)\.\w+\}")
+
 if TYPE_CHECKING:
-    from atomicguard.application.workflow import StepCallback
+    from atomicguard.application.workflow import PreStepCallback, StepCallback
     from atomicguard.domain.interfaces import (
         ArtifactDAGInterface,
         EffectorInterface,
@@ -40,6 +51,7 @@ def build_orchestrator(
     artifact_dag: ArtifactDAGInterface,
     step_callback: StepCallback | None = None,
     effector_registry: dict[str, EffectorInterface] | None = None,
+    pre_step_callback: PreStepCallback | None = None,
 ) -> WorkflowOrchestrator:
     """Build a configured WorkflowOrchestrator from a definition and registries.
 
@@ -49,8 +61,12 @@ def build_orchestrator(
         generator_registry: Map of generator name -> concrete instance.
         guard_registry: Map of guard name -> concrete instance.
         artifact_dag: Artifact storage implementation.
-        step_callback: Optional callback passed to the orchestrator.
+        step_callback: Optional callback passed to the orchestrator (fires
+            after each step's verdict).
         effector_registry: Map of effector name -> concrete instance (optional).
+        pre_step_callback: Optional callback passed to the orchestrator
+            (fires just before each step's ``agent.execute()``). Used to
+            display per-AP progress on long-running workflows.
 
     Returns:
         A fully configured ``WorkflowOrchestrator`` ready to ``execute()``.
@@ -61,11 +77,14 @@ def build_orchestrator(
     """
     effector_registry = effector_registry or {}
 
+    _validate_dep_references(definition, ap_context)
+
     orchestrator = WorkflowOrchestrator(
         artifact_dag,
         rmax=definition.rmax,
         constraints=definition.constraints,
         step_callback=step_callback,
+        pre_step_callback=pre_step_callback,
     )
 
     for ap_def in definition.action_pairs:
@@ -107,6 +126,48 @@ def build_orchestrator(
     return orchestrator
 
 
+def _validate_dep_references(
+    definition: WorkflowDefinition,
+    ap_context: dict[str, APContextEntry],
+) -> None:
+    """Reject workflows where a `{dep.X.field}` reference points outside `requires`.
+
+    Scans every AP's `task` template for `{dep.<ap_id>.<field>}` placeholders
+    and asserts that the referenced AP id is declared in the consuming AP's
+    `requires` list. Fails fast at orchestrator-build time with a precise
+    error rather than producing a misleading runtime KeyError when
+    `CommandTemplateGenerator` looks up the missing dependency.
+
+    Type-based references (`{type.<artifact_type>.<field>}`) are independent
+    of `requires` by design and are not checked here.
+
+    Raises:
+        ValueError: when any AP's task references a `{dep.X.*}` for an X
+            not in that AP's `requires`.
+    """
+    errors: list[str] = []
+    for ap_def in definition.action_pairs:
+        ctx = ap_context.get(ap_def.ap_id)
+        if ctx is None or not ctx.task:
+            continue
+        referenced = set(_DEP_PLACEHOLDER_RE.findall(ctx.task))
+        if not referenced:
+            continue
+        declared = set(ap_def.requires or [])
+        missing = referenced - declared
+        if missing:
+            for ref in sorted(missing):
+                errors.append(
+                    f"AP '{ap_def.ap_id}' task references {{dep.{ref}.<field>}} "
+                    f"but does not declare '{ref}' in `requires` "
+                    f"(declared: {sorted(declared)})."
+                )
+    if errors:
+        raise ValueError(
+            "Workflow has unresolved dep references:\n  " + "\n  ".join(errors)
+        )
+
+
 def _resolve_generator(
     ap_def: ActionPairDefinition,
     registry: dict[str, GeneratorInterface],

{atomicguard-2.26.1 → atomicguard-2.28.0}/src/atomicguard/application/workflow.py

@@ -67,6 +67,14 @@ logger = logging.getLogger(__name__)
 # Callback type: (ap_id, artifact, guard_result) -> None
 StepCallback = Callable[[str, "Artifact", "GuardResult"], None]
 
+# Pre-step callback: (ap_id,) -> None. Invoked once just before each
+# AP's agent.execute() runs (after deps are resolved, before the
+# generator/effector/guard chain starts). Fires once per workflow-level
+# entry into the step — inner retries inside the DualStateAgent loop are
+# not surfaced here, but an Extension-09 backtrack re-entry to the same
+# AP will re-fire the callback (which is the right signal).
+PreStepCallback = Callable[[str], None]
+
 
 class WorkflowOrchestrator(ActionPairPoolInterface, WorkflowExecutorInterface):
     """
@@ -83,6 +91,7 @@ class WorkflowOrchestrator(ActionPairPoolInterface, WorkflowExecutorInterface):
         constraints: str = "",
         agent_factory: AgentFactory | None = None,
         step_callback: StepCallback | None = None,
+        pre_step_callback: PreStepCallback | None = None,
     ):
         """
         Args:
@@ -94,12 +103,18 @@ class WorkflowOrchestrator(ActionPairPoolInterface, WorkflowExecutorInterface):
             step_callback: Optional callback invoked after each step completes
                 (both pass and fail). Signature:
                 ``(ap_id: str, artifact: Artifact, guard_result: GuardResult) -> None``
+            pre_step_callback: Optional callback invoked just before each
+                step's ``agent.execute()`` runs. Signature: ``(ap_id: str) -> None``.
+                Useful for displaying per-AP progress in long-running workflows
+                where the user otherwise sees no output between the previous
+                step's verdict and this step's.
         """
         self._dag = artifact_dag
         self._rmax = rmax
         self._constraints = constraints
         self._agent_factory = agent_factory
         self._step_callback = step_callback
+        self._pre_step_callback = pre_step_callback
         self._steps: list[WorkflowStep] = []
         self._steps_by_id: dict[str, WorkflowStep] = {}
         self._workflow_state = WorkflowState()
@@ -293,6 +308,11 @@ class WorkflowOrchestrator(ActionPairPoolInterface, WorkflowExecutorInterface):
                 step_escalation_feedback = tuple(
                     self._escalation_feedback.get(step.guard_id, [])
                 )
+                # Invoke pre-step callback before the AP actually runs, so
+                # consumers can show "step X starting" output before the
+                # (potentially slow) generator/effector/guard chain executes.
+                if self._pre_step_callback is not None:
+                    self._pre_step_callback(step.guard_id)
                 artifact = agent.execute(
                     specification,
                     dependencies,
@@ -304,14 +324,14 @@ class WorkflowOrchestrator(ActionPairPoolInterface, WorkflowExecutorInterface):
                 )
 
                 # Invoke step callback on success
-                if (
-                    self._step_callback is not None
-                    and artifact.guard_result is not None
-                ):
-                    self._step_callback(step.guard_id, artifact, artifact.guard_result)
+                self._fire_step_callback(step.guard_id, artifact)
 
             except StagnationDetected as e:
                 # Level 2: WorkflowOrchestrator backtracking
+                # Fire post-step callback to close the entry (paired with the
+                # pre_step_callback fired above). On the continue sub-path the
+                # next workflow entry will fire a fresh pre+post pair.
+                self._fire_step_callback(step.guard_id, e.artifact)
                 if self._escalation_count[step.guard_id] < step.e_max:
                     logger.info(
                         "[%s] Escalation %d/%d triggered. Targets: %s",
@@ -355,6 +375,7 @@ class WorkflowOrchestrator(ActionPairPoolInterface, WorkflowExecutorInterface):
 
             except EscalationRequired as e:
                 # Level 4: Human intervention (fatal guard)
+                self._fire_step_callback(step.guard_id, e.artifact)
                 return WorkflowResult(
                     status=WorkflowStatus.ESCALATION,
                     artifacts=self._artifacts,
@@ -364,6 +385,11 @@ class WorkflowOrchestrator(ActionPairPoolInterface, WorkflowExecutorInterface):
                 )
 
             except RmaxExhausted as e:
+                # Last attempt's artifact is the head of the most recent
+                # provenance entry; provenance is non-empty when this is raised.
+                last_artifact = e.provenance[-1][0] if e.provenance else None
+                if last_artifact is not None:
+                    self._fire_step_callback(step.guard_id, last_artifact)
                 return WorkflowResult(
                     status=WorkflowStatus.FAILED,
                     artifacts=self._artifacts,
@@ -476,6 +502,17 @@ class WorkflowOrchestrator(ActionPairPoolInterface, WorkflowExecutorInterface):
 
         return dependents
 
+    def _fire_step_callback(self, ap_id: str, artifact: "Artifact") -> None:
+        """Invoke step_callback for an AP entry if both callback and guard_result exist.
+
+        Centralises the None-guard so success and failure paths share the same
+        contract: exactly one call per workflow-level entry, whenever a
+        guard_result is available to report.
+        """
+        if self._step_callback is None or artifact.guard_result is None:
+            return
+        self._step_callback(ap_id, artifact, artifact.guard_result)
+
     def _inject_failure_context(self, target_id: str, summary: str) -> None:
         """Add failure summary to constraints for target re-execution (Definition 48).
 

{atomicguard-2.26.1 → atomicguard-2.28.0}/src/atomicguard/cli/run.py

@@ -247,7 +247,7 @@ def _execute_in_process(
 
     # Build registries
     click.echo(f"\nModel: {model} ({provider})")
-    from atomicguard.infrastructure.registries import (
+    from atomicguard.contrib.registries import (
         build_generator_registry,
         build_guard_registry,
     )

{atomicguard-2.26.1 → atomicguard-2.28.0}/src/atomicguard/cli/runner.py

@@ -155,7 +155,7 @@ def _execute_job(
 
     try:
         # Build registries from the job's model/provider
-        from atomicguard.infrastructure.registries import (
+        from atomicguard.contrib.registries import (
             build_generator_registry,
             build_guard_registry,
         )

atomicguard-2.28.0/src/atomicguard/contrib/__init__.py

@@ -0,0 +1,9 @@
+"""
+contrib — reusable building blocks for AtomicGuard agents.
+
+Generic guards, effectors, and generators that are useful across agents
+but do not belong in the core framework. Agents import from here;
+core (domain, application, infrastructure) never imports from here.
+
+One-way dependency: contrib → core, never core → contrib.
+"""

{atomicguard-2.26.1/src/atomicguard/infrastructure → atomicguard-2.28.0/src/atomicguard/contrib}/effectors/bash_executor.py

@@ -101,6 +101,11 @@ class BashCommandExecutor(EffectorInterface):
                     "command": command,
                 }
             ),
+            # Preserve artifact_type from the plan so type-based dependency
+            # resolution ({type.<artifact_type>.<field>}) can find this artifact
+            # in R. Without this, the effector's output artifact loses the type
+            # tag the action_pair attached to the plan.
+            artifact_type=plan.artifact_type,
         )
 
     def undo(self, plan: Artifact) -> bool:  # noqa: ARG002

atomicguard-2.28.0/src/atomicguard/contrib/generators/command_template.py

@@ -0,0 +1,184 @@
+"""
+CommandTemplateGenerator: Deterministic generator that resolves {spec.*},
+{dep.<ap_id>.<field>}, and {type.<artifact_type>.<field>} placeholders.
+
+For command-based APs, the task field in the prompt template IS the command
+template. The generator resolves placeholders from the specification and from
+upstream artifact content (parsed as JSON).
+
+Three placeholder forms:
+  {spec.<key>}                       — workflow specification key/value pair
+  {dep.<ap_id>.<field>}              — direct dep by AP id (legacy)
+  {type.<artifact_type>.<field>}     — by artifact_type, scanning R for the
+                                       most recent ACCEPTED artifact whose
+                                       producer declared this artifact_type.
+                                       Independent of `requires` declarations.
+"""
+
+import json
+import re
+import uuid
+from datetime import datetime
+
+from atomicguard.domain.interfaces import GeneratorInterface
+from atomicguard.domain.models import (
+    ActionPairId,
+    Artifact,
+    ArtifactId,
+    ArtifactStatus,
+    Context,
+    ContextSnapshot,
+    WorkflowId,
+)
+from atomicguard.domain.prompts import PromptTemplate
+
+
+class CommandTemplateGenerator(GeneratorInterface):
+    """Resolves {spec.*}, {dep.<ap_id>.<field>}, and {type.<artifact_type>.<field>}
+    placeholders in the task template.
+
+    {spec.<key>} — resolved from the specification string (key=value pairs).
+    {dep.<ap_id>.<field>} — resolved by parsing the named dependency artifact's
+        content as JSON and extracting <field>. Requires <ap_id> to be in the
+        AP's `requires`. If the JSON value is a list, the first element is used.
+    {type.<artifact_type>.<field>} — resolved by scanning R for the most recent
+        ACCEPTED artifact with matching artifact_type. Does NOT require the
+        producing AP to be in `requires`; type-based hydration sidesteps the
+        ordering-vs-visibility conflation. The producer AP must declare the
+        artifact_type via `output_artifact_type` (or equivalently the AP's
+        artifact_type field on its definition).
+    """
+
+    def generate(
+        self,
+        context: Context,
+        template: PromptTemplate,
+        action_pair_id: str = "unknown",
+        workflow_id: str = "unknown",
+        workflow_ref: str | None = None,
+    ) -> Artifact:
+        command = template.task
+
+        # Resolve {spec.*} placeholders from the specification
+        placeholders = re.findall(r"\{spec\.(\w+)\}", command)
+        if placeholders:
+            spec_values = self._parse_specification(context.specification)
+            for key in placeholders:
+                if key not in spec_values:
+                    msg = f"Missing specification key: spec.{key}"
+                    raise KeyError(msg)
+                command = command.replace(f"{{spec.{key}}}", spec_values[key])
+
+        # Resolve {dep.<ap_id>.<field>} placeholders from direct dependency artifacts
+        dep_placeholders = re.findall(r"\{dep\.(\w+)\.(\w+)\}", command)
+        if dep_placeholders and context.ambient and context.ambient.repository:
+            dep_map = dict(context.dependency_artifacts)
+            for ap_id, field in dep_placeholders:
+                artifact_id = dep_map.get(ap_id)
+                if artifact_id is None:
+                    msg = f"Missing dependency artifact: dep.{ap_id}"
+                    raise KeyError(msg)
+                artifact = context.ambient.repository.get_artifact(artifact_id)
+                value = self._extract_json_field(artifact.content, field, ap_id)
+                command = command.replace(f"{{dep.{ap_id}.{field}}}", value)
+
+        # Resolve {type.<artifact_type>.<field>} placeholders by scanning R
+        type_placeholders = re.findall(r"\{type\.(\w+)\.(\w+)\}", command)
+        if type_placeholders and context.ambient and context.ambient.repository:
+            for artifact_type, field in type_placeholders:
+                producer = self._find_artifact_by_type(context, artifact_type)
+                if producer is None:
+                    msg = (
+                        f"No ACCEPTED artifact with artifact_type={artifact_type!r} "
+                        f"found in R. Producer AP may not have run yet, or its "
+                        f"definition does not declare artifact_type={artifact_type!r}."
+                    )
+                    raise KeyError(msg)
+                value = self._extract_json_field(
+                    producer.content, field, f"type.{artifact_type}"
+                )
+                command = command.replace(f"{{type.{artifact_type}.{field}}}", value)
+
+        return Artifact(
+            artifact_id=ArtifactId(str(uuid.uuid4())),
+            workflow_id=WorkflowId(workflow_id),
+            content=command,
+            previous_attempt_id=None,
+            parent_action_pair_id=None,
+            action_pair_id=ActionPairId(action_pair_id),
+            created_at=datetime.now().isoformat(),
+            attempt_number=1,
+            status=ArtifactStatus.PENDING,
+            guard_result=None,
+            context=ContextSnapshot(
+                workflow_id=workflow_id,
+                specification=context.specification,
+                constraints=context.ambient.constraints if context.ambient else "",
+                feedback_history=(),
+            ),
+            workflow_ref=workflow_ref,
+        )
+
+    @staticmethod
+    def _parse_specification(spec: str) -> dict[str, str]:
+        """Parse specification as key=value pairs (one per line)."""
+        result = {}
+        for line in spec.strip().splitlines():
+            line = line.strip()
+            if "=" in line:
+                key, _, value = line.partition("=")
+                result[key.strip()] = value.strip()
+        return result
+
+    @staticmethod
+    def _find_artifact_by_type(context: Context, artifact_type: str) -> Artifact | None:
+        """Find the most recent ACCEPTED artifact in R with a matching artifact_type.
+
+        Independent of `requires` — scans the full repository for the current
+        workflow_id. If multiple matches exist, returns the most recent by
+        `created_at`. Returns None if no match is found.
+        """
+        if context.ambient is None or context.ambient.repository is None:
+            return None
+        if context.workflow_id is None:
+            return None
+        artifacts = context.ambient.repository.get_by_workflow(context.workflow_id)
+        matching = [
+            a
+            for a in artifacts
+            if a.artifact_type == artifact_type and a.status == ArtifactStatus.ACCEPTED
+        ]
+        if not matching:
+            return None
+        return max(matching, key=lambda a: a.created_at)
+
+    @staticmethod
+    def _extract_json_field(content: str, field: str, ap_id: str) -> str:
+        """Parse content as JSON and extract field. Lists yield their first element."""
+        try:
+            parsed = json.loads(content)
+        except json.JSONDecodeError as e:
+            msg = f"dep.{ap_id} artifact content is not valid JSON: {e}"
+            raise ValueError(msg) from e
+
+        if isinstance(parsed, list):
+            if not parsed:
+                msg = f"dep.{ap_id} artifact is an empty JSON array"
+                raise ValueError(msg)
+            parsed = parsed[0]
+
+        if not isinstance(parsed, dict):
+            msg = f"dep.{ap_id} artifact JSON is not an object or array of objects"
+            raise ValueError(msg)
+
+        if field not in parsed:
+            msg = f"dep.{ap_id} artifact has no field '{field}'"
+            raise KeyError(msg)
+
+        value = parsed[field]
+        # Nested arrays/objects are re-serialised as JSON so consumers (e.g.
+        # shell scripts piping into jq) get a valid JSON string rather than
+        # Python's repr. Primitives are str-coerced as before.
+        if isinstance(value, (list, dict)):
+            return json.dumps(value)
+        return str(value)

atomicguard-2.28.0/src/atomicguard/contrib/guards/pattern_guard.py

@@ -0,0 +1,40 @@
+"""PatternGuard — checks for required/forbidden substrings in artifact content."""
+
+from __future__ import annotations
+
+from atomicguard.domain.interfaces import GuardInterface
+from atomicguard.domain.models import Artifact, GuardResult
+
+
+class PatternGuard(GuardInterface):
+    """Passes if all required patterns are found and no forbidden patterns are found."""
+
+    def __init__(
+        self,
+        *,
+        required: list[str] | None = None,
+        forbidden: list[str] | None = None,
+    ):
+        self._required = required or []
+        self._forbidden = forbidden or []
+
+    def validate(self, artifact: Artifact, **deps: Artifact) -> GuardResult:  # noqa: ARG002
+        content = artifact.content
+
+        for pattern in self._forbidden:
+            if pattern in content:
+                return GuardResult(
+                    passed=False,
+                    feedback=f"Forbidden pattern found: {pattern!r}",
+                    guard_name="PatternGuard",
+                )
+
+        for pattern in self._required:
+            if pattern not in content:
+                return GuardResult(
+                    passed=False,
+                    feedback=f"Required pattern not found: {pattern!r}",
+                    guard_name="PatternGuard",
+                )
+
+        return GuardResult(passed=True, guard_name="PatternGuard")

atomicguard-2.28.0/src/atomicguard/contrib/guards/rendered_command_guard.py

@@ -0,0 +1,78 @@
+"""RenderedCommandGuard — pre-guard for command-based APs.
+
+Validates that the generator's rendered command is well-formed BEFORE the
+effector runs. Catches:
+
+- Empty rendered command (template was empty, or all placeholders blanked)
+- Unresolved template placeholders: `{spec.X}`, `{dep.X.Y}`, `{type.X.Y}`
+  that survived the generator. These indicate a generator bug or a missing
+  spec/dependency value the generator should have raised on.
+
+Layers as ``G_pre`` in the formal AP tuple ⟨ρ, a_gen, G_pre, E, G_post⟩.
+The corresponding ``G_post`` (e.g. ScriptResultGuard + a domain guard)
+validates the effector's output.
+
+Why this matters: failures caught at G_pre cost zero subprocess execution.
+A malformed command running through ``BashCommandExecutor`` still uses a
+slot of the AP's r_max budget and produces a confusing failure mode (the
+shell sees `{spec.foo}` literally and probably exits non-zero with an
+unhelpful message). Catching it before the effector gives a precise
+diagnosis.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+from atomicguard.domain.interfaces import GuardInterface
+from atomicguard.domain.models import Artifact, GuardResult
+
+# Match any of the three placeholder forms used by CommandTemplateGenerator.
+_UNRESOLVED = re.compile(r"\{(?:spec|dep|type)\.[\w.]+\}")
+
+
+class RenderedCommandGuard(GuardInterface):
+    """Pre-guard for command-template-based APs.
+
+    Pass when ``artifact.content`` is a non-empty string with no
+    ``{spec.*}``, ``{dep.*.*}``, or ``{type.*.*}`` placeholders remaining.
+    Fail with a precise diagnostic otherwise.
+    """
+
+    def __init__(self, **_kwargs: Any) -> None:
+        pass
+
+    def validate(self, artifact: Artifact, **dependencies: Artifact) -> GuardResult:  # noqa: ARG002
+        command = artifact.content or ""
+        stripped = command.strip()
+        if not stripped:
+            return GuardResult(
+                passed=False,
+                feedback=(
+                    "Rendered command is empty. The generator produced an empty "
+                    "task template — check ap_context.json `task` field for the "
+                    "current AP."
+                ),
+                guard_name="RenderedCommandGuard",
+            )
+
+        unresolved = _UNRESOLVED.findall(command)
+        if unresolved:
+            unique = sorted(set(unresolved))
+            return GuardResult(
+                passed=False,
+                feedback=(
+                    f"Rendered command contains unresolved placeholders: "
+                    f"{unique}. The generator should have raised KeyError; "
+                    f"if it didn't, the placeholder syntax is malformed or "
+                    f"the regex in CommandTemplateGenerator is out of sync."
+                ),
+                guard_name="RenderedCommandGuard",
+            )
+
+        return GuardResult(
+            passed=True,
+            feedback="",
+            guard_name="RenderedCommandGuard",
+        )