From 7856ee7e8e7472f2a1e7fbdf3035e58b403a5174 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Tue, 14 Apr 2026 11:23:18 +0000 Subject: [PATCH] =?UTF-8?q?docs:=20consolidate=20developer=20specs=20v6.0?= =?UTF-8?q?=20=E2=80=94=20tone=20fixes=20and=20integrity-reactions?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Remove 10 'comprehensive' instances from engine-architecture-review.md - Remove 2 'comprehensive' instances from file-inlining.md - Add integrity-reactions feature documentation to dev.md (v0.68.2+): compiler auto-enables cli-proxy when features.integrity-reactions: true - Bump dev.md to v6.0 (2026-04-14) Co-Authored-By: Claude Sonnet 4.6 --- scratchpad/dev.md | 22 ++++++++++++++++++++-- scratchpad/engine-architecture-review.md | 20 ++++++++++---------- scratchpad/file-inlining.md | 4 ++-- 3 files changed, 32 insertions(+), 14 deletions(-) diff --git a/scratchpad/dev.md b/scratchpad/dev.md index caf2a9f01f2..1c07bd84a09 100644 --- a/scratchpad/dev.md +++ b/scratchpad/dev.md @@ -1,7 +1,7 @@ # Developer Instructions -**Version**: 5.9 -**Last Updated**: 2026-04-13 +**Version**: 6.0 +**Last Updated**: 2026-04-14 **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. @@ -2089,6 +2089,23 @@ Integrity levels are determined by the `author_association` field and main branc **Extensibility**: The `MCPServerConfig` struct holds a `GuardPolicies map[string]any` field for future MCP servers (e.g., Jira, WorkIQ) that need server-specific policy schemas. +**Reactions as Trust Signals** (v0.68.2+): The `integrity-reactions` feature flag allows GitHub reactions (👍, ❤️) to promote content past the integrity filter. When `features.integrity-reactions: true` is set, the compiler automatically: +- Enables `cli-proxy` (required for reaction-based integrity decisions) +- Injects default endorsement reactions: `THUMBS_UP`, `HEART` +- Injects default disapproval reactions: `THUMBS_DOWN`, `CONFUSED` +- Uses `endorser-min-integrity: approved` (only reactions from owners, members, and collaborators count) +- Uses `disapproval-integrity: none` (a disapproval reaction demotes content to `none`) + +```yaml +features: + integrity-reactions: true +tools: + github: + min-integrity: approved +``` + +Note: `cli-proxy` is implicitly enabled by the compiler when `integrity-reactions: true` — no explicit `features.cli-proxy: true` is required. Reactions only work through the CLI proxy, not the gateway mode. + See `scratchpad/guard-policies-specification.md` for the full specification including type hierarchy and error message reference. ### MCP Server Configuration @@ -2812,6 +2829,7 @@ These files are loaded automatically by compatible AI tools (e.g., GitHub Copilo --- **Document History**: +- v6.0 (2026-04-14): Fixed 12 tone issues across 2 spec files: `engine-architecture-review.md` (10 fixes: "comprehensive documentation have been added to further enhance extensibility"→"documentation have been added to extend the architecture", "Comprehensive MCP support"→"MCP support", "No comprehensive guide existed"→"No guide existed", "Created comprehensive `adding-new-engines.md`"→"Created `adding-new-engines.md`", "Assessment: ✅ **Comprehensive**"→"Assessment: ✅", "No comprehensive developer guide"→"No developer guide", "Developers have comprehensive guidance"→"Developers have implementation guidance", "Create comprehensive guide for adding new engines"→"Create guide for adding new engines", "Comprehensive Engine Implementation Guide"→"Engine Implementation Guide", "Comprehensive testing"→"Testing"), `file-inlining.md` (2 fixes: "Comprehensive testing with unit tests"→"Testing with unit tests", "Comprehensive documentation"→"Documentation"). Added integrity-reactions feature documentation to GitHub MCP Guard Policies section (from PR #26154: `features.integrity-reactions: true`, compiler auto-enables `cli-proxy`, default reaction config, v0.68.2+). Coverage: 75 spec files (no new files). - v5.9 (2026-04-13): Maintenance tone scan — fixed 10 tone issues across 2 spec files: `go-type-patterns.md` (1 fix: "Easy refactoring"→"Supports refactoring"), `engine-review-summary.md` (9 fixes: "Completed comprehensive deep review"→"Completed deep review", "No comprehensive guide"→"No guide", "Created comprehensive documentation"→"Created documentation", "Comprehensive Implementation Guide"→"Implementation Guide", "quick access to comprehensive engine documentation"→"quick access to engine documentation", "Create comprehensive guide"→"Create guide", "Comprehensive Testing"→"Testing", "The only gap was comprehensive documentation"→"The only gap was documentation", "The comprehensive guide provides everything needed"→"The guide provides the steps needed"). Coverage: 75 spec files (no new files). - v5.8 (2026-04-11): Maintenance tone scan — fixed 9 tone issues across 2 spec files: `engine-review-summary.md` (6 fixes: `### Strengths ⭐⭐⭐⭐⭐`→`### Strengths`, `### Interface Design: ⭐⭐⭐⭐⭐ (5/5)`→`### Interface Design`, removed Rating column from Implementation Quality table and replaced "Comprehensive single-file implementation" with "Single-file implementation", `### Security: ⭐⭐⭐⭐⭐ (5/5)`→`### Security`, `### Testing: ⭐⭐⭐⭐⭐ (5/5)`→`### Testing`, `### Documentation: ⭐⭐⭐⭐⭐ (5/5) - After Improvements`→`### Documentation - After Improvements`), `engine-architecture-review.md` (3 fixes: removed 3 `**Rating**: ⭐⭐⭐⭐⭐ (5/5)` lines from Copilot, Claude, Codex, and Custom engine sections). Coverage: 75 spec files (no new files). - v5.7 (2026-04-10): Maintenance tone scan — fixed 4 tone issues across 2 spec files: `oh-my-code.md` (3 fixes: "Deep Research Comparison"→"Technical Comparison", "Comprehensive Analysis"→"Analysis", "deep research comparison between"→"compares"), `mdflow-comparison.md` (1 fix: "detailed syntax comparison"→"syntax comparison"). Updated Related Documentation description for `oh-my-code.md`. Coverage: 75 spec files (no new files). diff --git a/scratchpad/engine-architecture-review.md b/scratchpad/engine-architecture-review.md index 798ca23db08..5d9c96cd199 100644 --- a/scratchpad/engine-architecture-review.md +++ b/scratchpad/engine-architecture-review.md @@ -6,7 +6,7 @@ ## Executive Summary -The agentic engine architecture follows the Interface Segregation Principle (ISP) and is structured for extension. The ISP implementation provides flexibility for adding new engines while maintaining backward compatibility. Minor improvements and comprehensive documentation have been added to further enhance extensibility. +The agentic engine architecture follows the Interface Segregation Principle (ISP) and is structured for extension. The ISP implementation provides flexibility for adding new engines while maintaining backward compatibility. Minor improvements and documentation have been added to extend the architecture. ### Key Findings @@ -79,7 +79,7 @@ Key helper functions in `engine_helpers.go`: **Strengths**: - ✅ Modular organization (7 files) -- ✅ Comprehensive MCP support +- ✅ MCP support - ✅ Full firewall integration - ✅ Plugin support - ✅ Detailed logging @@ -128,9 +128,9 @@ Key helper functions in `engine_helpers.go`: ### Adding New Engines -**Before this review**: No comprehensive guide existed for adding new engines. +**Before this review**: No guide existed for adding new engines. -**After this review**: Created comprehensive `adding-new-engines.md` with: +**After this review**: Created `adding-new-engines.md` with: - Step-by-step implementation guide - Complete interface documentation - Testing requirements @@ -198,7 +198,7 @@ Engines with firewall support: - ✅ All engines implement LogParser interface - ✅ All engines implement SecurityProvider interface -**Assessment**: ✅ **Comprehensive**. Automated validation ensures compliance. +**Assessment**: ✅ Automated validation ensures compliance. ### Engine-Specific Tests @@ -253,7 +253,7 @@ Engine code includes: ### Developer Documentation -**Before this review**: No comprehensive developer guide for adding engines. +**Before this review**: No developer guide for adding engines. **After this review**: Created `scratchpad/adding-new-engines.md`: - ✅ Complete interface documentation @@ -263,13 +263,13 @@ Engine code includes: - ✅ Best practices - ✅ Troubleshooting -**Assessment**: ✅ Developers have comprehensive guidance. +**Assessment**: ✅ Developers have implementation guidance. ## Recommendations ### Immediate Actions (Completed) -1. ✅ **Create comprehensive guide for adding new engines** (`adding-new-engines.md`) +1. ✅ **Create guide for adding new engines** (`adding-new-engines.md`) - Complete interface documentation - Step-by-step implementation guide - Testing requirements @@ -313,7 +313,7 @@ The `adding-new-engines.md` document provides step-by-step guidance for implemen ### Key Deliverables -1. ✅ **Comprehensive Engine Implementation Guide** (`scratchpad/adding-new-engines.md`) +1. ✅ **Engine Implementation Guide** (`scratchpad/adding-new-engines.md`) - 500+ lines of detailed documentation - Step-by-step instructions - Complete code examples @@ -335,7 +335,7 @@ The architecture itself requires **no structural changes**. The codebase follows - Interface segregation - BaseEngine defaults - Shared helper functions -- Comprehensive testing +- Testing - Clear patterns The only improvement needed was documentation, which has been completed. diff --git a/scratchpad/file-inlining.md b/scratchpad/file-inlining.md index f5ee742b3b2..cc8d528e514 100644 --- a/scratchpad/file-inlining.md +++ b/scratchpad/file-inlining.md @@ -293,11 +293,11 @@ The runtime import feature provides a flexible way to include external content i - ✅ **Line range support** for targeted content - ✅ **URL fetching** with automatic caching - ✅ **Security built-in** with macro detection -- ✅ **Comprehensive testing** with unit tests +- ✅ **Testing** with unit tests ### Implementation Quality - ✅ All tests passing -- ✅ Comprehensive documentation +- ✅ Documentation - ✅ Example workflows provided - ✅ No breaking changes to existing features - ✅ Clean integration with existing codebase