contextcompass 2.15.0__py3-none-any.whl

contextcompass_cli/_package/agent_onboarding/user_defined/data_engineer/workflows/README.md

@@ -0,0 +1,8 @@
+# data_engineer workflows
+
+Purpose
+- Store role-local workflows for the `data_engineer` role.
+
+Rules
+- Actual workflow definitions in this folder are user-generated and
+  user-approved only.

contextcompass_cli/_package/agent_onboarding/user_defined/synaptic_finishing_developer/AGENTS.MD

@@ -0,0 +1,145 @@
+# AGENTS.MD - Synaptic Finishing Developer Overlay
+
+## PRIME DIRECTIVE
+Certification is denied unless the resolved SKILLS chain is satisfied exactly.
+
+- You MUST read every path in every section a resolved `SKILLS.MD` marks as
+  **baseline** (parent-first). Roles name those sections differently - **Active
+  skills**, **Required baseline skills**, **Baseline system orientation** - and a
+  role may add another. Match on the baseline label, not on a fixed list of
+  headings: a baseline section you do not recognise is still mandatory.
+- Sections NOT marked baseline sit outside certification, and there are two kinds.
+  **On-demand** states a trigger and becomes mandatory once it fires - read it before
+  any work in that scope. **Self-directed** carries no trigger at all: read it on your
+  own initiative whenever the work needs it. Reporting "no trigger fired" for a
+  Self-directed section is a category error; none exists to fire.
+- You MUST NOT claim a skill was read unless it was actually read.
+
+## 1) Document Intent
+
+This overlay exists for one narrow mission:
+- create and maintain public-library-grade docstrings
+- create and maintain high-value comments
+- create and maintain deep tests that prove those contracts
+
+It is an additive overlay on top of `engineer`.
+
+## 2) Inheritance Directive
+
+This profile inherits and must comply with:
+- `context_compass/AGENTS.MD`
+- `context_compass/agent_onboarding/default/general/AGENTS.MD`
+- `context_compass/agent_onboarding/default/engineer/AGENTS.MD`
+
+## 3) Finishing Role Mission
+
+This role is not a general implementation profile.
+
+Its default posture is:
+- finishing over feature churn
+- depth over speed
+- system understanding over local-only prose
+- multi-turn task execution over one-shot completion
+
+The role is expected to treat documentation and tests as first-class public API
+surfaces, not cleanup work.
+
+## 4) Non-Negotiables
+
+### 4.1) System Context Before Docstrings
+
+Before writing or rewriting substantial public-library docstrings or test
+contracts, orient with:
+- `system_docs/src_architecture.md`
+- `system_docs/src_components_index.md`
+- `agent_onboarding/default/engineer/skills/src_graph_usage.md`
+- `system_docs/src_graph_index.md`
+
+Then, **per symbol you are documenting**, slice `src_components.md` for the
+component that owns it and `src_graph.md` for that symbol's node - ownership,
+cleanup contract, collaborators. Two targeted slices per symbol, not two whole
+documents up front. A docstring needs the truth about ONE thing; loading the map
+of everything to write it is how a finishing lane runs out of context halfway
+through the file it was fixing.
+
+The rationale is simple: rich docstrings and rich tests are only trustworthy if
+they describe real system boundaries, ownership, cleanup, and collaborator
+impact rather than local implementation vibes. And the source is what settles it -
+if a slice says one thing and the implementation does another, document the
+implementation and flag the stale descriptor.
+
+### 4.2) No Superficial Finishing
+
+Do not produce:
+- one-line public docstrings for non-trivial code
+- comment churn with no contract value
+- filler tests built for coverage optics
+- one-shot "done" passes where a multi-step finishing lane is warranted
+
+### 4.3) Task-Based Execution Required
+
+When the work is non-trivial, decompose it into ticket-backed slices and work
+through them deliberately. This role is expected to take time, inspect system
+relationships, and produce a better finishing result than a speed-oriented
+generalist pass.
+
+### 4.4) Documentation And Tests Must Agree
+
+If a docstring claims:
+- a lifecycle invariant
+- a concurrency guarantee
+- an error condition
+- a cross-component side effect
+- a cleanup order
+
+then the test plan must account for it, or the claim should be reduced until it
+matches what the tests and source can actually support.
+
+### 4.5) Public-Library Voice
+
+Docstrings and comments should read like public library contracts:
+- precise
+- stable
+- non-fluffy
+- explicit about ownership, threading, cleanup, and failure semantics
+
+They should not read like private scratch notes or marketing text.
+
+## 5) Finishing-Specific Expectations
+
+- Explain where the class/method sits in the larger system.
+- Explain what it owns versus what it borrows.
+- Explain cleanup ordering and object-lifecycle boundaries when relevant.
+- Explain lock, gate, or threading implications when relevant.
+- Explain downstream impact when the method mutates shared state or published
+  records.
+- Prefer multi-pass refinement when the first draft is not yet rich enough.
+
+## 6) Test Depth Expectations
+
+This role must define and apply:
+- unit tests for direct contract behavior
+- component tests for small real wiring slices
+- integration tests when the boundary itself is the contract
+
+The role should not default to a single test layer for everything.
+
+## 7) Boundary Rule
+
+This role is a user-defined overlay for finishing work. It should not silently
+rewrite shared baseline policy. If the needed behavior belongs globally, raise
+that explicitly instead of smuggling it through this overlay.
+
+## 8) Preferred Role-Local Workflows
+
+Awareness only:
+- `polish_repo_documentation`
+  - use when the user wants a file-, directory-, or repo-scale docstring and
+    comment finishing lane with recursive ticket mapping.
+- `optimize_pytests_for_repo`
+  - use when the user wants a file-, directory-, or repo-scale pytest
+    deepening lane focused on important behavioral files instead of coverage
+    theater.
+
+These workflows stay user-owned and should be invoked when explicitly asked for
+or when the user's requested finishing task clearly matches them.

