github · pelikhan · May 20, 2026 · May 20, 2026
diff --git a/scratchpad/dev.md b/scratchpad/dev.md
@@ -1,7 +1,7 @@
 # Developer Instructions
 
-**Version**: 9.11
-**Last Updated**: 2026-05-19
+**Version**: 9.12
+**Last Updated**: 2026-05-20
 **Purpose**: Consolidated development guidelines for GitHub Agentic Workflows
 
 This document consolidates specifications from the scratchpad directory into unified developer instructions. It provides architecture patterns, security guidelines, code organization rules, and testing practices.
@@ -2974,6 +2974,7 @@ These files are loaded automatically by compatible AI tools (e.g., GitHub Copilo
 ---
 
 **Document History**:
+- v9.12 (2026-05-20): Maintenance tone scan — fixed 7 tone issues across 4 spec files: `mods/jsonschema-go.md` (2 fixes: "**Enhanced Type Mapping:** Improved handling of pointer types for nullable fields"→"**Type Mapping:** Improved handling of pointer types for nullable fields" line 119 — "Enhanced" is redundant when the same bullet already says "Improved"; "Enhanced default value support"→"Expanded default value support" line 129 — "Enhanced" is comparative with no baseline, "Expanded" describes the concrete change); `oh-my-code.md` (1 fix: "Provide extensive agent capabilities"→"Provide a broad set of agent capabilities" line 23 — "extensive" is subjective; matches the v6.1 "Comprehensive"→removed pattern); `mcp_logs_guardrails.md` (1 fix: "Runs contain extensive tool usage data"→"Runs contain large volumes of tool usage data" line 9 — replaced subjective "extensive" with concrete "large volumes of"); `github-mcp-access-control-specification.md` (3 fixes: "Only read operations allowed (enhanced security)"→"Only read operations allowed (write operations rejected)" line 407 and "Only triggering repository accessible (enhanced security)"→"Only triggering repository accessible (cross-repo access rejected)" line 508 — "enhanced security" is vague; replaced with the specific behavioral guarantee; "fine-grained permissions, enhanced security posture"→"fine-grained permissions and short-lived tokens" line 2341 — replaced vague "enhanced security posture" with one of the specific properties already listed in the surrounding bullets). Coverage: 64 spec files (no new files).
 - v9.11 (2026-05-19): Maintenance tone scan — fixed 3 tone issues across 3 spec files: `labels.md` (1 fix: "Nice-to-have improvements"→"Lower-priority improvements" line 27; matches the v8.0 "nice to have"→"non-blocking" pattern applied to `agents/hierarchical-agents-quickstart.md`); `serena-tools-analysis.md` (1 fix: "## Serena Tool Usage Deep Dive"→"## Serena Tool Usage Analysis" line 47; matches the v3.8 "Deep analysis"→"Detailed analysis" pattern and v9.7 "deep dive"→"statistical analysis" replacement applied to `serena-tools-quick-reference.md`); `ubuntulatest.md` (1 fix: "cannot be perfectly replicated"→"cannot be fully replicated" line 656; removed redundant intensifier — "perfectly" adds no information when contrasting partial vs. complete replication). Coverage: 64 spec files (no new files).
 - v9.10 (2026-05-18): Maintenance tone scan — fixed 4 tone issues across 4 spec files: `testing.md` (1 fix: "extensive testing practices (699 test files, 1,061+ table-driven tests)"→"uses 699 test files and 1,061+ table-driven tests" line 7; "extensive" is subjective when the concrete count is already provided); `html-entity-mention-bypass-fix.md` (1 fix: "Extensive test suite validates all attack vectors"→"Test suite validates all attack vectors" line 137; matches the v6.1 "Comprehensive"→removed pattern); `safe-outputs-specification.md` (1 fix: "Due to the extensive nature of GitHub operations (20+ operation types)"→"Given the number of GitHub operations (20+ operation types)" line 810); `serena-tools-analysis.md` (1 fix: "Serena tools are highly **bandwidth-efficient**"→"Serena tools are **bandwidth-efficient**" line 170; redundant intensifier — preceding line already states "minimal bandwidth"). Coverage: 64 spec files (no new files).
 - v9.9 (2026-05-17): Maintenance tone scan — fixed 1 tone issue: `mcp_logs_guardrails.md` (1 fix: "Returns a simplified list of runs with just the essential fields."→"Returns a list of runs containing only the `database_id`, `workflow_name`, and `status` fields." line 125; removed subjective "essential fields" in favor of explicit field enumeration). Coverage: 63 spec files (no new files).

diff --git a/scratchpad/github-mcp-access-control-specification.md b/scratchpad/github-mcp-access-control-specification.md
@@ -404,7 +404,7 @@ tools:
 The `read-only` field restricts the GitHub MCP server to read-only operations, preventing write operations like creating issues, PRs, or modifying repository content.
 
 **Values**:
-- `true` (default) - Only read operations allowed (enhanced security)
+- `true` (default) - Only read operations allowed (write operations rejected)
 - `false` - Both read and write operations allowed
 
 **Security Note**: The default is `true` to prevent accidental write operations. Explicitly set to `false` only when write operations are required and authorized.
@@ -505,7 +505,7 @@ tools:
 The `lockdown` field restricts GitHub MCP server to **only the triggering repository**, preventing access to other repositories even if the token has permissions.
 
 **Values**:
-- `true` - Only triggering repository accessible (enhanced security)
+- `true` - Only triggering repository accessible (cross-repo access rejected)
 - `false` - All token-accessible repositories available
 - **Omitted** - Automatically set based on repository visibility (private repos → `true`, public repos → `false`)
 
@@ -2338,7 +2338,7 @@ tools:
     private-repos: true
 ```
 
-**Use Case**: Multi-repository automation with fine-grained permissions, enhanced security posture
+**Use Case**: Multi-repository automation with fine-grained permissions and short-lived tokens
 
 **GitHub App Benefits**:
 - Short-lived tokens (auto-expire)

diff --git a/scratchpad/mcp_logs_guardrails.md b/scratchpad/mcp_logs_guardrails.md
@@ -6,7 +6,7 @@ This document describes the output size guardrail implemented for the MCP server
 
 When using the MCP server to fetch workflow logs, the output can exceed GitHub's API limits, especially when:
 - Fetching logs for many workflow runs
-- Runs contain extensive tool usage data
+- Runs contain large volumes of tool usage data
 - Multiple workflows are being analyzed
 
 Large outputs can:

diff --git a/scratchpad/mods/jsonschema-go.md b/scratchpad/mods/jsonschema-go.md
@@ -116,7 +116,7 @@ tool := &mcp.Tool{
 
 Based on upstream activity and community discussions:
 
-- **Enhanced Type Mapping:** Improved handling of pointer types for nullable fields
+- **Type Mapping:** Improved handling of pointer types for nullable fields
 - **Better Error Messages:** More descriptive validation errors, especially for `additionalProperties` violations
 - **Performance Improvements:** Optimizations in validation logic
 - **TypeSchemas Key Update:** Changed from `any` to `reflect.Type` for better type safety
@@ -126,7 +126,7 @@ Based on upstream activity and community discussions:
 
 While not officially released, upstream development suggests:
 - Deeper customization for schema inference
-- Enhanced default value support
+- Expanded default value support
 - More informative validation error messages
 - Better meta-schema integration
 - Improved handling of complex Go types

diff --git a/scratchpad/oh-my-code.md b/scratchpad/oh-my-code.md
@@ -20,7 +20,7 @@ This document compares **oh-my-opencode** and **GitHub Agentic Workflows** (gh-a
 | **Multi-Agent** | Native multi-agent orchestration | Single-agent per workflow (event-driven) |
 | **Tool Ecosystem** | LSP, AST-Grep, MCP servers | GitHub MCP, Bash allowlist, Playwright |
 | **State Management** | Stateful, persistent across sessions | Stateless workflow runs |
-| **Philosophy** | Provide extensive agent capabilities | "Safe by default" - minimize risk |
+| **Philosophy** | Provide a broad set of agent capabilities | "Safe by default" - minimize risk |
 
 ---