contextcompass 2.15.0__py3-none-any.whl

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

@@ -0,0 +1,86 @@
+# docstring_craft
+
+Purpose
+- Define how this role writes public-library docstrings that are rich,
+  system-aware, and worth rereading later.
+
+Finishing stance
+- A good docstring is not a local summary.
+- It explains why the symbol exists, what it guarantees, what it owns, what it
+  borrows, and how it behaves inside the wider system.
+
+Mandatory pre-write loop
+1) Identify the symbol's system role:
+   - which subsystem it belongs to
+   - what layer it sits in
+   - what other objects depend on it
+2) Identify its contract:
+   - invariants
+   - valid inputs
+   - outputs
+   - raises
+   - side effects
+3) Identify its operational context:
+   - threading/locks/gates
+   - lifecycle/cleanup ordering
+   - registration/publication impacts
+4) Identify what tests should prove those claims.
+
+Required public-library sections
+- Purpose:
+  - what it does
+  - why it exists
+- System Role:
+  - where it sits in the architecture/components graph
+  - what it collaborates with
+- Contract:
+  - invariants and guarantees
+  - what is stable for callers
+- Args / Returns / Raises:
+  - explicit and precise
+- Threading / Concurrency:
+  - locks, gates, ordering, reentrancy, or why none apply
+- Lifecycle / Cleanup:
+  - ownership
+  - teardown ordering
+  - idempotence expectations
+- Side Effects / State Impact:
+  - registry mutation
+  - descriptor/publication changes
+  - dirty-state or validation effects
+
+When to go deeper
+- Use richer narrative when the symbol:
+  - coordinates multiple collaborators
+  - mutates shared system state
+  - participates in cleanup/lifecycle
+  - gates validation or concurrency
+  - sits on a public surface that future readers will rely on
+
+Non-negotiables
+- Do not write one-liner public docstrings for non-trivial code.
+- Do not describe only mechanics if the system role matters.
+- Do not promise guarantees the tests and source do not support.
+- Do not ignore cleanup or concurrency when they are part of the contract.
+
+Docstring quality ladder
+- Gold:
+  - purpose, system role, contract, lifecycle, threading, failure semantics,
+    and testable guarantees
+- Strong:
+  - complete contract sections with less system narrative
+- Adequate:
+  - basic args/returns/raises but missing deeper system or lifecycle detail
+- Weak:
+  - only local mechanics, little contract value
+
+Review questions
+- Could a new engineer understand why this symbol matters in the system?
+- Could a tester derive a meaningful test plan from the docstring?
+- Would a harmless refactor keep this docstring true?
+
+References
+- `system_docs/src_architecture.md`
+- `system_docs/src_components.md`
+- `system_docs/src_graph.md`
+- `agent_onboarding/user_defined/synaptic_python_developer/skills/python/docstrings.md`

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

@@ -0,0 +1,51 @@
+# docstring_test_alignment
+
+Purpose
+- Define how documentation claims and tests should reinforce each other.
+
+Core rule
+- If a docstring makes a meaningful claim, the test strategy should account for
+  it.
+
+Map docstring claims to test layers
+- Args / Returns / Raises:
+  - usually unit tests
+- Lifecycle and cleanup:
+  - unit tests first
+  - component tests when cleanup crosses a real collaborator boundary
+- Threading / locking / gating:
+  - unit tests when isolated behavior is enough
+  - component or integration tests when real coordination is the contract
+- Cross-component side effects:
+  - component tests first
+  - integration tests when broader orchestration is required
+- Regression notes or bug history:
+  - dedicated regression tests
+
+Alignment loop
+1) Draft or revise the docstring.
+2) Extract the meaningful guarantees.
+3) Decide which guarantees need unit, component, or integration coverage.
+4) Add or update tests until the strongest public claims are actually proven.
+5) Reduce any docstring claims that the current test plan cannot support.
+
+What this role should look for
+- docstring says cleanup is idempotent:
+  - add idempotent cleanup tests
+- docstring says method is non-throwing after cleanup:
+  - add post-cleanup tests
+- docstring says registry write triggers publication/refresh:
+  - add component or integration coverage
+- docstring says method holds a lock or requires ordered mutation:
+  - add tests around the visible consequence of that guarantee
+
+Anti-patterns
+- strong docstring claims with no matching tests
+- rich tests that prove behavior the docstring never documents
+- coverage-only tests that do not support the documented contract
+
+References
+- `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`

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

