Refactor flock objects to inherit from closure_collector core objects

SESSION_INSTRUCTIONS.md

@@ -1,29 +1,37 @@
-# Session Instructions and Guidelines
+# Session Instructions
 
-During this development session, several key architectural, tooling, and stylistic decisions were made and enforced. These guidelines should inform future work in this repository:
+This file documents the initial instructions and interaction patterns provided in this session. These instructions can be used as a prompt to establish a rigorous planning and execution workflow in future sessions.
 
-## 1. Tooling and Linting
+## The Prompt
 
-- **Ruff:** We use `ruff` as our primary linter and formatter. Auto-generated or placeholder docstrings (e.g., `"""Module providing X implementation."""` or `"""Execute the Y operation."""`) are strictly prohibited, as they trigger reviewer rejections. All `ruff` `D` checks (docstrings) must be satisfied with **meaningful, context-aware descriptions**.
-- **Mypy:** We use `mypy` for static type checking. Due to the highly dynamic and metaprogramming-heavy nature of `closure_collector`, `mypy` is currently preferred over `pyright` as it correctly evaluates duck typing, callable interfaces, and default values without emitting false positive errors or requiring blanket `Any` suppressions.
-- **Markdown Formatting:** All markdown files must be formatted with `mdformat`.
-- **Tox:** We use `tox` for cross-version testing and CI orchestration. `tox.ini` has been integrated into `pyproject.toml` via `legacy_tox_ini`.
+```markdown
+Before making any changes you will start a deep planning mode. You will interact with me to fully understand my requirements. You should be thoughtful and think about what I am trying to achieve.
 
-## 2. Type Hinting in Closure Collector
+Your initial goals are:
+1. Have absolute certainty of my expectations and goals before you start working on the plan.
+2. Even if you think you have clarity on the task, ask me to confirm your assumptions in the form of questions.
+3. Remember, you are asking questions - not having me approve a plan. The plan approval comes AFTER you ask these questions.
+4. Ask as many questions and take as many turns as you need. You should have zero doubt about the task at hand. Test and verify every assumption you have made.
+5. You should only ask questions about the task and questions that clarify my desires. Questions that you can derive from the code like ("what file does this logic live in?") can be asked but are discouraged.
+6. After I respond to your questions, you may have more new questions. Think about my answers and reflect on what other questions you might have. Do this as often as you need. Remember in this planning mode, it is your utmost responsibility to make sure the requirements are crystal clear.
+7. Always use the `request_user_input` and `message_user` tools to communicate with me and ask me questions.
+8. When you are absolutely certain that you fully understand the task, create a plan using the `set_plan` tool as described above.
+9. Once the plan is created and approved, proceed with execution autonomously. Do not ask for confirmation or additional questions unless absolutely necessary. Trust your plan and execute it.
+```
 
-Type hinting within `closure_collector` and `flock` requires a specific approach due to the reliance on parameter inspection and closures:
+## Task Example
 
-- **Avoid Over-Typing with `Any`:** Prefer omitting type hints altogether rather than applying `Any` to parameters that accept dynamic values.
-- **Prefer Lambdas over Local `def`s:** When creating closures, `lambda: value` is preferred over `def inner(): return value`. Some type checkers (like `pyright`) misinterpret local `def` closures and inject `Any` return types incorrectly, whereas `lambda` statements bypass this static analysis quirk.
-- **Callable and Dict:** Use `typing.Mapping` and `typing.Callable` appropriately to represent the dictionaries and rule functions processed by the collectors.
+Following the general instructions, a specific task should be provided. For example:
 
-## 3. Architecture
+```markdown
+The task I need you to solve is the following:
+As much as possible implement the flock objects in terms of closure_collector objects identify any cases where this is difficult or complex to do and suggest any additions to closure_collector that would allow a simpler implementation.
+```
 
-- The core functionality of `flock` has been refactored and generalized into a standalone library called `closure_collector`.
-- The `flock` module now serves primarily as a backward-compatibility wrapper (`FlockDict` built on `DynamicClosureCollector`). New functionality should target `closure_collector`.
-- `examples/mythica/model.py` demonstrates a real-world use case for `closure_collector` rules and should be kept functional and lint-free as an integration test.
+## Additional Context from this Session
 
-## 4. Workflows
+During the deep planning mode, the following clarifications were made which guided the implementation:
 
-- The CI is defined in `.github/workflows/tests.yml` and utilizes `tox` across Python 3.9, 3.10, 3.11, 3.12, and 3.13.
-- Before submission, all tests must pass locally: `tox -e py312,lint,type`.
+> "Hmm actually I want to add mapping support to closure_collector, let's create a ClosureMapping and, if needed, a ClosureList. FlockDict and FlockList will then inherit from, or if necessary, wrap this to provide their existing interface."
+
+This highlighted the importance of asking clarifying questions before starting the plan, as it shifted the approach from merely rewriting `flock` internals to actively extending the newer `closure_collector` library to provide native mapping and sequence support, which `flock` then inherited.