Proofread comments and documentation

.agents/tasks/otel-backend-report.md

@@ -585,7 +585,7 @@ Implications:
 ## 11. Phased plan
 
 - **Phase 0 — JVM-via-compat spike.** Backend on JVM only, `OpenTelemetry` provided as
-  `javaOtel.toOtelKotlinApi()`. Validate the full path (Spine log → OTLP → backend of choice)against
+  `javaOtel.toOtelKotlinApi()`. Validate the full path (Spine log → OTLP → backend of choice) against
   the mature Java SDK. Lowest risk; proves the mapping before touching KMP.
 - **Phase 1 — KMP commonMain backend (`:api`).** Move the mapping into `commonMain`, JVM target
   registered via `ServiceLoader`, SDK injected by the app. Severity, body, metadata→attributes,

.claude/settings.json

@@ -1,5 +1,6 @@
 {
   "$schema": "https://json.schemastore.org/claude-code-settings.json",
+  "plansDirectory": ".claude/plans",
   "permissions": {
     "allow": [
       "Edit(version.gradle.kts)",
@@ -32,8 +33,11 @@
       "Bash(mkdir:*)",
       "Bash(touch:*)",
       "Bash(python3 .agents/skills/update-copyright/scripts/update_copyright.py:*)",
+      "Bash(.agents/skills/version-bumped/scripts/version-bumped.sh)",
       "Bash(./config/pull)",
-      "Bash(./config/migrate)"
+      "Bash(./config/migrate)",
+      "Skill(pre-pr)",
+      "Skill(pre-pr:*)"
     ],
     "deny": [
       "Bash(git reset --hard:*)",

.gitignore

@@ -54,8 +54,12 @@
 .idea/modules
 .idea/shelf
 
+# `.idea/misc.xml` is intentionally NOT re-included below. It is project-local —
+# it holds the per-project JDK name and IDEA's own churn (entry-point list
+# indices, external-storage toggles) — so `.idea/*.xml` above keeps it ignored.
+# `./config/pull` (via `migrate`) untracks any copy an earlier pull committed.
+
 # Do not ignore the following IDEA settings
-!.idea/misc.xml
 !.idea/codeStyleSettings.xml
 !.idea/codeStyles/
 !.idea/copyright/
@@ -173,6 +177,12 @@ __pycache__/
 
 # Claude working files
 /.claude/worktrees/
+# Ephemeral plan-mode scratch (durable task docs live in `.agents/tasks/`).
+/.claude/plans/
+
+# Personal, per-developer Claude Code settings overrides (never committed;
+# the distributed `.claude/settings.json` is the shared, committed layer).
+/.claude/settings.local.json
 
 # Auto-downloaded Lychee binary used by the `check-links` skill.
 /.agents/skills/check-links/.cache/
@@ -190,7 +200,6 @@ docs/_preview/resources/
 # <<< shared config <<<
 
 # >>> repo-local entries (preserved across ./config/pull) >>>
-!.idea/misc.xml
 !.idea/codeStyleSettings.xml
 !.idea/codeStyles/
 !.idea/copyright/

CONTRIBUTING.md

@@ -20,13 +20,13 @@ Code contributions should:
 
 Contributor License Agreement
 -----------------------------
-Contributions to the code of Spine Event Engine framework and its libraries must be accompanied by
-Contributor License Agreement (CLA).
+Contributions to the code of the Spine Event Engine framework and its libraries must be accompanied by
+a Contributor License Agreement (CLA).
 
  * If you are an individual writing original source code and you're sure you own
    the intellectual property, then you'll need to sign an individual CLA.
 
- * If you work for a company which wants you to contribute your work,
+ * If you work for a company that wants you to contribute your work,
    then an authorized person from your company will need to sign a corporate CLA.
 
 Please [contact us][legal-email] for arranging the paper formalities.

README.md

@@ -8,7 +8,7 @@
 Spine Logging is a versatile library designed for Kotlin and Java projects,
 with a potential for multi-platform use.
 
-As of now, only JVM target is supported, with a JavaScript implementation
+As of now, only the JVM target is supported, with a JavaScript implementation
 being our priority for future development.
 
 API and implementation are largely inspired by [Google Flogger][flogger],
@@ -34,12 +34,12 @@ dependencies {
 ```
 
 In this case, the default logging backend will be used. It outputs log records
-to the console using `java.util.logging` (JUL) framework.
+to the console using the `java.util.logging` (JUL) framework.
 
 All logging operations are done with an instance of `io.spine.logging.Logger`.
 To get a logger, one can use the following:
 
-1. Make a logging class implement `WithLogging` interface.
+1. Make a logging class implement the `WithLogging` interface.
 2. Get a logger from `LoggingFactory`.
 
 ### Logging via `WithLogging` interface
@@ -100,10 +100,10 @@ The following backends are available:
   See [the OpenTelemetry backend guide](docs/otel-backend.md).
 
 The default backend is supplied along the logging library itself. To use it,
-one just needs to not supply any other backend. Then JUL backend will be
+one just needs to not supply any other backend. Then the JUL backend will be
 used automatically.
 
-For other backends, put a chosen one to `runtimeOnly` configuration,
+For other backends, put a chosen one to the `runtimeOnly` configuration,
 and the logging library will discover it in the runtime.
 
 An example usage of Log4j2 backend:
@@ -142,7 +142,7 @@ class Example : WithLogging {
 // INFO: Call #7 [CONTEXT ratelimit_count=7 skipped=6 ]
 ```
 
-Also, a user can attach its own metadata. For instance, you can attach
+Also, a user can attach their own metadata. For instance, you can attach
 a user ID to all log records for the current request, or force logging
 level if the requested URL contains a debug parameter.
 

backends/jul-backend/src/main/kotlin/io/spine/logging/backend/jul/AbstractJulBackend.kt

@@ -70,7 +70,7 @@ public abstract class AbstractJulBackend : LoggerBackend {
 
     /**
      * Logs the given record using this backend. If [wasForced] is set, the backend will make a
-     * best effort attempt to bypass any log level restrictions in the underlying Java [Logger],
+     * best-effort attempt to bypass any log level restrictions in the underlying Java [Logger],
      * but there are circumstances in which this can fail.
      */
     public fun log(record: LogRecord, wasForced: Boolean) {
@@ -108,7 +108,7 @@ public abstract class AbstractJulBackend : LoggerBackend {
      * Forces logging via a child logger, bypassing the parent handlers.
      *
      * WARNING: This code will fail for anonymous loggers `(getName() == null)` and
-     * when/if the Logging library supports anonymous loggers it must ensure that
+     * when/if the Logging library supports anonymous loggers, it must ensure that
      * this code path is avoided by not allowing subclasses of `Logger` to be used.
      */
     internal fun forceLoggingViaChildLogger(record: LogRecord) {
@@ -120,7 +120,7 @@ public abstract class AbstractJulBackend : LoggerBackend {
             Logger.getLogger("").log(
                 SEVERE.toJavaLogging(),
                 """
-                Forcing log statements with has been partially disabled.
+                Forcing log statements has been partially disabled.
                 The Logging library cannot modify logger log levels, which is necessary to
                 force log statements. This is likely due to an installed `SecurityManager`.
                 Forced log statements will still be published directly to log handlers, but

backends/jul-backend/src/main/kotlin/io/spine/logging/backend/jul/AbstractJulRecord.kt

@@ -56,13 +56,13 @@ import java.util.logging.LogRecord
  * ## Non-null message, non-empty parameters
  *
  * This state is only reached if a user calls both [setMessage] and [setParameters].
- * In this state the message is treated as is it were a brace-format log
+ * In this state the message is treated as if it were a brace-format log
  * message, and no formatting is attempted.
  * Any relationship between this value, and the log message
  * implied by the contained [LogData] and [Metadata] is lost.
  *
  * For many reasons it is never a good idea for users to modify unknown [LogRecord]
- * instances, but this does happen occasionally, so this class supports that in a best effort way,
+ * instances, but this does happen occasionally, so this class supports that in a best-effort way,
  * but users are always recommended to copy [LogRecord] instances if they need
  * to modify them.
  *
@@ -175,7 +175,7 @@ public abstract class AbstractJulRecord : LogRecord {
     public fun getLogData(): LogData = data
 
     /**
-     * Returns the immutable [MetadataProcessor] which provides a unified view of scope and log site metadata.
+     * Returns the immutable [MetadataProcessor] that provides a unified view of scope and log site metadata.
      */
     public fun getMetadataProcessor(): MetadataProcessor = metadata
 

backends/jul-backend/src/main/kotlin/io/spine/logging/backend/jul/JulBackend.kt

@@ -78,7 +78,7 @@ internal class JulBackend(loggingClass: String): AbstractJulBackend(loggingClass
      * are involved.
      *
      * When a [parent logger][Logger.getParent] has a higher level
-     * (which is [Level.INFO][java.util.logging.Level.INFO] by default) its handler has
+     * (which is [Level.INFO][java.util.logging.Level.INFO] by default), its handler has
      * this level too. Because of this the method [Handler.isLoggable] filters
      * out the record.
      *
@@ -91,7 +91,7 @@ internal class JulBackend(loggingClass: String): AbstractJulBackend(loggingClass
      * @see publishForced
      */
     private fun doLog(record: LogRecord, wasForced: Boolean) {
-        // If not forced, do work as usually.
+        // If not forced, do work as usual.
         if (!wasForced || isLoggable(record.level.toLevel())) {
             logger.log(record)
             return
@@ -107,7 +107,7 @@ internal class JulBackend(loggingClass: String): AbstractJulBackend(loggingClass
 /**
  * Publishes the given [record] using the handlers of the [logger].
  *
- * If the logger is configured to [use parent handlers][Logger.getUseParentHandlers]
+ * If the logger is configured to [use parent handlers][Logger.getUseParentHandlers],
  * propagates publishing to the [parent logger][Logger.getParent] too.
  */
 private fun publishForced(logger: Logger, record: LogRecord) {

backends/jul-backend/src/main/kotlin/io/spine/logging/backend/jul/JulBackendFactory.kt

@@ -30,7 +30,7 @@ import io.spine.logging.backend.BackendFactory
 import io.spine.logging.backend.LoggerBackend
 
 /**
- * A [BackendFactory] producing [LoggerBackend] which supports publishing
+ * A [BackendFactory] producing [LoggerBackend] that supports publishing
  * of logging records according to configured [LogLevelMap][io.spine.logging.context.LogLevelMap].
  */
 public class JulBackendFactory: BackendFactory() {

backends/jul-backend/src/test/kotlin/io/spine/logging/backend/jul/given/StubLogData.kt

@@ -36,7 +36,7 @@ import io.spine.logging.toLevel
 import java.util.logging.Level as JLevel
 
 /**
- * A mutable [LogData] fot testing backends and other log handling code.
+ * A mutable [LogData] for testing backends and other log handling code.
  *
  * @see <a href="http://rb.gy/z2i0q">Original Java code</a>
  *   for historical context.

backends/log4j2-backend/src/main/kotlin/io/spine/logging/backend/log4j2/ValueQueue.kt

@@ -103,7 +103,7 @@ internal class ValueQueue private constructor() : Iterable<Any> {
             return if (existingValue == null) {
                 value
             } else {
-                // This should only rarely happen, so a few small allocations seems acceptable.
+                // This should only rarely happen, so a few small allocations seem acceptable.
                 val existingQueue = existingValue as? ValueQueue ?: newQueue(existingValue)
                 existingQueue.put(value)
                 existingQueue
@@ -136,7 +136,7 @@ internal class ValueQueue private constructor() : Iterable<Any> {
          * Emits a metadata label/value pair to a given KeyValueHandler,
          * handling Tags values specially.
          *
-         * Tags are key-value mappings which cannot be modified or replaced.
+         * Tags are key-value mappings that cannot be modified or replaced.
          * If you add the tag mapping "foo" -> true and later add "foo" -> false,
          * you get "foo" mapped to both true and false.
          * This is deliberate since the key space for tags is global and the risk

backends/log4j2-backend/src/test/kotlin/io/spine/logging/backend/log4j2/given/StubLogData.kt

@@ -34,7 +34,7 @@ import io.spine.logging.MetadataKey
 import io.spine.logging.backend.LogData
 
 /**
- * A mutable [LogData] fot testing backends and other log handling code.
+ * A mutable [LogData] for testing backends and other log handling code.
  *
  * @see <a href="http://rb.gy/z2i0q">Original Java code</a>
  *   for historical context.

backends/probe-backend/README.md

@@ -3,7 +3,7 @@
 **Note:** This is a specific backend implementation that is designed to be used in tests.
 
 The probe backend provides a backend factory that can switch
-the current backend implementation on runtime.
+the current backend implementation at runtime.
 The logging facade does not provide such a capability.
 Take a look at `DynamicBackendFactory` for details.
 

backends/probe-backend/src/main/kotlin/io/spine/logging/backend/probe/CaptureLogData.kt

@@ -30,7 +30,7 @@ import io.spine.logging.backend.LogData
 
 /**
  * Runs the given [action], capturing all log data that are passed
- * to backend by the API.
+ * to the backend by the API.
  *
  * To make this work, please create a logger instance inside of [action].
  * This method captures log data for loggers that are both created and used
@@ -77,7 +77,7 @@ public inline fun captureLogData(action: () -> Unit): List<LogData> {
     }
 
     // Several loggers could have been created within the `action`.
-    // Each logger spawns its own instance of backend.
+    // Each logger spawns its own instance of a backend.
     val loggedFromAllBackends = memoizingFactory.createdBackends.flatMap { it.logged }
     return loggedFromAllBackends
 }

backends/probe-backend/src/main/kotlin/io/spine/logging/backend/probe/DynamicBackendFactory.kt

@@ -32,10 +32,10 @@ import io.spine.logging.backend.jul.JulBackendFactory
 
 /**
  * A factory that delegates backends creation to another factory
- * and allows changing of the underlying factory in runtime.
+ * and allows changing of the underlying factory at runtime.
  *
  * In general, the logging facade doesn't provide a mechanism for changing
- * the underlying backend factory in runtime. It shouldn't make any sense
+ * the underlying backend factory at runtime. It shouldn't make any sense
  * in real code. But for tests, it can be handy.
  *
  * Different tests may need different backend stubs to perform their assertions.