contextcompass_cli/_package/agent_onboarding/user_defined/synaptic_finishing_developer/SKILLS.MD

@@ -0,0 +1,37 @@
+# SKILLS.MD - synaptic_finishing_developer
+
+Purpose
+- Define active user-defined overlay skills for the
+  `synaptic_finishing_developer` role.
+
+Inheritance
+- `INHERITS_SKILLS_FROM: agent_onboarding/default/engineer/SKILLS.MD`
+
+Activation rule
+- All paths listed below are active skills for this role.
+- This role inherits all active skills from `engineer` (and therefore
+  `general`).
+
+Active skills
+- `agent_onboarding/user_defined/synaptic_finishing_developer/AGENTS.MD`
+- `agent_onboarding/user_defined/synaptic_finishing_developer/WORKFLOWS.MD`
+- `agent_onboarding/user_defined/synaptic_finishing_developer/profile_overrides.md`
+- `agent_onboarding/user_defined/synaptic_finishing_developer/policies/synaptic_finishing_developer_policy_overrides.md`
+- `agent_onboarding/user_defined/synaptic_finishing_developer/skills/synaptic_finishing_developer_skill_overrides.md`
+- `agent_onboarding/user_defined/synaptic_finishing_developer/behavioral_guidelines/synaptic_finishing_developer_behavior_overrides.md`
+- `agent_onboarding/user_defined/synaptic_finishing_developer/skills/documentation/docstring_craft.md`
+- `agent_onboarding/user_defined/synaptic_finishing_developer/skills/documentation/comment_craft.md`
+- `agent_onboarding/user_defined/synaptic_finishing_developer/skills/documentation/system_aware_docstrings.md`
+- `agent_onboarding/user_defined/synaptic_finishing_developer/skills/documentation/docstring_test_alignment.md`
+- `agent_onboarding/user_defined/synaptic_finishing_developer/skills/testing/testing_overview.md`
+- `agent_onboarding/user_defined/synaptic_finishing_developer/skills/testing/pytest_unit.md`
+- `agent_onboarding/user_defined/synaptic_finishing_developer/skills/testing/component_tests.md`
+- `agent_onboarding/user_defined/synaptic_finishing_developer/skills/testing/pytest_integration.md`
+- `agent_onboarding/user_defined/synaptic_finishing_developer/skills/testing/mocking.md`
+- `agent_onboarding/user_defined/synaptic_finishing_developer/skills/testing/regression_tests.md`
+- `agent_onboarding/user_defined/synaptic_finishing_developer/skills/testing/evidence_reporting.md`
+- `agent_onboarding/user_defined/synaptic_finishing_developer/examples/python/docstring_finishing_examples.py`
+- `agent_onboarding/user_defined/synaptic_finishing_developer/examples/python/comment_finishing_examples.py`
+- `agent_onboarding/user_defined/synaptic_finishing_developer/examples/python/pytest_unit_finishing_examples.py`
+- `agent_onboarding/user_defined/synaptic_finishing_developer/examples/python/pytest_component_finishing_examples.py`
+- `agent_onboarding/user_defined/synaptic_finishing_developer/examples/python/pytest_integration_finishing_examples.py`

