contextcompass 2.15.0__py3-none-any.whl

contextcompass_cli/_package/agent_onboarding/user_defined/synaptic_python_developer/profile_overrides.md

@@ -0,0 +1,27 @@
+
+
+# synaptic_python_developer profile_overrides
+
+Purpose
+- Define the user-specific overlay scope for this profile.
+- Keep default `general` and `engineer` baselines reusable for public users.
+
+Resolved inheritance
+- `general` -> `engineer` -> `synaptic_python_developer`
+- Source of truth:
+  `agent_onboarding/user_defined/synaptic_python_developer/SKILLS.MD` header
+  `INHERITS_SKILLS_FROM: agent_onboarding/default/engineer/SKILLS.MD` and
+  the engineer header chain to `agent_onboarding/default/general/SKILLS.MD`.
+
+Overlay scope
+- User-preference collaboration tone and engagement style.
+- User-preference pushback intensity and clarification cadence.
+- User-specific operating emphasis that should not be required for public
+  default onboarding paths.
+
+References
+- `agent_onboarding/user_defined/synaptic_python_developer/policies/synaptic_policy_overrides.md`
+- `agent_onboarding/user_defined/synaptic_python_developer/skills/synaptic_skill_overrides.md`
+- `agent_onboarding/user_defined/synaptic_python_developer/behavioral_guidelines/synaptic_behavior_overrides.md`
+
+

contextcompass_cli/_package/agent_onboarding/user_defined/synaptic_python_developer/skills/python/attribute_aliasing_skill_benchmark.py

@@ -0,0 +1,35 @@
+"""Attribute aliasing micro benchmark example."""
+
+import timeit
+
+
+class Sample:
+    def __init__(self) -> None:
+        self.value = 1
+
+
+def direct(obj: Sample) -> int:
+    total = 0
+    for _ in range(1000):
+        total += obj.value
+    return total
+
+
+def aliased(obj: Sample) -> int:
+    total = 0
+    value = obj.value
+    for _ in range(1000):
+        total += value
+    return total
+
+
+def run() -> tuple[float, float]:
+    obj = Sample()
+    d = timeit.timeit(lambda: direct(obj), number=2000)
+    a = timeit.timeit(lambda: aliased(obj), number=2000)
+    return d, a
+
+
+if __name__ == "__main__":
+    direct_t, aliased_t = run()
+    print(f"direct={direct_t:.6f}s aliased={aliased_t:.6f}s")

contextcompass_cli/_package/agent_onboarding/user_defined/synaptic_python_developer/skills/python/banned_patterns.md