@@ -0,0 +1,64 @@
+# system_aware_docstrings
+
+Purpose
+- Force docstring writing to account for the larger system instead of treating
+  methods and classes as isolated islands.
+
+Required read surfaces
+- `system_docs/src_architecture.md` - read whole
+- `system_docs/src_components_index.md` - then slice `src_components.md`
+- `agent_onboarding/default/engineer/skills/src_graph_usage.md`
+- `system_docs/src_graph_index.md` - then slice `src_graph.md`
+
+"Surface" means a place you go with a question, not a document you ingest. Each
+one below is entered through its index and sliced to the symbol you are
+documenting. On a real repository the components map and the graph run to ~8,400
+and ~25,000 lines; a docstring needs the truth about one symbol.
+
+Use each surface for a different question
+- `src_architecture.md`
+  - What system layer is this in?
+  - What is the top-level purpose?
+  - What invariants and failure modes matter globally?
+- `src_components.md`
+  - What owns this object?
+  - What does it create, validate, publish, or bind?
+  - What are the method-level call flows?
+- `src_graph.md`
+  - What does this object own?
+  - What does it borrow?
+  - What does it create?
+  - What edges imply lifecycle responsibility?
+
+System-aware docstring pattern
+1) Start from the symbol under edit.
+2) Map it to its component and subsystem.
+3) Check ownership and borrowing relationships in the graph.
+4) Reconcile that with the code and call flow.
+5) Write the docstring so it explains the symbol's place in that structure.
+
+What to include when system context matters
+- upstream owner
+- downstream consumers
+- whether it owns lifecycle or only borrows
+- shared-state or registry side effects
+- validation or publication effects
+- why its contract matters beyond the local file
+
+What to avoid
+- claiming ownership when the graph shows borrowing
+- hiding cleanup responsibility when the component docs make it explicit
+- writing local-only descriptions for symbols that coordinate multiple layers
+- inventing guarantees that the architecture/docs/code do not support
+
+Unknowns rule
+- If the architecture, components, and graph do not line up cleanly with the
+  code, do not bluff.
+- Investigate further or keep the claim out of the docstring until it is
+  evidenced.
+
+References
+- `system_docs/src_architecture.md`
+- `system_docs/src_components.md`
+- `agent_onboarding/default/engineer/skills/src_graph_usage.md`
+- `system_docs/src_graph.md`

contextcompass_cli/_package/agent_onboarding/user_defined/synaptic_finishing_developer/skills/synaptic_finishing_developer_skill_overrides.md

@@ -0,0 +1,11 @@
+# synaptic_finishing_developer_skill_overrides
+
+Purpose
+- Define the role-local skill posture for finishing work.
+
+Skills
+- Use system context to enrich docstrings, not just local code shape.
+- Use tests to prove documentation claims, not just to pad coverage.
+- Split work into tasks when the finishing surface spans multiple classes,
+  methods, or test layers.
+- Optimize for maximum contract clarity and regression value.

contextcompass_cli/_package/agent_onboarding/user_defined/synaptic_finishing_developer/skills/testing/component_tests.md

@@ -0,0 +1,45 @@
+# component_tests
+
+Purpose
+- Define component tests as a first-class layer between unit and integration
+  testing for finishing work.
+
+Component-test definition
+- A component test uses a small real slice of collaborators to prove a
+  meaningful boundary without dragging in the whole system.
+
+Use component tests when
+- a public contract depends on a few real collaborators
+- a docstring describes behavior across a local boundary
+- ownership, publication, refresh, or registry behavior is real but bounded
+- unit mocks would re-implement the system instead of testing it
+
+Examples of good component-test targets
+- descriptor manager + published record behavior
+- viewer/command/workstation interaction in one room slice
+- cleanup cascade across one parent and its owned children
+- ACL compile/validate behavior across a small real bundle
+
+Component-test rules
+- Keep the slice small and intentional.
+- Use real collaborators where that materially increases signal.
+- Do not pull in the whole runtime when a smaller slice proves the contract.
+- Keep setup explicit and deterministic.
+- Prefer clear boundary assertions over broad snapshot dumps.
+
+Placement
+- component tests belong in `tests/component/`
+
+How component tests support docstrings
+- They prove "this object coordinates X with Y" claims.
+- They prove publication or refresh side effects.
+- They prove ownership boundaries where multiple real objects interact.
+
+Anti-patterns
+- component tests that are really oversized integration tests
+- component tests that still mock every meaningful collaborator
+- component tests that assert a giant object dump instead of boundary behavior
+
+References
+- `agent_onboarding/default/qa_engineer/skills/test_strategy_and_planning.md`
+- `agent_onboarding/user_defined/synaptic_python_developer/skills/testing/testing_overview.md`

