stogger 2026.5.12__tar.gz

stogger-2026.5.12/.agents/drafts/pytest-stogger-new-checks.md

@@ -0,0 +1,284 @@
+---
+lifecycle:
+  requirements:
+    completed_at: "2026-05-03T18:00:00Z"
+    git_rev: c4f0f2b
+---
+
+## Problem
+
+pytest-stogger erzwingt 12 AST-basierte Logging-Konventionen. Basierend auf einem Sample von ~280 Log-Statements aus 3 Projekten (batou-type, code-rag, docdisco) wurden 6 Lücken identifiziert, die zu unnötigem Log-Noise, fehlendem Context und ungenutztem Structlog-Potential führen.
+
+## Binding Decisions
+
+### scope-batch
+
+#### Context
+
+Es gibt 6 vorgeschlagene Checks. Zu viele auf einmal risking Qualität, zu wenige liefern nicht den erwarteten Mehrwert.
+
+#### Decision
+
+Alle 6 Checks in einem Durchgang umsetzen:
+1. `log-consolidate-repeated` — 3+ Log-Calls in direkter Folge mit shared Context → zusammenfassen
+2. `log-debug-context-range` — max 5 key-value pairs bei DEBUG
+3. `log-bind-threshold` — wiederholter key-value 3+ Mal → log.bind() nutzen
+4. `log-exception-not-in-except` — log.exception() außerhalb except-Block
+5. `log-error-in-except` — log.error() in except-Block statt log.exception()
+6. `log-warning-for-not-found` — WARNING bei "not found" Event-IDs
+
+#### Alternatives
+
+a. Nur Top 3 — schneller, aber Lücken bleiben
+b. Nur 1 MVP — zu wenig Impact
+
+#### Consequences
+
+Größerer Durchgang, aber alle Checks folgen demselben Registry-Pattern und teilen Helper-Funktionen.
+
+### consolidate-severity
+
+#### Context
+
+Die Consolidation-Heuristik hat False Positives bei legitimen Multi-Step-Logging.
+
+#### Decision
+
+Config-gesteuert: Default WARNING, kann per Config auf ERROR gestellt werden via `consolidate_as_error = true`.
+
+#### Alternatives
+
+a. Immer WARNING — zu schwach für CI
+b. Immer ERROR — zu viele False Positives
+
+#### Consequences
+
+Neue Config-Option `consolidate_as_error` in `[tool.pytest-stogger]`.
+
+### debug-range-config
+
+#### Context
+
+Konvention ist "2-3 key-values normal, max 5". Braucht das einen konfigurierbaren Schwellwert?
+
+#### Decision
+
+Fester Wert 5 — hardcoded wie die meisten Rules. Kein Config-Overhead.
+
+#### Alternatives
+
+a. Per Config (debug_max_context) — flexibel aber unnötig
+b. Nur Warning bei >7 — zu großzügig
+
+#### Consequences
+
+Hardgrenze bei 5 key-value pairs für DEBUG. Darüber → Violation.
+
+### exception-placement
+
+#### Context
+
+log.exception() erzeugt einen Stacktrace — ohne except-Block ist das sinnlos oder verwirrend.
+
+#### Decision
+
+Eigenständiger Check: `log-exception-not-in-except`. log.exception() nur erlaubt innerhalb von except-Blöcken.
+
+#### Alternatives
+
+a. Mit Inline-Ignore — nicht nötig, klarer Fix
+b. Nicht umsetzen — zu noisy
+
+#### Consequences
+
+Klare Rule mit klarer Migration: exception() → error() wenn außerhalb von except.
+
+### consolidate-message-ux
+
+#### Context
+
+Fehlermeldungen müssen dem User helfen, nicht nur informieren.
+
+#### Decision
+
+Zeige Merge-Vorschlag: betroffene Zeilen + konkreter Vorschlag wie die zusammengefasste Statement aussehen könnte.
+
+#### Alternatives
+
+a. Nur Zeilen + Count — nicht hilfreich genug
+b. Diff-Style — zu komplex für ersten Wurf
+
+#### Consequences
+
+Die Violation-Message enthält ein konkretes Code-Beispiel.
+
+## Scope Boundaries
+
+- INCLUDE: 6 neue File-Rules im bestehenden Registry-Pattern
+- INCLUDE: Neue Config-Option `consolidate_as_error`
+- EXCLUDE: Changes an bestehenden Rules
+- EXCLUDE: Changes am logging-coverage Check
+- EXCLUDE: Autofix-Funktionalität (nur Detection)
+
+## Open Questions
+
+- Severity der restlichen 5 Checks (ERROR wie bestehende Rules?)
+- Default-Severity für bind-threshold und error-in-except
+- Interface: wie werden die neuen Rules in --help und Status-Output sichtbar?
+
+### severity-strategy
+
+#### Context
+
+6 neue Checks mit unterschiedlicher Heuristik-Qualität. Klare AST-basierte Rules können ERROR sein, heuristische sollten WARNING sein.
+
+#### Decision
+
+Gemischt:
+- ERROR: `log-exception-not-in-except`, `log-error-in-except`, `log-debug-context-range`, `log-bind-threshold`
+- WARNING (config-steuerbar): `log-consolidate-repeated`, `log-warning-for-not-found`
+
+#### Alternatives
+
+a. Alle ERROR — zu streng für heuristische Checks
+b. Alle WARNING — zu schwach für klare Rules
+
+#### Consequences
+
+Zwei Severity-Level in der Rule-Architektur. Needs flag `needs_warning_severity` auf _RuleSpec oder Config-basiert.
+
+### error-in-except-severity
+
+#### Context
+
+log.error() in except-Block verliert den Stacktrace — suboptimal aber nicht falsch.
+
+#### Decision
+
+ERROR — strenger als ursprünglich empfohlen. log.exception() ist in except-Blöcken immer die bessere Wahl.
+
+#### Alternatives
+
+a. WARNING — weniger Breakage aber schwächer
+b. Nicht umsetzen — bestehende no-log-info-in-except reicht
+
+#### Consequences
+
+Migration: alle log.error() in except-Blöcken → log.exception(). Inline-Ignore möglich.
+
+### warning-not-found-fp
+
+#### Context
+
+Pattern-Matching auf Event-IDs (*-not-found, *-missing, *-absent) hat False Positives.
+
+#### Decision
+
+Inline-Ignore: # stogger: ignore log-warning-for-not-found für legitime Fälle.
+
+#### Alternatives
+
+a. Exempt-List in Config — flexibel aber Config-Bloat
+b. Nicht umsetzen — zu heuristisch
+
+#### Consequences
+
+Neue Rule mit needs_inline_ignores=True Flag.
+
+### bind-threshold-value
+
+#### Context
+
+Wiederholter key-value in Scope → log.bind() nutzen.
+
+#### Decision
+
+Schwellwert 3 — konsistent mit bestehender check_bind_for_repeating die auch bei 3 Wiederholungen triggert.
+
+#### Alternatives
+
+a. 2 Mal — strenger
+b. Config-gesteuert — unnötig, 3 ist bewährt
+
+#### Consequences
+
+Konsistente Schwelle im Codebase. Kein neuer Config-Wert nötig.
+
+## Scope Boundaries (Updated)
+
+- INCLUDE: 6 neue File-Rules im bestehenden Registry-Pattern
+- INCLUDE: Neue Config-Option `consolidate_as_error`
+- INCLUDE: Severity-Level ERROR vs WARNING für neue Rules
+- EXCLUDE: Changes an bestehenden Rules
+- EXCLUDE: Changes am logging-coverage Check
+- EXCLUDE: Autofix-Funktionalität (nur Detection)
+
+### warning-pytest-output
+
+#### Context
+
+WARNING-Level Rules sollen den Test nicht failen lassen, aber sichtbar sein.
+
+#### Decision
+
+Normale `pytest.warning` — Test besteht, Warning wird angezeigt. Konsistent mit Python-Warnings.
+
+#### Alternatives
+
+a. Eigener Item-Typ — zu komplex
+b. Nur in Summary — nicht prominent genug
+
+#### Consequences
+
+Plugin nutzt `warnings.warn()` statt `StoggerViolationError` für WARNING-Level Rules.
+
+### warning-flag-architecture
+
+#### Context
+
+Rule-Architektur braucht ein Konzept für Severity-Level.
+
+#### Decision
+
+Neues Flag `is_warning: bool = False` auf `_RuleSpec`. Plugin entscheidet basierend auf Flag ob ERROR oder WARNING.
+
+#### Alternatives
+
+a. Config pro Rule — flexibel aber Config-Bloat
+b. Separate Rule-Liste — dupliziert Architektur
+
+#### Consequences
+
+Neues Feld auf _RuleSpec. Plugin.py muss zwei Pfade haben: ERROR-Path (bestehend) + WARNING-Path (neu, via warnings.warn).
+
+### discoverability
+
+#### Context
+
+Neue Rules sollen für Consumer-Projekte sofort nützlich sein.
+
+#### Decision
+
+Automatisch sichtbar — Zero-Config. Neue Rules laufen wie bestehende, werden im Test-Output sichtbar.
+
+#### Alternatives
+
+a. Disabled per Default — sicher aber weniger nützlich
+
+#### Consequences
+
+Consumer-Projekte sehen neue Rules sofort. WARNING-Level Rules brechen nicht, ERROR-Level Rules können per disable_rules deaktiviert werden.
+
+## Scope Boundaries (Final)
+
+- INCLUDE: 6 neue File-Rules im bestehenden Registry-Pattern
+- INCLUDE: Neues `is_warning` Flag auf `_RuleSpec`
+- INCLUDE: WARNING-Path via `warnings.warn()` in plugin.py
+- INCLUDE: Neue Config-Option `consolidate_as_error`
+- EXCLUDE: Changes an bestehenden Rules
+- EXCLUDE: Changes am logging-coverage Check
+- EXCLUDE: Autofix-Funktionalität (nur Detection)
+
+- Interface: wie werden die neuen Rules in --help und Status-Output sichtbar?
+- Brauchen wir ein neues `needs_warning_severity` Flag auf `_RuleSpec`?
+- Wie wird WARNING im pytest-Output dargestellt? ( eigenes Item-Type oder nur in Summary?)