@@ -0,0 +1,110 @@
+
+
+# banned_patterns
+
+Purpose
+- Prevent unsafe or non-auditable behavior.
+
+Attribute Access Rule (No Defensive Introspection in Owned Code)
+If we own the file/module and the attribute names are visible in the code, do NOT use getattr() / hasattr() as a defensive pattern.
+
+* Use direct access (obj.attr).
+* Handle None explicitly where appropriate.
+* If you genuinely need to handle a missing attribute on an external/optional dependency, call it directly and catch AttributeError instead of probing with hasattr. This keeps owned-code contracts strict while still being safe when the contract is ambiguous or external.
+
+getattr() / hasattr() are allowed only in ambiguous situations, meaning at least one is true:
+* The object is polymorphic/external and its attribute contract is not visible in our code.
+* The attribute/method is optional by design (capability checks).
+* The attribute name is truly dynamic.
+
+Polymorphic lock cleanup exception (allowed):
+* For lock-like objects that may be different implementations, capability checks are allowed:
+  if hasattr(lock, "cleanup"): lock.cleanup()
+
+Disallowed example (we own it / visible contract):
+* getattr(self, "_foo", None) when _foo is clearly part of our class/object contract in this file.
+
+Defensive local alias for nullable owned dependency (banned)
+If a dependency is part of the owned class contract, do not treat it as optional at access time.
+Do not create a local alias just to guard a potentially None owned dependency.
+Guarantee initialization through the lifecycle and use direct self references.
+Do not silently return defaults in hot path accessors.
+
+Snapshotting owned structures for reads (banned)
+Do not snapshot owned registries/maps/lists into locals or copies for read access.
+Use the live structure directly when it is part of the owned contract.
+Snapshotting is allowed only when required for correctness (for example, iterating
+while mutation is expected or when a defensive copy is explicitly mandated by the
+method contract). When snapshotting is required, document the reason in the
+method docstring or a targeted comment.
+
+Disallowed example (defensive local alias):
+```
+@property
+def validated(self) -> bool:
+    """ True if the validation phase has run and marked this spell as validated. """
+    crafter = self._crafter
+    return crafter.validated if crafter is not None else False
+
+@property
+def is_broken(self) -> bool:
+    """ True if the validation phase classified this spell as broken / unsafe. """
+    crafter = self._crafter
+    return crafter.is_broken if crafter is not None else False
+```
+
+Banned / Disallowed Patterns
+* Never use type: ignore.
+* Never use # noqa.
+* eval() / exec() / compile() are allowed for agent work when codegen is required.
+* Never use wildcard imports (e.g., from module import *).
+* Never use PEP 604 union syntax (e.g., A | B, T | None); use Optional/Union.
+
+Never use
+- type: ignore
+- # noqa
+- eval() / exec() / compile() for non-codegen work
+- wildcard imports
+- from __future__ import annotations (new files must not add this)
+- Python 3.14 already provides deferred annotations by default, so this is not
+  a valid workaround for typing-only import pressure
+- PEP 604 unions (A | B, T | None); use Optional/Union
+- fake local Protocol/ABC enforcement surfaces when a truthful concrete type
+  plus `typing.TYPE_CHECKING` import would solve the typing-only dependency
+- `else: TypeName = Any` fallback aliases under `TYPE_CHECKING`
+- widening truthful concrete collaborator types to `Any` instead of raising the
+  conflict to the user
+
+Dataclass restrictions
+- Do not use dataclasses to store object references or owned resources.
+- Dataclasses may only contain value types (str, int, float, bool, None) and containers of those value types.
+- If object references are required, use a normal class with explicit cleanup.
+
+Cleanup/disposal guidance
+- Proper usage: `agent_onboarding/user_defined/synaptic_python_developer/skills/python/cleanup_and_disposal.md`
+- Anti-patterns: `agent_onboarding/user_defined/synaptic_python_developer/examples/python/anti_patterns.py`
+- Cleanup/disposal anti-patterns (summary):
+  - Snapshotting owned `self._fields` into locals as defensive cleanup guards.
+  - Defensive `None` checks on owned fields when lifecycle guarantees they exist.
+  - Relying on GC for owned resources instead of explicit cleanup.
+  - Keeping stale owned references alive after cleanup.
+  - Using `None` by default when the contract does not need a retained
+    post-cleanup tombstone field.
+  - Cleaning loggers before owned children.
+  - Placeholder comments like "already nulled above" or "already deleted above"
+    instead of the actual teardown actions.
+
+Owned-code strictness
+- Do not use getattr/hasattr for owned attributes.
+- Handle AttributeError only for truly optional external interfaces.
+- Do not replace honest `TYPE_CHECKING` imports with fake structural shims just
+  to avoid a typing-only dependency edge.
+
+Exception
+- Polymorphic lock cleanup may use hasattr(lock, "cleanup").
+
+Examples
+- agent_onboarding/user_defined/synaptic_python_developer/examples/python/anti_patterns.py
+
+
+

contextcompass_cli/_package/agent_onboarding/user_defined/synaptic_python_developer/skills/python/cleanup_and_disposal.md