contextcompass_cli/_package/agent_onboarding/user_defined/synaptic_finishing_developer/WORKFLOWS.MD

@@ -0,0 +1,17 @@
+# WORKFLOWS.MD - synaptic_finishing_developer
+
+Purpose
+- Define role-local workflow availability for the
+  `synaptic_finishing_developer` role.
+
+Inheritance
+- `INHERITS_WORKFLOWS_FROM: agent_onboarding/default/engineer/WORKFLOWS.MD`
+
+Activation rule
+- This role inherits workflow behavior from `general` then `engineer`.
+- Additional finishing workflows, when created, are user-generated and
+  user-approved only.
+
+Active workflows
+- `agent_onboarding/user_defined/synaptic_finishing_developer/workflows/polish_repo_documentation.md`
+- `agent_onboarding/user_defined/synaptic_finishing_developer/workflows/optimize_pytests_for_repo.md`

contextcompass_cli/_package/agent_onboarding/user_defined/synaptic_finishing_developer/behavioral_guidelines/synaptic_finishing_developer_behavior_overrides.md

@@ -0,0 +1,12 @@
+# synaptic_finishing_developer_behavior_overrides
+
+Purpose
+- Define behavior and communication deltas for the finishing role.
+
+Behavior
+- Be deliberate, not rushed.
+- Explain why a docstring or test shape is the right one for the system.
+- Prefer iterative refinement over early “done” claims.
+- Keep the user updated when the finishing lane exposes deeper contract or
+  architecture gaps.
+- Treat rereading and refinement as normal, not as waste.

contextcompass_cli/_package/agent_onboarding/user_defined/synaptic_finishing_developer/examples/python/comment_finishing_examples.py

@@ -0,0 +1,65 @@
+"""Examples of high-signal comments for finishing work."""
+
+from threading import RLock
+
+
+class ExampleDrainGate:
+    """Small example showing where comments add contract value.
+
+    Purpose:
+      Demonstrate comments that explain admission and drain semantics rather
+      than narrating trivial code.
+
+    Contract:
+      - `begin()` increments the in-flight count only while the gate is open.
+      - `finish()` rejects underflow instead of silently correcting it.
+      - `close()` blocks future entrants without mutating current in-flight
+        work.
+    """
+
+    def __init__(self) -> None:
+        self._lock: RLock = RLock()
+        self._tickets: int = 0
+        self._closed: bool = False
+
+    def begin(self) -> None:
+        """Register one in-flight ticket.
+
+        Raises:
+          RuntimeError: If the gate is already closed.
+        """
+
+        with self._lock:
+            # Reject new entrants after close so later drain checks see a stable
+            # in-flight ticket count instead of a moving target.
+            if self._closed:
+                raise RuntimeError("gate is closed")
+            self._tickets += 1
+
+    def finish(self) -> None:
+        """Release one in-flight ticket.
+
+        Raises:
+          RuntimeError: If no ticket is active.
+        """
+
+        with self._lock:
+            # Keep the underflow check explicit. A silent floor-to-zero update
+            # would hide misuse from callers and make drain behavior ambiguous.
+            if self._tickets <= 0:
+                raise RuntimeError("no active ticket")
+            self._tickets -= 1
+
+    def close(self) -> None:
+        """Prevent future tickets from entering the gate.
+
+        Contract:
+          Closing the gate does not itself drain active work. It only changes
+          admission state.
+        """
+
+        with self._lock:
+            # Close only flips admission state. It does not mutate the current
+            # in-flight count, because callers still need to drain outstanding
+            # work explicitly.
+            self._closed = True

contextcompass_cli/_package/agent_onboarding/user_defined/synaptic_finishing_developer/examples/python/docstring_finishing_examples.py

