docs: consolidate developer instructions (v9.16 tone scan) (#37318)

Author: github-actions[bot]

scratchpad/dev.md

@@ -1,7 +1,7 @@
 # Developer Instructions
 
-**Version**: 9.15
-**Last Updated**: 2026-05-30
+**Version**: 9.16
+**Last Updated**: 2026-06-06
 **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.
@@ -2977,6 +2977,7 @@ These files are loaded automatically by compatible AI tools (e.g., GitHub Copilo
 ---
 
 **Document History**:
+- v9.16 (2026-06-06): Maintenance tone scan — `scratchpad/` clean (0 tone issues across all 64 files; the only marketing-term matches in the directory are inside this file's own Document History, which records prior fixes and is not itself a violation). Expanded the scan to the `specs/` directory (9 files) for the first time this cycle and fixed 2 non-normative tone issues: `aw-harness.md` (1 fix: "Leverages Node 24 features"→"Uses Node 24 features" line 198 — trailing descriptive note on a TypeScript→ES2024 MUST clause; matches the v9.14 "leverage"→"use" pattern); `security-architecture-spec-summary.md` (1 fix: "8 comprehensive appendices"→"8 appendices" line 61 — the count is the concrete metric, matching the v6.1 "Comprehensive"→removed pattern). Deliberately left untouched in `specs/`: "Production-ready security" (`security-architecture-spec.md` line 144, `-summary.md` line 22) is a defined conformance-level name in the spec's RFC-2119 taxonomy, not prose; and "comprehensive input sanitization" inside the IS-04..IS-09 MUST requirements (`security-architecture-spec-validation.md` lines 84, 149) carries normative meaning (it scopes the required coverage) and should be revised only by a spec owner. These are flagged for human review rather than auto-edited. Coverage: 64 scratchpad files + 9 specs files = 73 files.
 - v9.15 (2026-05-30): Maintenance tone scan — fixed 2 tone issues across 2 spec files: `token-budget-guidelines.md` (1 fix: "Scans all lock files comprehensively"→"Scans all lock files" line 242 — removed subjective adverb; the count of files scanned is what matters, matching the v6.1 "Comprehensive"→removed pattern); `engine-review-summary.md` (1 fix: "# Deep Review Summary: Agentic Engine Interface & Implementations"→"# Detailed Review Summary: ..." line 1 — the H1 still used "Deep" after v9.13 corrected "Completed deep review"→"Completed a detailed review" in the same file's body at line 5, matching the v3.8/v9.13 "Deep"→"Detailed" pattern; the dev.md Related Documentation link text already omits the adjective, so no link mismatch is introduced). Documented cross-repository handler consistency in the Safe Outputs System → Common Configuration Patterns section (from PRs #35901 and related: `target-repo` and `allowed-repos` are now honored by all safe-output handlers — including `add-labels`, `remove-labels`, and `assign-to-user` — and handler config is generated into a single `config.json` from the handler registry as the single source of truth, keeping cross-repo routing and auth, including `github-token`, consistent across handlers). Added `allowed-repos` to the Cross-Repository YAML example. Coverage: 64 spec files (no new files).
 - v9.14 (2026-05-22): Maintenance tone scan — fixed 10 "leverage" tone issues across 7 spec files. "Leverage" is corporate-speak that translates to concrete verbs like "use", "reuse", or "adopt" in context: `serena-tools-analysis.md` (2 fixes: heading "### 3. Leverage Unused Capabilities"→"### 3. Use Unused Capabilities" line 218; "doesn't fully leverage their language-aware capabilities"→"doesn't fully use their language-aware capabilities" line 368); `mods/jsonschema-go.md` (2 fixes: "leveraging Go 1.18+ generics for compile-time type safety"→"using Go 1.18+ generics for compile-time type safety" line 53; "3. **Leverage Schema Descriptions**"→"3. **Use Schema Descriptions**" line 147); `gastown.md` (1 fix: "Leverage GitHub as communication layer for gastown agents"→"Use GitHub as the communication layer for gastown agents" line 944); `actions.md` (3 fixes: "Leverages existing bundler infrastructure from workflow compilation"→"Reuses existing bundler infrastructure from workflow compilation" line 44; "**Decision**: Leverage existing `workflow.GetJavaScriptSources()` instead of creating separate bundling system."→"**Decision**: Reuse existing `workflow.GetJavaScriptSources()` instead of creating a separate bundling system." line 323; "**Reuse existing infrastructure**: Leverages the same script registry and bundler used for inline mode"→"**Reuse existing infrastructure**: Uses the same script registry and bundler as inline mode" line 915 — the bullet already led with "Reuse", so "Leverages" was redundant filler); `agents/hierarchical-agents.md` (1 fix: "**Leverage cross-campaign coordination:**"→"**Use cross-campaign coordination:**" line 246); `mdflow.md` (1 fix: "Leverage mdflow's simplicity in gh-aw context"→"Adopt mdflow's minimal-configuration approach in the gh-aw context" line 1355 — "simplicity" is subjective; replaced with the concrete property already used elsewhere in the file); `github-mcp-access-control-specification.md` (1 fix: "Both leverage MCP Gateway's extensible configuration format"→"Both use MCP Gateway's extensible configuration format" line 108). Coverage: 64 spec files (no new files).
 - v9.13 (2026-05-21): Maintenance tone scan — fixed 8 tone issues across 6 spec files: `serena-tools-analysis.md` (2 fixes: "# Serena Tools Usage - Deep Statistical Analysis"→"# Serena Tools Usage - Statistical Analysis" line 1 — "Deep" is redundant when "Statistical Analysis" follows, matches v9.7 "Complete deep dive"→"Complete statistical analysis" pattern; "rather than deep language service features"→"rather than language service features" line 181 — removed subjective intensifier, matches v9.7 "deep exploration"→"multi-step exploration" pattern); `mdflow.md` (2 fixes: "**Status**: Deep Technical Analysis"→"**Status**: Technical Analysis" line 5; "This document provides a deep technical analysis"→"This document provides a technical analysis" line 11 — "deep" is subjective, matches v5.7 "Deep Research Comparison"→"Technical Comparison" pattern); `engine-architecture-review.md` (1 fix: "**Scope**: Deep review of agentic engine interface and implementations"→"**Scope**: Detailed review of agentic engine interface and implementations" line 5 — matches v3.8 "Deep analysis"→"Detailed analysis" pattern); `engine-review-summary.md` (1 fix: "Completed deep review of the agentic engine architecture"→"Completed a detailed review of the agentic engine architecture" line 5 — same v3.8 pattern); `ubuntulatest.md` (1 fix: "due to the extensive software list"→"due to the size of the software list" line 350 — replaced subjective "extensive" with concrete "size", matches v9.10 "Due to the extensive nature of..."→"Given the number of..." pattern). Also updated dev.md Related Documentation description for `serena-tools-analysis.md`: "Deep statistical analysis of Serena MCP"→"Statistical analysis of Serena MCP" line 2962 (consistency with the title fix). Coverage: 64 spec files (no new files).

specs/aw-harness.md

@@ -195,7 +195,7 @@ The AW Harness is the topmost layer within the gh-aw container. The following AS
 
 5. **`gh-proxy` and `cli-proxy` always on.** GitHub and other MCP server tools are available to the agent as CLI commands on `PATH` (via `cli-proxy`) and via the pre-authenticated `gh` binary (via `gh-proxy`). A conforming implementation **MUST** enable both `gh-proxy` and `cli-proxy` when `engine: aw` is selected. A conforming implementation **MUST NOT** honor attempts to disable these features for `engine: aw`, regardless of the values specified in the workflow frontmatter (see [Section 6.2](#62-overrides-and-fixed-settings)).
 
-6. **TypeScript → Node 24.** Source **MUST** be TypeScript, compiled to ES2024, bundled via esbuild to a single `.cjs`. Leverages Node 24 features (native fetch, `structuredClone`, `AbortSignal.any`).
+6. **TypeScript → Node 24.** Source **MUST** be TypeScript, compiled to ES2024, bundled via esbuild to a single `.cjs`. Uses Node 24 features (native fetch, `structuredClone`, `AbortSignal.any`).
 
 7. **Output in `actions/setup/js/`.** The bundled `aw_harness.cjs` **MUST** be placed in `actions/setup/js/aw_harness.cjs`, alongside `copilot_harness.cjs` and `claude_harness.cjs`. The same deployment mechanism and runtime contract apply.
 

specs/security-architecture-spec-summary.md

@@ -58,7 +58,7 @@ The specification defines **7 security guarantees (SG-01 to SG-07)**:
 
 - **130+ formal requirements** using RFC 2119 keywords (MUST, SHALL, SHOULD, MAY)
 - **70+ compliance tests** across 8 categories
-- **8 comprehensive appendices** with diagrams, examples, and best practices
+- **8 appendices** with diagrams, examples, and best practices
 
 ### Test Categories