contextcompass_cli/_package/agent_onboarding/user_defined/synaptic_finishing_developer/skills/testing/evidence_reporting.md

@@ -0,0 +1,25 @@
+# evidence_reporting
+
+Purpose
+- Define truthful reporting rules for finishing-role validation claims.
+
+Rules
+- Never claim tests ran unless they actually ran.
+- If tests were not run, report exactly `Not run.`
+- Never guess at coverage numbers.
+- If coverage was not measured, say so explicitly.
+- Recommend exact repo-consistent commands when useful.
+
+Recommended command references
+- `pytest`
+- `pytest -q`
+- `pytest -m integration`
+- `pytest --cov`
+
+Finishing-role emphasis
+- Because this role is documentation-heavy, false validation claims are
+  especially damaging. They make both the tests and the docstrings less
+  trustworthy.
+
+References
+- `agent_onboarding/user_defined/synaptic_python_developer/skills/testing/evidence_reporting.md`

contextcompass_cli/_package/agent_onboarding/user_defined/synaptic_finishing_developer/skills/testing/mocking.md

@@ -0,0 +1,35 @@
+# mocking
+
+Purpose
+- Define how this role uses mocks without hollowing out the contract being
+  tested.
+
+Mock only true boundaries
+- filesystem
+- subprocess
+- network
+- time
+- randomness
+- OS/platform seams
+
+Do not mock
+- the core logic you are trying to prove
+- private fields just to make a test easy
+- collaboration details that are not part of the public contract
+
+Finishing-role rule
+- If a docstring claims collaboration behavior, mock only the external edge and
+  assert the visible contract consequence, not an incidental internal call list.
+
+Good mocking
+- one boundary call with essential arguments
+- deterministic time/random control
+- cheap stand-ins for expensive external dependencies
+
+Bad mocking
+- long ordered call chains that would break under harmless refactors
+- fake implementations that duplicate real logic
+- mocks used to avoid writing the right component test
+
+References
+- `agent_onboarding/user_defined/synaptic_python_developer/skills/testing/mocking.md`

contextcompass_cli/_package/agent_onboarding/user_defined/synaptic_finishing_developer/skills/testing/pytest_integration.md

@@ -0,0 +1,32 @@
+# pytest_integration
+
+Purpose
+- Define when this role should escalate from unit/component tests to
+  integration tests.
+
+Use integration tests when
+- the real boundary is multi-component orchestration
+- concurrency or gating behavior depends on real interaction
+- serializer, adapter, or runtime wiring behavior is itself the contract
+- unit or component tests would become fake by mocking too much
+
+Integration-test rules
+- Keep scope minimal but real.
+- Use the smallest real set of components that proves the contract.
+- Make the boundary under test explicit in the test name and setup.
+- Avoid environmental flakiness unless the environment is part of the contract.
+- Mark integration tests clearly if the repo uses markers.
+
+Finishing-role emphasis
+- Reach for integration tests when the docstring or system docs describe a
+  runtime flow that spans multiple owned/borrowed boundaries and a component
+  slice is not enough.
+
+Examples
+- real revalidation flow across spell/system state and change control
+- real room command -> codegen engine -> memory/event emission flow
+- real refresh/gate coordination when that is the contract under discussion
+
+References
+- `agent_onboarding/user_defined/synaptic_python_developer/skills/testing/pytest_integration.md`
+- `agent_onboarding/default/qa_engineer/skills/regression_and_release_quality.md`

contextcompass_cli/_package/agent_onboarding/user_defined/synaptic_finishing_developer/skills/testing/pytest_unit.md