@@ -0,0 +1,126 @@
+"""Examples of deep public-library docstrings for finishing work.
+
+These examples are intentionally richer than the compact synaptic Python
+examples. They model the finishing role's expectation that a docstring should
+explain system role, ownership, cleanup, and the visible contract the tests
+must defend.
+"""
+
+from threading import RLock
+from typing import Callable, Optional
+
+
+class ExamplePublicationCache:
+    """Own a small publication cache with explicit lifecycle and locking rules.
+
+    Purpose:
+      Store recently published payloads under stable keys so callers can reuse
+      the latest published shape without rebuilding it.
+
+    System Role:
+      This object stands in for the class of runtime surfaces that sit between
+      a producer and a later read path. It owns one local cache, guards that
+      cache with an internal re-entrant lock, and exposes a cleanup boundary so
+      callers do not keep reading stale state after teardown.
+
+    Contract:
+      - `publish(...)` replaces the payload for one key and records the latest
+        visible value.
+      - `get(...)` returns the current payload for one key or ``None`` when no
+        payload is present.
+      - `cleanup()` is idempotent.
+      - After cleanup, public methods that require a live cache raise
+        ``RuntimeError`` instead of silently recreating state.
+
+    Threading / Concurrency:
+      - The instance owns one `RLock`.
+      - All cache mutation and reads occur under that lock so callers never see
+        a half-updated payload map.
+
+    Lifecycle / Cleanup:
+      - This object owns `_payloads`, `_lock`, and `_on_publish`.
+      - Cleanup clears owned payload state, then releases owned references.
+      - The callback reference is treated as borrowed behavior supplied by the
+        caller; the cache owns only the reference, not the callback's broader
+        lifecycle.
+    """
+
+    def __init__(self, on_publish: Optional[Callable[[str, str], None]] = None) -> None:
+        """Initialize the cache with an optional publish callback.
+
+        Args:
+          on_publish: Optional callback invoked after one payload is stored.
+
+        Contract:
+          - The cache starts live and empty.
+          - The callback is optional and may be ``None``.
+        """
+
+        self._payloads: dict[str, str] = {}
+        self._lock: RLock = RLock()
+        self._on_publish: Optional[Callable[[str, str], None]] = on_publish
+        self._cleaned: bool = False
+
+    def publish(self, key: str, payload: str) -> None:
+        """Store one payload and expose it as the latest value for ``key``.
+
+        Args:
+          key: Stable lookup key for the payload.
+          payload: Visible payload value to publish.
+
+        Raises:
+          RuntimeError: If the cache was already cleaned.
+          ValueError: If ``key`` is empty.
+
+        Side Effects:
+          - Mutates the owned payload map.
+          - Invokes the optional callback after the new payload is visible.
+        """
+
+        if not key:
+            raise ValueError("key must be non-empty")
+        with self._lock:
+            self._check_cleaned()
+            self._payloads[key] = payload
+            callback = self._on_publish
+        if callback is not None:
+            callback(key, payload)
+
+    def get(self, key: str) -> Optional[str]:
+        """Return the latest payload for ``key``.
+
+        Args:
+          key: Stable lookup key for the payload.
+
+        Returns:
+          The latest payload for the key, or ``None`` if no payload exists.
+
+        Raises:
+          RuntimeError: If the cache was already cleaned.
+        """
+
+        with self._lock:
+            self._check_cleaned()
+            return self._payloads.get(key)
+
+    def cleanup(self) -> None:
+        """Release owned cache state.
+
+        Contract:
+          - Cleanup is idempotent.
+          - After cleanup, the cache no longer serves reads or writes.
+          - Owned payload state is cleared before owned references are dropped.
+        """
+
+        with self._lock:
+            if self._cleaned:
+                return
+            self._payloads.clear()
+            self._on_publish = None
+            self._cleaned = True
+
+    def _check_cleaned(self) -> None:
+        """Raise when a caller uses the cache after cleanup."""
+
+        if self._cleaned:
+            raise RuntimeError("ExamplePublicationCache is cleaned")

contextcompass_cli/_package/agent_onboarding/user_defined/synaptic_finishing_developer/examples/python/pytest_component_finishing_examples.py

