[docs] Consolidate developer specifications to v9.3 (#31027)

Author: Copilot

scratchpad/dev.md

@@ -1,7 +1,7 @@
 # Developer Instructions
 
-**Version**: 9.2
-**Last Updated**: 2026-05-07
+**Version**: 9.3
+**Last Updated**: 2026-05-08
 **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.
@@ -1843,6 +1843,19 @@ Compiled `workflow_dispatch` workflows now automatically propagate `aw_context`
 
 The `activation` artifact now uploads `aw_info.json` alongside `prompt.txt`. This makes run info and workflow overview data available to prompt generation and logging earlier in the job lifecycle (previously only available after the agent job).
 
+**`engine.mcp.tool-timeout` rendered as numeric `toolTimeout` seconds** (PR #31007):
+
+The `engine.mcp.tool-timeout` frontmatter value is parsed from a Go duration string and rendered as numeric `toolTimeout` seconds in MCP gateway config JSON (`pkg/workflow/mcp_renderer.go` uses `durationStringToSeconds` before emitting `toolTimeout`). `session-timeout` remains a string field.
+
+```yaml
+engine:
+  mcp:
+    session-timeout: "2m" # rendered as gateway.sessionTimeout: "2m" (string)
+    tool-timeout: 2m      # rendered as gateway.toolTimeout: 120 (integer seconds)
+```
+
+Empty `tool-timeout` falls back to the MCP gateway default (`toolTimeout: 60` seconds).
+
 **GHE Support** (`configure_gh_for_ghe.sh`):
 
 Workflows that call `gh` CLI commands on GitHub Enterprise Server domains should source `configure_gh_for_ghe.sh` before any `gh` calls. The script auto-detects the correct GHE host from environment variables (`GITHUB_SERVER_URL`, `GITHUB_ENTERPRISE_HOST`, `GITHUB_HOST`, or `GH_HOST`):
@@ -2960,6 +2973,7 @@ These files are loaded automatically by compatible AI tools (e.g., GitHub Copilo
 ---
 
 **Document History**:
+- v9.3 (2026-05-08): Maintenance tone scan — 0 tone issues found across all 63 spec files. Documented 1 new feature from PR #31007 in Workflow Patterns: `engine.mcp.tool-timeout` now parses Go duration strings and renders as numeric gateway `toolTimeout` seconds (contrasted with string `session-timeout` rendering). Coverage: 63 spec files (no new files).
 - v9.2 (2026-05-07): Maintenance tone scan — fixed 1 tone issue: `workflow-refactoring-patterns.md` (4 fixes: removed gamified "+X points" scoring from Benefits headings). Documented 3 new features from PR #30800: (1) `mcp-gateway.opentelemetry.headers` now accepts string-only format (migration from object format); (2) `aw_context` caller metadata propagation for compiled `workflow_dispatch` workflows (dispatch traceability via `aw_info.json`); (3) activation artifact now includes `aw_info.json` alongside `prompt.txt`. Coverage: 63 spec files (no new files).
 - v9.1 (2026-05-06): Maintenance tone scan — 0 tone issues found across all 63 spec files. No new spec files since v9.0. Coverage: 63 spec files (no new files).
 - v9.0 (2026-05-04): Maintenance tone scan — fixed 1 tone issue: `serena-tools-quick-reference.md` (1 fix: "12.32 KB (2.89% of all data) - highly efficient"→"12.32 KB (2.89% of all data)"). Documented PR #30072 engine domain registry pattern: updated Engine Interface Architecture section ("Adding a new engine" note about `engineDefaultDomains` map in `domains.go`), updated `adding-new-engines.md` with new "Firewall Domain Registration" pattern (Phase 1 checklist item + full code example for `engineDefaultDomains` map and model-specific domain functions). Coverage: 64 spec files (no new files).