@@ -0,0 +1,79 @@
+
+
+# cleanup_and_disposal
+
+Purpose
+- Enforce deterministic, idempotent cleanup with explicit post-teardown field policy.
+
+Cleanup / Teardown Discipline (Immediately After Initialization)
+
+Cleanup is a core part of this library's correctness contract.
+* Cleanup must be deterministic and idempotent.
+* Prefer object teardown: call cleanup() on child objects, then delete owned
+  references to drop the live surface and prevent use-after-clean.
+* Look at existing implementations of the class for patterns to better understand requirements. We cleanup everything; do not leave it to the GC.
+* Logger teardown last.
+* Do not use placeholder comments like "already deleted above." Write the
+  actual teardown assignments or deletes.
+
+Cleanup teardown contract:
+* Default posture: after cleaning children, delete owned field references with
+  `del self._field` so the object stops exposing stale state.
+* Allowed exception: set a field to `None` only when the contract explicitly
+  needs a retained post-cleanup tombstone surface for callers, tests, or
+  diagnostic introspection.
+* If a field is kept as `None` instead of deleted, that must be intentional and
+  documented.
+
+Post-cleanup usage rule
+* If a class implements cleanup, assume the object is not used after cleanup completes.
+* Prefer `self.check_cleaned()` and allow it to throw for methods that require a live object.
+* Only use `if self._cleaned: return` when the method must be non-throwing by contract.
+* Do NOT snapshot `self._field` into locals unless absolutely necessary and justified.
+* Do NOT guard internal fields with `if x is None` when lifecycle guarantees they exist pre-cleanup.
+* `None` checks are for external inputs, truly optional state, or deliberately
+  retained tombstone fields only.
+
+Rules
+- Cleanup implemented immediately after __init__.
+- If your base class defines a cleanup contract, prefer deleting owned fields
+  after cleanup. Use `None`
+  only when the class contract explicitly requires a retained post-cleanup
+  field surface.
+- Cleanup must be idempotent and safe to call multiple times.
+- Use a lock when cleanup can race with active work; check _cleaned before and after locking.
+- Tear down child objects before clearing own fields.
+- Delete owned references after cleanup by default.
+- Logger teardown is always last.
+- Do not rely on GC for owned resources.
+- Document cleanup ordering and ownership in the docstring.
+
+Checklist
+- Guard against double cleanup.
+- Acquire lock, then re-check _cleaned.
+- Cleanup children in dependency order.
+- Delete the lock after guarded teardown by default.
+- Delete owned fields explicitly, unless a retained `None` tombstone is part of
+  the contract.
+- Logger cleanup last.
+
+Example order
+1) if _cleaned: return
+2) with lock: re-check _cleaned, then cleanup children
+3) del self._child
+4) del self._lock
+5) logger.cleanup() (last)
+6) del self._logger
+
+Retained-`None` exception example
+1) if callers/tests intentionally read `field` after cleanup:
+2) document that `field` becomes `None`
+3) set `self.field = None` instead of deleting it
+4) keep that exception local and explicit
+
+Examples
+- agent_onboarding/user_defined/synaptic_python_developer/examples/python/cleanup_patterns.py
+
+
+
+

contextcompass_cli/_package/agent_onboarding/user_defined/synaptic_python_developer/skills/python/comments.md

@@ -0,0 +1,39 @@
+
+
+# comments
+
+Purpose
+- Preserve and improve comments as part of the API contract.
+
+Prime Directive: Documentation-First Edits
+Whenever you add or modify code:
+* Every class must have a rich docstring.
+* Every method/function must have a rich docstring.
+* Comments must be preserved and improved when they are unclear or insufficient.
+* Treat docstrings + comments as part of the API: they must remain accurate.
+
+Non-Negotiables
+* Preserve Documentation and Comments
+* Never delete or strip docstrings.
+* Never delete comments. If a comment is wrong, stale, or misleading, update it rather than removing it.
+* Only rewrite docstrings/comments for code you touched unless an untouched doc/comment is provably wrong or dangerously misleading.
+
+Rules
+- Never delete comments; update them if stale or wrong.
+- Add comments only to clarify non-obvious logic.
+- Add moderate, targeted comments for future readers when intent or invariants are not obvious.
+- Avoid narrative or redundant comments.
+- Keep comments aligned with docstrings and invariants.
+- If a comment conflicts with behavior, fix the comment and the code together.
+
+Good vs bad
+- Good: "# Guard against re-entrancy during cleanup."
+- Bad: "# Set x to 1." when the code is self-explanatory.
+
+Examples
+- agent_onboarding/user_defined/synaptic_python_developer/examples/python/anti_patterns.py
+
+
+
+
+