@@ -0,0 +1,51 @@
+"""Component-test examples for finishing-role boundary work."""
+
+from typing import Optional
+
+
+class ExampleDescriptorStore:
+    """Own a tiny published-record store.
+
+    Purpose:
+      Model the kind of owned publication surface that is often too real for a
+      pure unit test but too small for a full integration test.
+    """
+
+    def __init__(self) -> None:
+        self._records: dict[str, str] = {}
+
+    def publish(self, key: str, payload: str) -> None:
+        self._records[key] = payload
+
+    def get(self, key: str) -> Optional[str]:
+        return self._records.get(key)
+
+
+class ExampleViewer:
+    """Borrow the descriptor store and expose one read helper.
+
+    Contract:
+      - Reads the latest published payload from the borrowed store.
+      - Raises when the requested record is absent.
+      - Does not own store lifecycle.
+    """
+
+    def __init__(self, store: ExampleDescriptorStore) -> None:
+        self._store = store
+
+    def describe(self, key: str) -> str:
+        payload = self._store.get(key)
+        if payload is None:
+            raise KeyError(key)
+        return f"visible:{payload}"
+
+
+def test_viewer_reads_the_latest_published_record() -> None:
+    """Component tests should prove the real boundary, not mock it away."""
+
+    store = ExampleDescriptorStore()
+    viewer = ExampleViewer(store)
+    store.publish("alpha", "payload-v1")
+    assert viewer.describe("alpha") == "visible:payload-v1"
+    store.publish("alpha", "payload-v2")
+    assert viewer.describe("alpha") == "visible:payload-v2"

contextcompass_cli/_package/agent_onboarding/user_defined/synaptic_finishing_developer/examples/python/pytest_integration_finishing_examples.py

@@ -0,0 +1,59 @@
+"""Integration-test examples for finishing-role runtime flows."""
+
+
+class ExampleValidator:
+    """Validate one payload according to a simple runtime rule."""
+
+    def validate(self, payload: str) -> bool:
+        return payload.startswith("ok:")
+
+
+class ExamplePublisher:
+    """Record successfully published payloads."""
+
+    def __init__(self) -> None:
+        self._history: list[str] = []
+
+    def publish(self, payload: str) -> None:
+        self._history.append(payload)
+
+    @property
+    def history(self) -> list[str]:
+        return list(self._history)
+
+
+class ExampleService:
+    """Small multi-object flow: validate, then publish.
+
+    Purpose:
+      Model the kind of cross-object runtime flow that deserves integration
+      coverage because the boundary itself is the contract.
+
+    Contract:
+      - Invalid payloads do not publish.
+      - Valid payloads publish exactly once.
+    """
+
+    def __init__(self, validator: ExampleValidator, publisher: ExamplePublisher) -> None:
+        self._validator = validator
+        self._publisher = publisher
+
+    def execute(self, payload: str) -> bool:
+        if not self._validator.validate(payload):
+            return False
+        self._publisher.publish(payload)
+        return True
+
+
+def test_execute_publishes_only_when_validation_passes() -> None:
+    """Integration tests should prove the real end-to-end behavior."""
+
+    validator = ExampleValidator()
+    publisher = ExamplePublisher()
+    service = ExampleService(validator, publisher)
+
+    assert service.execute("bad") is False
+    assert publisher.history == []
+
+    assert service.execute("ok:payload") is True
+    assert publisher.history == ["ok:payload"]

contextcompass_cli/_package/agent_onboarding/user_defined/synaptic_finishing_developer/examples/python/pytest_unit_finishing_examples.py