stogger-2026.5.12/.agents/impl_specs/logging-decorators-docs.md

@@ -0,0 +1,91 @@
+---
+lifecycle:
+  requirements:
+    completed_at: "2026-05-04T14:00:00Z"
+    git_rev: "be50a11"
+---
+
+# logging-decorators-docs
+
+## Context
+
+The logging decorators (`log_call`, `log_result`, `log_operation`, `log_scope`) are implemented and functional (commit be50a11) but documentation-invisible. Docstrings lack structured parameter docs. Autoapi skips `_decorators.py` (underscore prefix). No user-facing prose exists. Users cannot discover or learn the decorators through docs.
+
+## Decisions
+
+### docstring-quality
+
+#### Context
+
+Existing docstrings describe behavior in 1-2 sentences but omit structured parameter documentation, return types, raised exceptions, and usage examples. Other stogger public APIs (e.g., `init_logging`) have full Args/Returns/Raises docstrings.
+
+#### Decision
+
+Enrich all 5 public docstrings (`log_call`, `log_result`, `log_operation`, `log_scope`, `LogScope`) with Google-style Args, Returns, Raises, and Examples sections. Match the quality of `init_logging` in `core.py`.
+
+#### Alternatives
+
+a. Numpy-style docstrings — inconsistent with existing codebase convention
+b. Minimal docstrings + separate docs — forces users to look in two places
+
+#### Consequences
+
+`help(log_call)` and generated API docs both show complete usage information. Single source of truth per function.
+
+### api-docs-visibility
+
+#### Context
+
+Autoapi skips `_decorators.py` because the `autoapi_skip_member` hook in `conf.py` rejects names starting with `_`. The re-exports in `core.py` are bare imports (`# noqa: F401`) so autoapi doesn't document them either. Generated `docs/api/stogger/core/index.rst` has zero decorator entries.
+
+#### Decision
+
+Add manual Sphinx directives to `docs/api/stogger/core/index.rst` for the 5 re-exported names. Use `.. py:function::` for decorators and `.. py:class::` for `LogScope`, with `:canonical:` pointing to `stogger._decorators` source. This keeps the private module hidden while surfacing the public API.
+
+#### Alternatives
+
+a. Modify `autoapi_skip_member` to allow `_decorators` — exposes private module internals
+b. Move decorators to public `decorators.py` — violates architecture decision (Layer 2 placement)
+
+#### Consequences
+
+Decorators appear in generated HTML docs under `stogger.core`. Source links go to `_decorators.py` which is acceptable since users navigate via public API, not module internals.
+
+### user-guide-integration
+
+#### Context
+
+`docs/user/logging_patterns.md` has manual "Function Tracing" and "Timing Operations" patterns that are exactly what the decorators automate. Users reading that page have no indication that decorators exist.
+
+#### Decision
+
+Add a new "Decorators" section to `logging_patterns.md` after the "Common Patterns" section. Cover all 4 features (`@log_call`, `@log_result`, `@log_operation`, `log_scope()`) with practical examples. Cross-reference from the existing "Function Tracing" and "Timing Operations" subsections.
+
+#### Alternatives
+
+a. New standalone page `docs/user/decorators.md` — fragments the logging patterns narrative
+b. No user guide, rely on API docs only — poor discoverability for new users
+
+#### Consequences
+
+Users reading logging patterns naturally discover decorators. Single coherent page covers manual and automated approaches.
+
+## Requirements
+
+### Files to Modify
+
+- **Modify**: `src/stogger/_decorators.py` — enriched docstrings for all 5 public names
+- **Modify**: `docs/api/stogger/core/index.rst` — add decorator entries to summary lists and module contents
+- **Modify**: `docs/user/logging_patterns.md` — add "Decorators" section with examples
+
+### Docstring Requirements
+
+Each decorator must document: Args (func, include_args, exclude_args with types and semantics), event format (fields emitted), exception behavior. `LogScope` must document constructor args, `add_fields`, enter/exit lifecycle, async support. `log_scope` must document name and **fields parameters. All must include a 2-3 line usage example.
+
+### User Guide Requirements
+
+New section must show: basic usage of all 4 features, arg filtering example, exception handling example, async usage. Each example must be self-contained and runnable.
+
+## References
+
+- `.agents/impl_specs/logging-decorators.md` — original implementation spec with event schemas and interface contracts