@@ -0,0 +1,49 @@
+# pytest_unit
+
+Purpose
+- Define how this role writes unit tests for public-library contract work.
+
+Unit-test mission
+- Prove the direct contract of the class or method under test:
+  - outputs
+  - raises
+  - invariants
+  - lifecycle behavior
+  - cleanup semantics
+
+What unit tests should target first
+- return values and visible state changes
+- invalid inputs and error messages
+- idempotent cleanup
+- post-cleanup behavior
+- state-transition legality
+- public methods that enforce ownership or borrowing boundaries
+
+When unit tests are enough
+- when the behavior can be proved without real collaborator wiring
+- when the contract is local and deterministic
+- when mocking true external boundaries does not hide the real behavior
+
+Unit-test rules
+- Use pytest fixtures for setup and teardown.
+- Prefer public APIs over private fields.
+- Assert behavior, not incidental shape.
+- Include error-path coverage when the docstring promises it.
+- Prefer a few high-signal tests over a carpet of filler assertions.
+
+Finishing-role emphasis
+- If the docstring mentions:
+  - cleanup ordering
+  - non-throwing cleanup
+  - fail-fast invalid state
+  - explicit error remediation
+  then the unit test suite should reflect that.
+
+Bad unit tests
+- attribute existence checks
+- implementation-detail snapshots with no contract value
+- “did not crash” assertions with no stronger claim
+
+References
+- `agent_onboarding/user_defined/synaptic_finishing_developer/skills/documentation/docstring_craft.md`
+- `agent_onboarding/user_defined/synaptic_python_developer/skills/testing/pytest_unit.md`

contextcompass_cli/_package/agent_onboarding/user_defined/synaptic_finishing_developer/skills/testing/regression_tests.md

@@ -0,0 +1,24 @@
+# regression_tests
+
+Purpose
+- Define how this role writes regression tests that lock down previously
+  observed failures without overfitting to implementation details.
+
+Rules
+- Name the test after the symptom.
+- Keep the reproduction minimal.
+- Assert the corrected behavior, not the internal workaround.
+- Prefer a regression test whenever a docstring or comment is updated to record
+  a historically broken contract.
+
+High-value regression signals
+- bug symptom is obvious from the test name
+- failure is reproducible in a small setup
+- the final assertion matches the public contract the repo wants to keep
+
+Finishing-role emphasis
+- If documentation becomes more explicit because a bug taught us something,
+  pair that stronger documentation with a regression test whenever practical.
+
+References
+- `agent_onboarding/user_defined/synaptic_python_developer/skills/testing/regression_tests.md`

contextcompass_cli/_package/agent_onboarding/user_defined/synaptic_finishing_developer/skills/testing/testing_overview.md

@@ -0,0 +1,71 @@
+# testing_overview
+
+Purpose
+- Define the finishing-role testing taxonomy and the depth bar for
+  public-library contracts.
+
+Testing stance
+- We do not optimize for speed here.
+- We optimize for:
+  - contract coverage
+  - lifecycle coverage
+  - error-path coverage
+  - cross-component behavior when the contract spans real collaborators
+
+Primary test layers
+- Unit:
+  - default first move
+  - direct contract behavior
+  - error semantics
+  - cleanup and state transitions
+- Component:
+  - small real wiring slices
+  - preferred when a public contract depends on a few real collaborators
+  - bridges the gap between isolated unit tests and broader integration tests
+- Integration:
+  - use when the boundary itself is the contract
+  - use when concurrency/orchestration/serialization cannot be proved safely
+    with unit or component tests
+
+Finishing-role rule
+- The test plan should be derived from the documented contract, not from a
+  desire to "get coverage up."
+
+What high-value tests look like
+- they fail for a real regression
+- they survive harmless refactors
+- they prove a public or architectural contract
+- they help keep docstrings honest
+
+Depth expectations
+- unit tests should cover:
+  - returns
+  - raises
+  - invariants
+  - cleanup
+  - state transitions
+- component tests should cover:
+  - owner/borrower interactions
+  - descriptor/publication/refresh boundaries
+  - command/viewer/workstation or similar small real slices
+- integration tests should cover:
+  - real orchestration boundaries
+  - real concurrency contracts
+  - real multi-component runtime flows
+
+Slow-finishing expectation
+- For non-trivial surfaces, do not stop after one test pass.
+- Revisit the contract after the first tests and ask:
+  - what remains unproven?
+  - what docstring claims are still too strong?
+  - what layer needs one more slice?
+
+Validation truthfulness
+- Never imply tests ran if they did not.
+- If not run, say `Not run.` exactly.
+- Coverage numbers require actual measurement; do not guess.
+
+References
+- `agent_onboarding/user_defined/synaptic_finishing_developer/skills/documentation/docstring_test_alignment.md`
+- `agent_onboarding/user_defined/synaptic_python_developer/skills/testing/testing_overview.md`
+- `agent_onboarding/default/qa_engineer/skills/test_strategy_and_planning.md`

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

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