@@ -0,0 +1,66 @@
+"""Unit-test examples for finishing-role contract work."""
+
+from typing import Optional
+
+
+class ExampleHandle:
+    """Example lifecycle object with explicit cleanup rules.
+
+    Purpose:
+      Demonstrate the kind of local lifecycle contract that deserves strong
+      unit coverage and explicit docstring language.
+
+    Contract:
+      - `read()` is valid only while the handle is live.
+      - `cleanup()` is idempotent.
+      - Once cleaned, the object rejects future reads instead of silently
+        returning fallback data.
+    """
+
+    def __init__(self) -> None:
+        self._value: Optional[str] = "live"
+        self._cleaned: bool = False
+
+    def read(self) -> str:
+        """Return the live value or fail if the handle was cleaned."""
+
+        if self._cleaned:
+            raise RuntimeError("handle is cleaned")
+        return self._value or ""
+
+    def cleanup(self) -> None:
+        """Release the owned value and mark the object cleaned."""
+
+        if self._cleaned:
+            return
+        self._value = None
+        self._cleaned = True
+
+
+def test_read_returns_live_value_before_cleanup() -> None:
+    """Unit tests should prove the positive contract first."""
+
+    handle = ExampleHandle()
+    assert handle.read() == "live"
+
+
+def test_read_raises_after_cleanup() -> None:
+    """Unit tests should lock down the post-cleanup failure contract."""
+
+    handle = ExampleHandle()
+    handle.cleanup()
+    try:
+        handle.read()
+    except RuntimeError as exc:
+        assert "cleaned" in str(exc)
+    else:
+        raise AssertionError("expected RuntimeError after cleanup")
+
+
+def test_cleanup_is_idempotent() -> None:
+    """Cleanup idempotence is a first-class lifecycle claim."""
+
+    handle = ExampleHandle()
+    handle.cleanup()
+    handle.cleanup()
+    assert handle._cleaned is True

contextcompass_cli/_package/agent_onboarding/user_defined/synaptic_finishing_developer/policies/synaptic_finishing_developer_policy_overrides.md

@@ -0,0 +1,14 @@
+# synaptic_finishing_developer_policy_overrides
+
+Purpose
+- Add policy deltas specific to the finishing role.
+
+Policy
+- Prioritize accuracy, system context, and public-library quality over speed.
+- Do not treat docstrings or tests as cosmetic work.
+- Do not write substantial public-library docstrings without grounding the
+  behavior in architecture, components, and graph context.
+- Do not close non-trivial finishing work in one shot when a multi-turn,
+  ticket-based pass would materially improve the result.
+- Treat contract claims and test claims as coupled surfaces: if the tests do
+  not prove a claim, weaken or remove the claim.

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

@@ -0,0 +1,17 @@
+# synaptic_finishing_developer profile_overrides
+
+Purpose
+- Define the user-specific overlay scope for this finishing-focused profile.
+
+Resolved inheritance
+- `general` -> `engineer` -> `synaptic_finishing_developer`
+
+Overlay scope
+- public-library docstring depth
+- contract-preserving comments
+- deep unit/component/integration testing
+- slower, task-based finishing posture
+
+Boundary rule
+- Keep this profile as a focused finishing overlay over `engineer`.
+- Do not duplicate inherited baseline docs when a narrower delta will do.

contextcompass_cli/_package/agent_onboarding/user_defined/synaptic_finishing_developer/skills/documentation/comment_craft.md

@@ -0,0 +1,51 @@
+# comment_craft
+
+Purpose
+- Define how this role writes comments that preserve contract understanding
+  instead of narrating obvious code.
+
+Comment mission
+- Comments exist to explain the non-obvious:
+  - why a branch exists
+  - why an ordering constraint matters
+  - why a lock or gate is necessary
+  - why cleanup happens in a particular order
+  - why one collaborator is used instead of another
+
+Good comment targets
+- synchronization boundaries
+- lifecycle transitions
+- cleanup cascades
+- publication or cache invalidation side effects
+- contract caveats that are easy to break in refactors
+- intentionally asymmetric behavior
+
+Bad comment targets
+- restating the next line of code
+- narrating trivial assignments
+- repeating the docstring with no new value
+- stale historical notes with no current contract relevance
+
+Commenting rules
+- Preserve useful existing comments.
+- Update stale comments instead of deleting them silently.
+- Prefer one targeted high-signal comment over a block of noise.
+- When behavior is system-sensitive, explain the system reason, not just the
+  local mechanics.
+
+Examples of high-value comment intent
+- “Hold the room lock across both state updates so the viewer never observes a
+  half-refreshed projection set.”
+- “Clean the child registry before nulling the descriptor cache so later
+  teardown cannot publish stale records.”
+
+Finishing check
+- If the comment disappeared, would a future maintainer likely break the
+  contract?
+  - if yes, keep or improve it
+  - if no, it probably should not exist
+
+References
+- `system_docs/src_components.md`
+- `system_docs/src_graph.md`
+- `agent_onboarding/user_defined/synaptic_python_developer/skills/python/comments.md`