From 85fd158c965275c4597a4f6a3d7393116f982cbb Mon Sep 17 00:00:00 2001 From: Documentation Consolidation Bot Date: Sun, 22 Feb 2026 00:03:17 +0000 Subject: [PATCH] docs: consolidate developer specs v2.7 - tone fixes and TypeScript type definitions MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Fix 3 subjective language issues across 3 spec files: - engine-review-summary.md: remove 'production-ready' qualifier, replace 'Easy to understand and follow' with technical description - go-type-patterns.md: replace 'Easy refactoring' with factual description - serena-tools-quick-reference.md: replace '✓ Perfect' with '✓ Complete' - Add TypeScript Type Definitions section to dev.md Safe Outputs System documenting handler-factory.d.ts, safe-outputs.d.ts, safe-outputs-config.d.ts, and github-script.d.ts from PR #17605 - Bump dev.md version to 2.7 Co-Authored-By: Claude Sonnet 4.6 --- scratchpad/dev.md | 27 ++++++++++++++++++++-- scratchpad/engine-review-summary.md | 4 ++-- scratchpad/go-type-patterns.md | 2 +- scratchpad/serena-tools-quick-reference.md | 2 +- 4 files changed, 29 insertions(+), 6 deletions(-) diff --git a/scratchpad/dev.md b/scratchpad/dev.md index aca9e67d9f..d9b1fd44a0 100644 --- a/scratchpad/dev.md +++ b/scratchpad/dev.md @@ -1,7 +1,7 @@ # Developer Instructions -**Version**: 2.6 -**Last Updated**: 2026-02-20 +**Version**: 2.7 +**Last Updated**: 2026-02-22 **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. @@ -597,6 +597,28 @@ func generateAttribution(workflowName, runURL string, issue int) string { } ``` +### TypeScript Type Definitions for Handlers + +Safe output handler development is supported by TypeScript type definitions in `actions/setup/js/types/`: + +| File | Purpose | +|------|---------| +| `handler-factory.d.ts` | Types for `HandlerFactoryFunction`, `MessageHandlerFunction`, `HandlerConfig`, `HandlerResult` | +| `safe-outputs.d.ts` | JSONL output item types for all safe output operations | +| `safe-outputs-config.d.ts` | Configuration interfaces for each safe output type (e.g., `CreateIssueConfig`) | +| `github-script.d.ts` | GitHub Script context types available in handler functions | + +**Handler Factory Pattern** (typed): +```typescript +// A handler main() function follows this signature +const main: HandlerFactoryFunction = async (config?: HandlerConfig): Promise => { + return async (message: any, resolvedTemporaryIds: ResolvedTemporaryIds): Promise => { + // process message + return { success: true }; + }; +}; +``` + --- ## Testing Guidelines @@ -1782,6 +1804,7 @@ type Everything interface { --- **Document History**: +- v2.7 (2026-02-22): Fixed 3 tone issues (engine-review-summary.md: removed 'production-ready' and 'Easy to understand and follow'; go-type-patterns.md: replaced 'Easy refactoring'; serena-tools-quick-reference.md: replaced '✓ Perfect' with '✓ Complete'), added TypeScript type definitions section for safe output handler development (PR #17605) - v2.6 (2026-02-20): Fixed 8 tone issues across 4 spec files, documented post-processing extraction pattern and CLI flag propagation rule from PR #17316, analyzed 61 files - v2.5 (2026-02-19): Fixed 6 tone issues in engine review docs, added Engine-Specific MCP Config Delivery section (Gemini pattern), analyzed 61 files - v2.4 (2026-02-17): Quality verification - analyzed 4 new files, zero tone issues found across all 61 files diff --git a/scratchpad/engine-review-summary.md b/scratchpad/engine-review-summary.md index 08414108e5..a026e48e2b 100644 --- a/scratchpad/engine-review-summary.md +++ b/scratchpad/engine-review-summary.md @@ -273,13 +273,13 @@ All implementations follow established patterns and are thoroughly tested. ## Conclusion -The agentic engine architecture is **production-ready**. It follows SOLID principles, has comprehensive test coverage, and provides clear extensibility patterns through: +The agentic engine architecture follows SOLID principles, has comprehensive test coverage, and provides clear extensibility patterns through: 1. **Interface Segregation**: Focused interfaces composed together 2. **BaseEngine Defaults**: Sensible defaults for all methods 3. **Shared Helpers**: Reduce duplication and ensure consistency 4. **Comprehensive Testing**: Automated validation of compliance -5. **Clear Patterns**: Easy to understand and follow +5. **Clear Patterns**: Consistent interfaces with documented extension points The architecture **requires no structural changes**. The only gap was comprehensive documentation for adding new engines, which has been addressed with: diff --git a/scratchpad/go-type-patterns.md b/scratchpad/go-type-patterns.md index 27a9179391..b1556395dc 100644 --- a/scratchpad/go-type-patterns.md +++ b/scratchpad/go-type-patterns.md @@ -37,7 +37,7 @@ type Version string - Self-documenting code - the type name explains the purpose - Type safety - prevents mixing different concepts that share the same underlying type - Clear intent - signals to readers what the value represents -- Easy refactoring - can change underlying implementation without affecting API +- Enables refactoring without breaking API contracts - underlying implementation can change independently ### Examples in Codebase diff --git a/scratchpad/serena-tools-quick-reference.md b/scratchpad/serena-tools-quick-reference.md index ff8d099f2b..18b7fcce29 100644 --- a/scratchpad/serena-tools-quick-reference.md +++ b/scratchpad/serena-tools-quick-reference.md @@ -9,7 +9,7 @@ |--------|-------|--------| | Total Tool Calls | 44 | ✓ | | Serena Tool Calls | 9 (20.45%) | ⚠️ Low | -| Response Rate | 100% | ✓ Perfect | +| Response Rate | 100% | ✓ Complete | | Tools Registered | 23 | - | | Tools Used | 6 (26.09%) | ⚠️ Low adoption | | Most Used Tool | Bash (17 calls) | - |