Support finding caller of a companion object

.agents/_TOC.md

@@ -0,0 +1,20 @@
+# Table of Contents
+
+1. [Quick Reference Card](quick-reference-card.md)
+2. [Purpose](purpose.md)
+3. [Project overview](project-overview.md)
+4. [Coding guidelines](coding-guidelines.md)
+5. [Documentation & comments](documentation-guidelines.md)
+6. [Documentation typography & structure](documentation-typography-and-structure.md)
+7. [Documentation tasks](documentation-tasks.md)
+8. [Running builds](running-builds.md)
+9. [Version policy](version-policy.md)
+10. [Project structure expectations](project-structure-expectations.md)
+11. [Testing](testing.md)
+12. [Safety rules](safety-rules.md)
+13. [Advanced safety rules](advanced-safety-rules.md)
+14. [Refactoring guidelines](refactoring-guidelines.md)
+15. [Interaction tips – key to effective collaboration!](interaction-tips.md)
+16. [LLM goals](llm-goals.md)
+    - [Problem-solving framework](llm-goals.md#problem-solving-framework-for-complex-tasks)
+17. [Common tasks](common-tasks.md)

.agents/advanced-safety-rules.md

@@ -0,0 +1,6 @@
+# 🚨 Advanced safety rules
+
+- Do **not** auto-update external dependencies without explicit request.
+- Do **not** inject analytics or telemetry code.
+- Flag any usage of unsafe constructs (e.g., reflection, I/O on the main thread).
+- Avoid generating blocking calls inside coroutines.

.agents/coding-guidelines.md

@@ -0,0 +1,39 @@
+# 🧾 Coding guidelines
+
+## Core principles
+
+- Adhere to [Spine Event Engine Documentation][spine-docs] for coding style.
+- Generate code that compiles cleanly and passes static analysis.
+- Respect existing architecture, naming conventions, and project structure.
+- Write clear, incremental commits with descriptive messages.
+- Include automated tests for any code change that alters functionality.
+
+## Kotlin best practices
+
+### ✅ Prefer
+- **Kotlin idioms** over Java-style approaches:
+  - Extension functions
+  - `when` expressions 
+  - Smart casts
+  - Data classes and sealed classes
+  - Immutable data structures
+- **Simple nouns** over composite nouns (`user` > `userAccount`)  
+- **Generic parameters** over explicit variable types (`val list = mutableList<Dependency>()`)  
+- **Java interop annotations** only when needed (`@file:JvmName`, `@JvmStatic`)
+- **Kotlin DSL** for Gradle files
+
+### ❌ Avoid
+- Mutable data structures
+- Java-style verbosity (builders with setters)
+- Redundant null checks (`?.let` misuse)
+- Using `!!` unless clearly justified
+- Type names in variable names (`userObject`, `itemList`)
+- String duplication (use constants in companion objects)
+- Mixing Groovy and Kotlin DSLs in build logic
+- Reflection unless specifically requested
+
+## Text formatting
+ - ✅ Remove double empty lines in the code.
+ - ✅ Remove trailing space characters in the code.
+
+[spine-docs]: https://github.com/SpineEventEngine/documentation/wiki

.agents/common-tasks.md

@@ -0,0 +1,6 @@
+# 📋 Common tasks
+
+- **Adding a new dependency**: Update relevant files in `buildSrc` directory.
+- **Creating a new module**: Follow existing module structure patterns.
+- **Documentation**: Use KDoc style for public and internal APIs.
+- **Testing**: Create comprehensive tests using Kotest assertions.

.agents/documentation-guidelines.md

@@ -0,0 +1,14 @@
+# Documentation & comments
+
+## Commenting guidelines
+- Avoid inline comments in production code unless necessary.
+- Inline comments are helpful in tests.
+- When using TODO comments, follow the format on the [dedicated page][todo-comments].
+- File and directory names should be formatted as code.
+
+## Avoid widows, runts, orphans, or rivers 
+
+Agents should **AVOID** text flow patters illustrated
+on [this diagram](widow-runt-orphan-river.jpg).
+
+[todo-comments]: https://github.com/SpineEventEngine/documentation/wiki/TODO-comments

.agents/documentation-tasks.md

@@ -0,0 +1,24 @@
+# 📄 Documentation tasks
+
+1. Ensure all public and internal APIs have KDoc examples.
+2. Add in-line code blocks for clarity in tests.
+3. Use `TODO` comments with agent names for unresolved logic sections:
+   ```
+   // TODO(chatgpt): Refactor `EventStore` for better CQRS compliance.
+   ```
+4. Convert inline API comments in Java to KDoc in Kotlin:
+   ```java
+   // Literal string to be inlined whenever a placeholder references a non-existent argument.
+   private final String missingArgumentMessage = "[MISSING ARGUMENT]";
+   ```
+   transforms to:
+   ```kotlin
+   /**
+    * Literal string to be inlined whenever a placeholder references a non-existent argument.
+    */
+    private val missingArgumentMessage = "[MISSING ARGUMENT]" 
+   ```
+
+5. Javadoc -> KDoc conversion tasks:
+   - Remove `<p>` tags in the line with text: `"<p>This"` -> `"This"`.
+   - Replace `<p>` with empty line if the tag is the only text in the line.

.agents/documentation-typography-and-structure.md

@@ -0,0 +1,145 @@
+# Documentation Typography & Structure
+
+This guide adapts principles from **MIL-STD-961** and **Apple Human Interface Guidelines** for use
+with AI agents, with a focus on improving Kotlin KDoc documentation.
+
+## Goals
+- Improve **text flow** and **line width** in KDoc blocks.
+- Ensure **consistent formatting**, **clarity**, and **navigability**.
+- Enable AI tools to reliably generate or refactor documentation based on structured patterns.
+
+---
+
+## 1. General Formatting Rules
+
+### 1.1 Code Width
+- **Maximum line width for code:** `100 characters`
+- **Maximum line width for documentation:** `90 characters`
+
+### 1.2 Font Style and Presentation
+- Use **Markdown-style formatting** within KDoc where supported (e.g., `inline code`).
+- Format code blocks with fences and language identifiers:
+  ```kotlin
+  fun example() {
+      // Implementation
+  }
+  ```
+
+### External links in `@see` tag
+
+- The `@see` tag is for [referencing API elements](https://kotlinlang.org/docs/kotlin-doc.html#see-identifier).
+- External links are [not officially supported](https://github.com/Kotlin/dokka/issues/518).
+- External links CAN be added when migrating from Javadoc.
+- Format is:
+  ```kotlin
+  /**
+   * Documentation text.
+   *
+   * @see <a href="https://my.site.com/my-page.html">Link title</a>
+   */
+  ```
+
+### 1.3 Line Wrapping
+- Hard-wrap KDoc lines at **90 characters** to improve readability in side-by-side editors and diffs.
+- **Provide** text flow **convenient for human readers**.
+- **Prefer** starting new sentences or breaking after commands on new lines **over filling** the width.
+
+---
+
+## 2. Sectioning and Navigation
+
+### 2.1 Structure of a KDoc Block
+Use the following standard structure in multi-line KDoc blocks:
+
+```kotlin
+/**
+ * [Short summary sentence.]
+ *
+ * [Detailed description. Wrap at 90 characters.]
+ *
+ * @param paramName [Description of the parameter.]
+ * @return [Description of the return value.]
+ * @throws SomeException [Reason for throwing.]
+ */
+```
+
+> **Note:** Start `@param`, `@return`, and `@throws` descriptions with a **capital letter** and
+> end with a **period**. This follows guidance from Apple, Microsoft, and military documentation
+> (MIL-STD-961F), all of which encourage clarity and full-sentence formatting.
+> While Java Javadoc traditionally uses lowercase fragments, Kotlin documentation benefits
+> from full-sentence style for better readability and tooling support.
+
+### 2.2 Headers and Subsections
+- Do **not** use Markdown headers level 1 and level 2 (`#`, `##`) in KDoc.
+- Use spacing and keywords (`@param`, `@return`, `@throws`) to denote sections.
+
+### 2.3 Ordering for Navigability
+Always order tags as follows for consistency:
+1. `@param` (in declaration order)
+2. `@return`
+3. `@throws`
+4. `@see` / `@sample`
+
+---
+
+## 3. Clarity and Language
+
+### 3.1 Sentence Style
+- Use **complete sentences** with a subject and verb.
+- Start with a **capital letter**.
+- End with a **period**, unless it's a list item or tag line.
+
+### 3.2 Vocabulary and Tone
+- Be **neutral**, **precise**, and **audience-aware**.
+- Avoid unnecessary jargon.
+- Favor active voice: “Initializes the engine,” not “The engine is initialized.”
+
+### 3.3 Lists and Steps
+Use hyphen lists (`-`) or numbered lists (`1.`, `2.`) inside KDoc only if supported by tooling.
+
+```kotlin
+/**
+ * Loads a configuration:
+ * - Reads from disk.
+ * - Parses YAML.
+ * - Caches the result.
+ */
+```
+
+---
+
+## 4. Punctuation and Consistency
+
+- Use **Oxford commas** for clarity in lists.
+- Always end descriptive lines with a **period**.
+- For `@param`, `@return`, etc., write the description in sentence case.
+
+```kotlin
+@param timeout The time in milliseconds before the operation times out.
+```
+
+---
+
+## 5. AI Agent Instructions
+
+When generating or modifying Kotlin code with KDoc:
+
+- **Ensure** documentation for `public`  and `internal` API exists.
+- **Wrap** text at 90 characters.
+- **Preserve** the structure defined above.
+- **Correct grammar and punctuation**.
+- **Infer tag content** when possible, based on function signature.
+- **Avoid duplication** between summary and detailed description.
+- **Omit boilerplate** such as “This function...” in summaries.
+- **ALWAYS WRAP the modified Kotlin code at 100 characters** or `detekt` build error will occur. 
+
+---
+
+## References
+- MIL-STD-961F: Department of Defense Standard Practice for Defense Specifications.
+- Apple Human Interface Guidelines: [Typography](https://developer.apple.com/design/human-interface-guidelines/foundations/typography/)
+
+---
+
+End of guide.
+

.agents/interaction-tips.md

@@ -0,0 +1,20 @@
+# 💬 Interaction tips – key to effective collaboration!
+
+- Human programmers may use inline comments to guide agents:
+  ```kotlin
+    // ChatGPT: Suggest a refactor for better readability.
+    // Codex: Complete the missing branches in this `when` block.
+    // ChatGPT: explain this logic.
+    // Codex: complete this function.
+   ```
+- Agents should ensure pull request messages are concise and descriptive:
+  ```text
+  feat(chatgpt): suggested DSL refactoring for query handlers  
+  fix(codex): completed missing case in sealed class hierarchy
+  ```
+- Encourage `// TODO:` or `// FIXME:` comments to be clarified by ChatGPT.
+
+- When agents or humans add TODO comments, they **must** follow the format described on
+  the [dedicated page][todo-comments].
+
+[todo-comments]: https://github.com/SpineEventEngine/documentation/wiki/TODO-comments

.agents/java-kotlin-conversion.md

@@ -0,0 +1,58 @@
+# 🪄 Converting Java code to Kotlin
+
+* Java code API comments are Javadoc format.
+* Kotlin code API comments are in KDoc format. 
+
+## Javadoc to KDoc conversion
+
+* The wording of original Javadoc comments must be preserved.
+
+## Treating nullability
+
+* Use nullable Kotlin type only if the type in Java is annotated as `@Nullable`.
+
+## Efficient Conversion Workflow
+
+* First, analyze the entire Java file structure before beginning conversion to understand dependencies and class relationships.
+* Convert Java code to Kotlin systematically: imports first, followed by class definitions, methods, and finally expressions.
+* Preserve all existing functionality and behavior during conversion.
+* Maintain original code structure and organization to ensure readability.
+
+## Common Java to Kotlin Patterns
+
+* Convert Java getters/setters to Kotlin properties with appropriate visibility modifiers.
+* Transform Java static methods to companion object functions or top-level functions as appropriate.
+* Replace Java anonymous classes with Kotlin lambda expressions when possible.
+* Convert Java interfaces with default methods to Kotlin interfaces with implementations.
+* Transform Java builders to Kotlin DSL patterns when appropriate.
+
+## Error Prevention
+
+* Pay special attention to Java's checked exceptions versus Kotlin's unchecked exceptions.
+* Be cautious with Java wildcards (`? extends`, `? super`) conversion to Kotlin's `out` and `in` type parameters.
+* Ensure proper handling of Java static initialization blocks in Kotlin companion objects.
+* Verify that Java overloaded methods convert correctly with appropriate default parameter values in Kotlin.
+* Remember that Kotlin has smart casts which can eliminate explicit type casting needed in Java.
+* Suppress `detekt` build errors using this format: `[Error]` with `@Suppress("Error")`.
+
+## Documentation Conversion
+
+* Convert `@param` to `@param` with the same description: 
+  - Start the description on the same line with the `@param` tag 
+  - Break at 90 chars
+  - Continue with the margin of 7 space chars.
+
+* Convert `@return` to `@return` with the same description.
+* Convert `@throws` to `@throws` with the same description.
+* Convert `{@link}` to `[name][fully.qualified.Name]` format.
+* Convert `{@code}` to inline code with backticks (`).
+
+## Conversion tasks
+ * Convert end-line comments above methods and fields to KDoc.
+ * Preserve the content of original comments but convert the format and markup.
+ * Always use braces `{}` for `if`, `for`, and `while` statements.
+ * If the converted function has more than two `return` statements, annotate it with `@Suppress("ReturnCount")`.
+ * Keep inline comments from the original code.
+ * Ensure a single new line at the end of the produced Kotlin file without asking.
+
+

.agents/llm-goals.md

@@ -0,0 +1,20 @@
+# 🧭 LLM goals
+
+These goals guide how agents (ChatGPT, Codex) are used in this project to:
+- Help developers move faster without sacrificing code quality.
+- Provide language-aware guidance on Kotlin/Java idioms.
+- Lower the barrier to onboarding new contributors.
+- Enable collaborative, explainable, and auditable development with AI.
+
+## Problem-solving framework for complex tasks
+
+When faced with complex tasks, follow this framework:
+
+1. **Decompose**: Break down the problem into smaller, manageable parts.
+2. **Analyze**: Understand the architectural implications of each part.
+3. **Pattern-Match**: Identify established patterns that apply.
+4. **Implement**: Write code that follows project conventions.
+5. **Test**: Ensure comprehensive test coverage.
+6. **Document**: Provide clear explanations of your solution.
+
+*This framework helps maintain consistency across contributions from different agents.*

.agents/project-overview.md

@@ -0,0 +1,8 @@
+# 🛠️ Project overview
+
+- **Languages**: Kotlin (primary), Java (secondary).
+- **Build tool**: Gradle with Kotlin DSL.
+- **Architecture**: Event-driven Command Query Responsibility Segregation (CQRS).
+- **Static analysis**: detekt, ErrorProne, Checkstyle, PMD. 
+- **Testing**: JUnit 5, Kotest Assertions, Codecov.
+- **Tools used**: Gradle plugins, IntelliJ IDEA Platform, KSP, KotlinPoet, Dokka.

.agents/project-structure-expectations.md

@@ -0,0 +1,21 @@
+# 📁 Project structure expectations
+
+```yaml
+.github
+buildSrc/
+<module-1>
+  src/
+  ├── main/
+  │ ├── kotlin/ # Kotlin source files
+  │ └── java/ # Legacy Java code
+  ├── test/
+  │ └── kotlin/ # Unit and integration tests
+  build.gradle.kts # Kotlin-based build configuration
+<module-2>
+<module-3>
+build.gradle.kts # Kotlin-based build configuration
+settings.gradle.kts # Project structure and settings
+README.md # Project overview
+AGENTS.md # LLM agent instructions (this file)
+version.gradle.kts # Declares the project version. 
+```