[spec-extractor] Update package specifications for gitutil, logger, stringutil, timeutil

pkg/gitutil/README.md

@@ -17,7 +17,7 @@ This package contains helpers for:
 
 #### `IsRateLimitError(errMsg string) bool`
 
-Returns `true` when `errMsg` indicates a GitHub API rate-limit error (HTTP 403 "API rate limit exceeded" or HTTP 429).
+Returns `true` when `errMsg` indicates a GitHub API rate-limit error. Matches any of: "api rate limit exceeded", "rate limit exceeded", or "secondary rate limit" (case-insensitive).
 
 ```go
 if gitutil.IsRateLimitError(err.Error()) {
@@ -47,6 +47,16 @@ if gitutil.IsHexString(sha) {
 }
 ```
 
+#### `IsValidFullSHA(s string) bool`
+
+Returns `true` if `s` is a valid 40-character lowercase hexadecimal SHA (the standard Git commit SHA format). Use this for strict SHA validation when the full 40-character form is required.
+
+```go
+if gitutil.IsValidFullSHA(commitSHA) {
+    // Full 40-char commit SHA
+}
+```
+
 #### `ExtractBaseRepo(repoPath string) string`
 
 Extracts the `owner/repo` portion from an action path that may include a sub-folder.

pkg/logger/README.md

@@ -61,7 +61,7 @@ log.Printf("Task completed")  // Shows +2.5s (or +500ms, +100µs, etc.)
 
 ## DEBUG Environment Variable
 
-Control which loggers are enabled using the `DEBUG` environment variable with patterns:
+Control which loggers are enabled using the `DEBUG` environment variable with patterns. When `ACTIONS_RUNNER_DEBUG=true` is set (as it is in GitHub Actions debug runs) and `DEBUG` is not explicitly set, all loggers are enabled automatically — equivalent to `DEBUG=*`.
 
 ### Examples
 

pkg/stringutil/README.md

@@ -26,7 +26,7 @@ stringutil.Truncate("hi", 8)          // "hi"
 
 ### `NormalizeWhitespace(content string) string`
 
-Collapses multiple consecutive whitespace characters (spaces, tabs, newlines) into a single space and trims leading/trailing whitespace.
+Normalizes trailing whitespace in multi-line content. Trims trailing spaces and tabs from every line, then ensures the content ends with exactly one newline (or is empty). This reduces spurious diffs caused by trailing-whitespace differences.
 
 ### `ParseVersionValue(version any) string`
 
@@ -40,7 +40,7 @@ stringutil.ParseVersionValue(20.0)    // "20"
 
 ### `IsPositiveInteger(s string) bool`
 
-Returns `true` if `s` is a non-empty string containing only digit characters (`0–9`).
+Returns `true` if and only if `s` is a decimal integer that is strictly greater than zero, has no leading zeros, and contains no non-digit characters. Returns `false` for `""`, `"0"`, negative strings (e.g. `"-5"`), strings with leading zeros (e.g. `"007"`), and non-numeric strings.
 
 ## ANSI Escape Code Stripping (`ansi.go`)
 
@@ -67,10 +67,11 @@ stringutil.NormalizeWorkflowName("weekly-research")          // "weekly-research
 
 ### `NormalizeSafeOutputIdentifier(identifier string) string`
 
-Converts dashes to underscores in safe-output identifiers, normalizing the user-facing `dash-separated` format to the internal `underscore_separated` format.
+Converts dashes **and periods** to underscores in safe-output identifiers, normalizing user-facing `dash-separated` and dot-separated formats to the internal `underscore_separated` format required by MCP tool names (which must match `^[a-zA-Z0-9_-]+$`).
 
 ```go
-stringutil.NormalizeSafeOutputIdentifier("create-issue") // "create_issue"
+stringutil.NormalizeSafeOutputIdentifier("create-issue")           // "create_issue"
+stringutil.NormalizeSafeOutputIdentifier("executor-workflow.agent") // "executor_workflow_agent"
 ```
 
 ### `MarkdownToLockFile(mdPath string) string`

pkg/timeutil/README.md

@@ -51,7 +51,7 @@ Formats a duration given in **nanoseconds** as a human-readable string. Returns
 
 ```go
 timeutil.FormatDurationNs(0)              // "—"
-timeutil.FormatDurationNs(2_500_000_000)  // "2s"
+timeutil.FormatDurationNs(2_000_000_000)  // "2s"
 timeutil.FormatDurationNs(90_000_000_000) // "1m30s"
 ```