contextcompass_cli/_package/agent_onboarding/user_defined/synaptic_python_developer/skills/python/docstrings.md

@@ -0,0 +1,90 @@
+
+
+# docstrings
+
+Purpose
+- Ensure docstrings are contract-first, not descriptive fluff.
+
+Prime Directive: Documentation-First Edits
+Whenever you add or modify code:
+* Every class must have a rich docstring.
+* Every method/function must have a rich docstring.
+* Comments must be preserved and improved when they are unclear or insufficient.
+* Treat docstrings + comments as part of the API: they must remain accurate.
+
+Non-Negotiables
+Rich Docstrings Required (No Fluff)
+This is not optional. For all public classes and public methods, write docstrings that include real contracts, not vibes.
+
+Docstring style: follow the repo's existing style (Google / NumPy / reST). If the repo has a pattern, match it exactly.
+
+Minimum content for public API:
+* Purpose: what it does and why it exists.
+* Contract: invariants / guarantees / side effects.
+* Parameters: meaning + constraints.
+* Returns: what is returned (or None).
+* Raises: what can be raised, and under what conditions.
+* Threading / Concurrency: locks, thread-safety, reentrancy, ordering (when relevant).
+* Lifecycle / Cleanup: ownership, idempotence, teardown ordering (when relevant).
+* Examples: only when it materially clarifies usage; keep short.
+* Typing: Always add typehints to signatures, and document complex types in the docstring if needed for clarity.
+
+No fluff rule: do not write marketing copy or filler sentences. If a docstring is "rich," it's because it contains precise guarantees.
+
+Rules
+- Every public class and function must have a rich docstring.
+- Docstrings must be rich and expressive; this is a public repository.
+- Match the repo's prevailing docstring style (Google/NumPy/reST).
+- Include purpose, contract, parameters, returns, raises, threading, and lifecycle when relevant.
+- Keep language precise, stable, and testable.
+- Document ownership and cleanup responsibilities when the code manages resources.
+
+Docstring rank ladder (highest to lowest)
+- Rank 5 (Gold): full contract narrative like `normalize_names` in `agent_onboarding/user_defined/synaptic_python_developer/examples/python/docstrings.py`.
+  Includes purpose, responsibilities, invariants, workflows, args/returns/raises, and clear
+  failure modes with remediation guidance.
+- Rank 4 (Strong): complete args/returns/raises with invariants and side effects, but less
+  narrative or fewer workflow details.
+- Rank 3 (Adequate): purpose + args/returns/raises, but missing invariants or error semantics.
+- Rank 2 (Weak): short description with partial args/returns and vague error handling.
+- Rank 1 (Thin): minimal one-liner with no contract detail.
+- Rank 0 (Garbage): no docstring.
+
+Comment discipline
+- Comments must explain non-obvious logic and uphold the contract; they are part of the API.
+- Add moderate, targeted comments for future readers when behavior is not obvious from code + docstring alone.
+
+Template snippet
+```
+"""
+Purpose: One sentence on what this does and why.
+
+Contract:
+  - Invariants and guarantees.
+  - Side effects and ordering constraints.
+
+Args:
+  x (Type): Meaning and constraints.
+
+Returns:
+  Type: What is returned.
+
+Raises:
+  ValueError: When inputs violate invariants.
+"""
+```
+
+Good vs bad
+- Good: "Returns a validated FooModel; never mutates inputs."
+- Bad: "Does stuff with foo."
+
+Examples
+- agent_onboarding/user_defined/synaptic_python_developer/examples/python/docstrings.py
+
+
+
+
+
+
+
+

