Address PR #7 review thread: lifecycle docs + startup logging behavior

src/automation/engine.py

@@ -57,7 +57,10 @@ class RunStatus(Enum):
 
 
 class EngineNotStartedError(RuntimeError):
-    """Raised when :meth:`AutomationEngine.trigger` is called before :meth:`start`."""
+    """
+    Raised when :meth:`AutomationEngine.trigger` or
+    :meth:`AutomationEngine.trigger_type` is called before :meth:`start`.
+    """
 
 
 @dataclass
@@ -195,17 +198,20 @@ def start(self) -> "AutomationEngine":
         """
         if not self._running:
             self._running = True
-            logger.info("AutomationEngine started")
+            logger.debug("AutomationEngine started")
         return self
 
     def stop(self) -> "AutomationEngine":
         """
-        Stop the engine and tear down all registered components.
+        Stop the engine and tear down all registered components by deregistering
+        each one from the component registry.
 
         After :meth:`stop` returns, :meth:`trigger` / :meth:`trigger_type`
         will raise :class:`EngineNotStartedError` until :meth:`start` is
-        called again.  All component teardown hooks are invoked; any
-        exceptions they raise are logged and suppressed.
+        called again. Because components are deregistered during teardown, a
+        subsequent :meth:`start` does not restore previously registered
+        components; callers must register them again as needed. Any exceptions
+        raised by teardown are logged and suppressed.
         Returns *self* for chaining.
         """
         if self._running:

tests/test_automation_review_regressions.py

@@ -128,6 +128,20 @@ def test_start_is_idempotent():
     assert engine.is_running is True
 
 
+def test_start_emits_debug_log(caplog):
+    engine = AutomationEngine()
+
+    with caplog.at_level("DEBUG", logger="automation.engine"):
+        engine.start()
+
+    start_logs = [
+        record for record in caplog.records
+        if record.name == "automation.engine" and record.message == "AutomationEngine started"
+    ]
+    assert len(start_logs) == 1
+    assert start_logs[0].levelname == "DEBUG"
+
+
 def test_stop_calls_component_teardown():
     events = []
 
@@ -261,4 +275,3 @@ def test_text_file_guardrail_in_pipeline_passes_valid_payload():
 
 def test_default_text_extensions_contains_txt():
     assert ".txt" in DEFAULT_TEXT_EXTENSIONS
-