stogger-2026.5.12/.agents/impl_specs/logging-decorators.md

@@ -0,0 +1,322 @@
+---
+lifecycle:
+  requirements:
+    completed_at: "2026-05-03T12:00:00Z"
+    git_rev: "c4f0f2b"
+  design:
+    completed_at: "2026-05-03T12:30:00Z"
+    git_rev: "c4f0f2b"
+  implement:
+    completed_at: "2026-05-03T13:00:00Z"
+    git_rev: "1682052"
+---
+
+# logging-decorators
+
+## Context
+
+Stogger has no decorators or context managers for structured logging. Users must manually write `log.info("called", func=..., args={...})`. Three named decorators and one context manager will provide structured call/result logging that integrates with the existing structlog pipeline.
+
+## Decisions
+
+### module-placement
+
+#### Context
+
+New code must fit the existing layered architecture enforced by pytest-archon. core.py is already 951 lines and should not grow further.
+
+#### Decision
+
+New private module `src/stogger/_decorators.py` at Layer 2. Imports `_types` and `structlog`. Re-exported through `core.py` → `__init__.py`. Registered in `test_architecture.py` with Layer 2 rules (may import `_types`, `config`; may not import `factory` or `__init__`).
+
+#### Alternatives
+
+a. Add to core.py — would push it past 1100 lines, no separation of concerns
+b. Public `decorators.py` at Layer 1 — cannot import `_types`, would need duplicate EventDict
+
+#### Consequences
+
+Clean module boundary. Architecture enforcement covers the new code from day one.
+
+### decorator-variants
+
+#### Context
+
+Users need different granularity levels for function-call logging. Three named decorators are more discoverable than one configurable decorator.
+
+#### Decision
+
+Three decorators with distinct semantics:
+
+1. `@log_call` — logs at entry. Event: `event="called"`, `func="module.qualname"`, `args={...}`. No result, no duration.
+2. `@log_result` — logs at exit. Event: `event="returned"`, `func="module.qualname"`, `result=...`, `duration_ms=...`. No args.
+3. `@log_operation` — logs at exit. Event: `event="operation"`, `func="module.qualname"`, `args={...}`, `result=...`, `duration_ms=...`. Everything in one event.
+
+All three share: sync+async support, `include_args`/`exclude_args` filtering, auto-logger via `structlog.get_logger()`, exception logging with re-raise, automatic `self`/`cls` filtering.
+
+#### Alternatives
+
+a. Single decorator with mode parameter — less discoverable, obscures intent
+b. Eliot-style start/end event pairs — doubles output, adds complexity
+
+#### Consequences
+
+Three explicit import paths. Users choose by intent: invocation tracking (`log_call`), result tracking (`log_result`), full audit (`log_operation`).
+
+### scope-object-design
+
+#### Context
+
+The `log_scope()` context manager needs state (start time, bound fields, accumulated fields) and explicit enter/exit behavior including exception handling.
+
+#### Decision
+
+`LogScope` class with `__enter__`/`__exit__`. On enter: binds fields via structlog context. On exit: logs `scope_end` event with duration and accumulated fields. On exception: logs `scope_failed` event with `exc_type`/`exc_msg`, then re-raises. `add_fields(**kwargs)` method for mid-scope enrichment. Factory function `log_scope(name, **fields)` returns a `LogScope` instance.
+
+Async support via `__aenter__`/`__aexit__` on the same class.
+
+#### Alternatives
+
+a. Generator-based `@contextmanager` — requires separate `@asynccontextmanager` for async
+b. Two separate classes for sync/async — doubles code
+
+#### Consequences
+
+Single class handles both sync and async. Stateful object enables `add_fields()` accumulation.
+
+### async-support
+
+#### Context
+
+Python ≥3.14. All decorators and context manager must work with both sync and async functions.
+
+#### Decision
+
+Each decorator uses `inspect.iscoroutinefunction(wrapped_function)` at decoration time. Returns either a sync wrapper or an async wrapper accordingly. No runtime check overhead — the check happens once at import/decoration time.
+
+For `LogScope`: implements both `__enter__`/`__exit__` and `__aenter__`/`__aexit__`. Python automatically calls the correct protocol based on `with` vs `async with`.
+
+#### Alternatives
+
+a. Single sync wrapper — breaks async functions
+b. Runtime isinstance(result, Coroutine) check — overhead on every call
+
+#### Consequences
+
+Zero runtime overhead for the sync/async dispatch. Two code paths per decorator, but they share arg-extraction and logging logic.
+
+### arg-extraction
+
+#### Context
+
+Need `args={'x': 1, 'y': 2}` in events. `inspect.getcallargs` is removed in Python 3.14.
+
+#### Decision
+
+`inspect.signature(wrapped_function)` + `sig.bind(*args, **kwargs)` + `bound.apply_defaults()`. This resolves positional args, keyword args, and defaults into a plain dict. Then apply `include_args`/`exclude_args` filtering and strip `self`/`cls`.
+
+#### Alternatives
+
+a. Manual dict construction — loses parameter names and defaults
+b. `locals()` capture — unreliable with decorators
+
+#### Consequences
+
+Correct arg resolution including defaults. Standard pattern that works with Python 3.14+.
+
+### duration-measurement
+
+#### Context
+
+`@log_result`, `@log_operation`, and `log_scope()` all need `duration_ms`.
+
+#### Decision
+
+`time.perf_counter()` — capture `t0` at entry, compute `(perf_counter() - t0) * 1000` at exit. Highest resolution, monotonic, no NTP drift.
+
+#### Alternatives
+
+a. `time.monotonic` — practically equivalent on Linux, lower resolution on some platforms
+b. Event timestamp subtraction — impossible for single-event decorators like `@log_call`
+
+#### Consequences
+
+Consistent duration measurement across all features. Sub-millisecond precision.
+
+### exception-handling
+
+#### Context
+
+Exceptions in decorated functions must be logged without changing program behavior.
+
+#### Decision
+
+Own `exc_type` and `exc_msg` fields in the event dict. `exc_type` = exception class name (e.g., `"ValueError"`). `exc_msg` = `str(exception)`. Exception is then re-raised unchanged. Does NOT use `exc_info=True` — the existing `process_exc_info`/`format_exc_info` pipeline is not invoked for decorator exceptions.
+
+Event semantics per decorator on exception:
+- `@log_call` — no exception handling (logs at entry, before execution)
+- `@log_result` — `event="failed"`, `exc_type`, `exc_msg`, `duration_ms`
+- `@log_operation` — `event="failed"`, `exc_type`, `exc_msg`, `duration_ms`, `args`
+- `log_scope()` — `event="scope_failed"`, `exc_type`, `exc_msg`, `duration_ms`
+
+#### Alternatives
+
+a. `exc_info=True` via existing pipeline — produces full tracebacks, too verbose for every decorated call
+b. Both own fields AND exc_info — redundant output
+
+#### Consequences
+
+Compact exception logging. Users get exception type and message without traceback noise. Full tracebacks available via explicit `log.exception()` outside decorators.
+
+### func-name
+
+#### Context
+
+Every event needs a `func` field identifying the decorated function.
+
+#### Decision
+
+`f"{wrapped_function.__module__}.{wrapped_function.__qualname__}"` at decoration time. Stored once, no runtime inspection needed. Works with `@functools.wraps` which preserves `__module__` and `__qualname__`.
+
+#### Alternatives
+
+a. `f.__name__` only — not unique across modules
+b. Frame inspection — expensive, unreliable with decorators
+
+#### Consequences
+
+Unique, searchable function identifiers. Zero runtime cost (computed once at decoration).
+
+### test-strategy
+
+#### Context
+
+No shared test fixtures exist. Each test file has its own `_reset_structlog` autouse fixture.
+
+#### Decision
+
+1. New `tests/conftest.py` with shared `_reset_structlog` autouse fixture (call `structlog.reset_defaults()`).
+2. New `tests/test_decorators.py` with tests for all three decorators and `log_scope()`.
+3. Update `tests/test_architecture.py` to register `_decorators` as Layer 2 module.
+4. TDD approach: write tests first, then implementation.
+
+Test locations:
+- Permanent decision tests: `tests/test_decorators.py`
+- Architecture enforcement: `tests/test_architecture.py`
+
+#### Alternatives
+
+a. No shared conftest, each file has its own reset — inconsistent with the improvement opportunity
+b. No new tests — unacceptable for new public API
+
+#### Consequences
+
+Solid test foundation. Architecture rules cover the new module from the start.
+
+## Requirements
+
+### Interface Contracts
+
+**Decorator usage:**
+```python
+from stogger import log_call, log_result, log_operation
+
+@log_call
+def fetch_user(user_id: int): ...
+
+@log_result
+def compute_hash(data: bytes) -> str: ...
+
+@log_operation(include_args=["query"], exclude_args=["password"])
+def authenticate(query: str, password: str) -> bool: ...
+```
+
+**Context manager usage:**
+```python
+from stogger import log_scope
+
+with log_scope("db_transaction", table="users") as scope:
+    insert(user)
+    scope.add_fields(rows_inserted=1)
+```
+
+**Event examples:**
+```
+# @log_call
+{"event": "called", "func": "mymodule.fetch_user", "args": {"user_id": 42}}
+
+# @log_result
+{"event": "returned", "func": "mymodule.compute_hash", "result": "abc123", "duration_ms": 2.4}
+
+# @log_operation
+{"event": "operation", "func": "mymodule.authenticate", "args": {"query": "admin"}, "result": true, "duration_ms": 15.3}
+
+# log_scope success
+{"event": "scope_end", "scope": "db_transaction", "table": "users", "rows_inserted": 1, "duration_ms": 45.2}
+
+# @log_result exception
+{"event": "failed", "func": "mymodule.compute_hash", "exc_type": "ValueError", "exc_msg": "empty input", "duration_ms": 0.1}
+
+# log_scope exception
+{"event": "scope_failed", "scope": "db_transaction", "exc_type": "ConnectionError", "exc_msg": "timeout", "duration_ms": 30001.0}
+```
+
+### Scope Boundary
+
+Not part of this work: task_uuid, task_level, parent-child tracking, preserve_context, distributed tracing, serialization.
+
+### Files to Create/Modify
+
+- **Create**: `src/stogger/_decorators.py`
+- **Modify**: `src/stogger/core.py` — add re-exports for decorators and log_scope
+- **Modify**: `src/stogger/__init__.py` — add to `__all__` and import from core
+- **Create**: `tests/conftest.py` — shared _reset_structlog fixture
+- **Create**: `tests/test_decorators.py`
+- **Modify**: `tests/test_architecture.py` — register _decorators as Layer 2
+
+## Appendix
+
+### Implementation Plan
+
+```yaml
+id: logging-decorators
+description: "Three logging decorators (log_call, log_result, log_operation) and one context manager (log_scope) as new _decorators.py module at Layer 2. Sync+async support, arg filtering, duration measurement, exception logging."
+specs:
+  - .agents/impl_specs/logging-decorators.md
+target_tests:
+  - file: tests/impl_spec/test_logging_decorators.py
+    tests:
+      - test_import_log_call_from_decorators
+      - test_import_log_result_from_decorators
+      - test_import_log_operation_from_decorators
+      - test_import_log_scope_from_decorators
+      - test_import_log_call_from_stogger_top_level
+      - test_import_log_scope_from_stogger_top_level
+      - test_log_call_produces_called_event
+      - test_log_result_produces_returned_event
+      - test_log_operation_produces_operation_event
+      - test_log_scope_returns_log_scope_instance
+      - test_log_scope_has_add_fields_method
+      - test_log_scope_success_produces_scope_end_event
+      - test_log_scope_exception_produces_scope_failed_event
+      - test_log_call_works_with_async
+      - test_log_result_works_with_async
+      - test_log_operation_works_with_async
+      - test_log_scope_works_with_async_with
+      - test_args_include_default_values
+      - test_args_strip_self
+      - test_args_strip_cls
+      - test_include_args_whitelist_filtering
+      - test_exclude_args_blacklist_filtering
+      - test_log_result_has_duration_ms
+      - test_log_operation_has_duration_ms
+      - test_log_scope_has_duration_ms
+      - test_log_result_logs_exception_and_reraises
+      - test_log_operation_logs_exception_with_args
+      - test_log_call_does_not_catch_exceptions
+      - test_log_scope_exception_reraises
+      - test_func_field_is_module_qualname
+      - test_func_field_for_method
+created_at: "2026-05-03T13:00:00Z"
+git_rev: "1682052"
+```