contextcompass_cli/_package/agent_onboarding/user_defined/synaptic_python_developer/skills/python/error_model.md

@@ -0,0 +1,28 @@
+
+
+# error_model
+
+Purpose
+- Keep error behavior explicit and documented.
+
+Rules
+- Document raises in docstrings with conditions.
+- Do not swallow exceptions silently.
+- Use clear, stable exception types.
+- Log error context when raising or translating errors.
+- Error messages must be expressive and user-facing: what failed, why, and how to fix.
+- This is a public repo, so raise messages must be safe and explanatory.
+- Use high-quality contract error messages as a reference for detail and remediation.
+- Avoid vague messages like "invalid input" without context.
+
+Example
+- Raises: ValueError when input violates invariants.
+- Logging: ERROR with target path, reason, and remediation hint.
+
+Examples
+- agent_onboarding/user_defined/synaptic_python_developer/examples/python/docstrings.py
+
+
+
+
+

contextcompass_cli/_package/agent_onboarding/user_defined/synaptic_python_developer/skills/python/hot_path_attribute_aliasing.md

@@ -0,0 +1,52 @@
+
+
+# hot_path_attribute_aliasing
+
+Purpose
+- Apply measured attribute-access rules in Python hot paths.
+
+Why this exists
+- Attribute access style can materially affect runtime in tight loops.
+- This skill encodes measured behavior so agents stop guessing and use data.
+
+Rules
+- Repeated `self` access in hot loops:
+  - Alias once (`local = self._field`) and use the local alias.
+- Method parameter flat access (`param.attr`) in hot loops:
+  - Default to direct access.
+  - Only alias if a local benchmark for that path shows a win.
+- Method parameter chained access (`param.a.b...`) with depth >= 2 in hot loops:
+  - Alias the resolved leaf once and reuse it.
+- Outside hot paths:
+  - Prefer readability and avoid unnecessary alias locals.
+
+Challenge protocol
+- If an agent disagrees with these rules, they must benchmark and provide evidence.
+- The baseline benchmark files are:
+  - `benchmarks/testing_other_di/test_local_alias_vs_direct_attr_perf.py`
+  - `context_compass/agent_onboarding/user_defined/synaptic_python_developer/skills/python/attribute_aliasing_skill_benchmark.py`
+
+Run commands
+- `python -m pytest benchmarks/testing_other_di/test_local_alias_vs_direct_attr_perf.py -q -s`
+- `python -m pytest context_compass/agent_onboarding/user_defined/synaptic_python_developer/skills/python/attribute_aliasing_skill_benchmark.py -q -s`
+
+Evidence reporting format
+- Include one table per scenario:
+  - flat `self`
+  - flat param
+  - chained `self` (depth 2/3/4)
+  - chained param (depth 2/3/4)
+- Include:
+  - iterations
+  - repeats
+  - direct ns/iter
+  - alias ns/iter
+  - alias/direct ratio
+
+Decision policy
+- If alias/direct ratio < 1.0: alias is faster.
+- If ratio is near 1.0 (noise band), keep whichever is more readable unless path is proven hot.
+
+
+
+

contextcompass_cli/_package/agent_onboarding/user_defined/synaptic_python_developer/skills/python/init_and_ownership.md

@@ -0,0 +1,35 @@
+
+
+# init_and_ownership
+
+Purpose
+- Keep initialization explicit and ownership clear.
+
+Constructor / Initialization Requirements
+When adding or modifying __init__ / initialization flows:
+* Maintain explicit ownership: it must be clear what this object owns and what it only references.
+* Initialize fields deterministically and explicitly.
+* If an attribute is optional, initialize it to None (or a clear sentinel) and document that contract.
+
+Rules
+- Initialize all attributes deterministically in __init__.
+- Optional fields must be set to None (or a sentinel) and documented.
+- Document ownership: who cleans up what and when.
+- Avoid hidden shared state; prefer instance ownership for resources.
+- If a field is injected and not owned, document that contract explicitly.
+- Dataclasses are value-only: allowed fields are None, bool, int, float, and str.
+- Do not store object instances or resources in dataclasses. If a model needs
+  objects or cleanup, use a normal class with cleanup.
+
+Checklist
+- Every field is initialized.
+- Ownership and lifecycle are described in the docstring.
+- Optional values are explicitly None.
+
+Examples
+- agent_onboarding/user_defined/synaptic_python_developer/examples/python/cleanup_patterns.py
+
+
+
+
+

contextcompass_cli/_package/agent_onboarding/user_defined/synaptic_python_developer/skills/python/interfaces.md

@@ -0,0 +1,47 @@
+
+
+# interfaces
+
+Purpose
+- Choose Protocol, ABC, or concrete types deliberately.
+
+Rules
+- Use truthful concrete types plus `typing.TYPE_CHECKING` imports by default
+  when the dependency is typing-only.
+- In Python 3.14, deferred annotations are already the default.
+  That means the concrete type name should be used directly in annotations
+  after a `TYPE_CHECKING` import, with no quotes and no `else: TypeName = Any`
+  fallback alias.
+- Use Protocol for structural typing only when multiple implementations are
+  expected and the receiving code truly depends on a shared behavioral subset.
+- Use ABC for shared behavior and explicit inheritance requirements.
+- Use concrete types when there is a single stable implementation.
+- For injected object collaborators, default to `TYPE_CHECKING` imports of the
+  concrete runtime class unless a real shared structural contract is required.
+- "Injected object collaborator" means an externally supplied object the
+  receiver uses or stores but does not construct itself.
+- Use the concrete type when the concrete runtime class is the true contract:
+  concrete-only behavior, lifecycle/identity semantics, or intentionally
+  concrete public APIs.
+- Document the interface contract in the docstring, not just the type hints.
+- Avoid widening types without a concrete compatibility reason.
+- Interfaces may be exposed in public APIs when they mirror concrete classes.
+  If exposed, the runtime object must be the concrete implementation and the
+  interface contract must stay in lockstep with it.
+- Prefer `typing.TYPE_CHECKING` over invented structural shims when the problem
+  is only import visibility. Reach for interfaces only when the structure
+  itself is the contract.
+- Do not widen those truthful concrete types to `Any` just to break an import
+  edge. If `Any` appears genuinely unavoidable, raise that conflict to the user
+  instead of silently weakening the contract.
+
+Example
+- Protocol: "Supports .acquire() and .release()" without forcing inheritance.
+- ABC: "BaseLogger" enforcing cleanup and level setting.
+
+Examples
+- agent_onboarding/user_defined/synaptic_python_developer/examples/python/protocols_and_abc.py
+
+
+
+

contextcompass_cli/_package/agent_onboarding/user_defined/synaptic_python_developer/skills/python/logging.md

@@ -0,0 +1,37 @@
+
+
+# logging
+
+Purpose
+- Ensure consistent logging discipline.
+
+
+No print() - Use the Library's Logging Pattern
+* Do not add print().
+* Use the library's logging abstraction/pattern.
+* If you cannot identify the correct logger usage, ask rather than inventing a new logging style.
+
+Rules
+- Never use print().
+- Primary logger path is `InitHelpers.resolve_channel_logger(...)` through the
+  hosted provider.
+- Explicit logger objects should be wrapped with
+  `InitHelpers.resolve_safe_logger(...)`.
+- Stdlib logging is secondary and should be registered at the provider level as
+  the basic fallback only.
+- If logger selection is unclear, raise an explicit open question and cite the
+  repository's real logger owner or logger-factory source file.
+
+Example
+- logger = InitHelpers.resolve_channel_logger(self, channels="system")
+- logger.info("message", "method_name")
+
+Examples
+- agent_onboarding/user_defined/synaptic_python_developer/examples/python/logging_patterns.py
+
+
+
+
+
+
+

contextcompass_cli/_package/agent_onboarding/user_defined/synaptic_python_developer/skills/python/module_scope.md

@@ -0,0 +1,38 @@
+
+
+# module_scope
+
+Purpose
+- Prevent hidden shared state and lifecycle confusion.
+
+Module Scope: Types + Pure Helpers Only
+* Avoid module-level mutable state (globals, caches, singletons, registries, shared clients).
+* Prefer instance-bound methods/classes for anything with ownership/lifecycle (deps, logging, concurrency, cleanup, configuration).
+* Allowed at module scope:
+  * type aliases, Protocols, ABCs, TypeVar/ParamSpec, and other generic definitions
+  * pure functions (no side effects, no hidden state, deterministic)
+* Do not add module-level constants or hidden sentinels; define constants on classes/config objects instead.
+* If a helper is not obviously pure/stateless or would introduce shared state, ask first.
+* If an existing module already uses module-level helpers, you may follow the pattern, but do not add new module globals without asking.
+
+Rules
+- Avoid module-level mutable state (globals, caches, registries).
+- Module scope is limited to type/generic definitions and pure helper functions.
+- Do not introduce module-level constants; use class attributes or config objects.
+- If a helper is not obviously pure, ask before adding.
+- Prefer instance-owned resources for anything with lifecycle or cleanup.
+
+Examples
+- Allowed: ResultT = TypeVar("ResultT")
+- Allowed: class SupportsClose(Protocol): ...
+- Allowed: def normalize_name(value: str) -> str
+- Not allowed: FOO_TIMEOUT_SECONDS = 10 (move to class/config)
+- Not allowed: mutable caches or shared client instances
+
+Examples
+- agent_onboarding/user_defined/synaptic_python_developer/examples/python/anti_patterns.py
+
+
+
+
+

contextcompass_cli/_package/agent_onboarding/user_defined/synaptic_python_developer/skills/python/refactor_limits.md

@@ -0,0 +1,44 @@
+
+
+# refactor_limits
+
+Purpose
+- Keep changes scoped and reviewable.
+
+No Drive-By Refactors
+* Do not refactor unrelated code.
+* Do not rename symbols unless explicitly requested.
+* Do not reorder code for aesthetics.
+* Do not reformat files beyond what is required for the change.
+
+Reviewability and Change Hygiene
+* Keep changes reviewable.
+* Avoid touching large numbers of files in one change unless explicitly requested.
+* When a large change is required, group it by a clear boundary (module/dir) and apply a consistent rule.
+
+Mechanical Sweeps (Repo-Wide Imports / Class Vars / Headers)
+For repo-wide mechanical edits (e.g., "add this import everywhere", "add a class variable to every class"):
+* Prefer generating a deterministic codemod script (or equivalent automated edit) rather than manually editing N files.
+* The codemod must be safe, predictable, and reviewable.
+* The goal is to avoid partial application, missed files, and "creative" edits.
+
+Public API Guardrail
+* Do not change public API shape or semantics unless explicitly requested.
+* If a public change is unavoidable, prefer:
+  * compatibility adapters/shims, and/or
+  * explicit deprecation paths with documentation.
+
+Rules
+- No drive-by refactors.
+- No renames or reordering for aesthetics.
+- Group large changes by clear module boundaries.
+- Use codemods for mechanical repo-wide edits.
+- Ask before touching many files or changing public API shape.
+- Preserve existing formatting unless required by the change.
+
+Examples
+- agent_onboarding/user_defined/synaptic_python_developer/examples/python/anti_patterns.py
+
+
+
+