diff --git a/scratchpad/actions.md b/scratchpad/actions.md index 6c63436b6c9..025f839d8cb 100644 --- a/scratchpad/actions.md +++ b/scratchpad/actions.md @@ -105,7 +105,7 @@ Create a custom actions system that: │ │ └── README.md │ │ │ └────────────────────────────────────────────────────┘ │ └─────────────────────────────────────────────────────────┘ -```text +``` ### Component Responsibilities @@ -166,7 +166,7 @@ gh-aw/ ├── Makefile # Build targets (NO sync-shell-scripts or sync-js-scripts) └── .github/workflows/ └── ci.yml # CI pipeline -```text +``` **Runtime File Copy Flow (Current Architecture):** @@ -197,7 +197,7 @@ actions/{action-name}/ ├── src/ # Source files │ └── index.js # Main entry point with FILES placeholder └── README.md # Action documentation -```text +``` ### action.yml Format @@ -261,7 +261,7 @@ The build system is implemented entirely in Go and follows these steps: ```text actions/setup/js/*.cjs (SOURCE OF TRUTH) → Runtime copy to /tmp/gh-aw/actions actions/setup/sh/*.sh (SOURCE OF TRUTH) → Runtime copy to /tmp/gh-aw/actions -```text +``` **Why this pattern?** - JavaScript and shell scripts live in `actions/setup/js/` and `actions/setup/sh/` as source of truth diff --git a/scratchpad/agents/hierarchical-agents.md b/scratchpad/agents/hierarchical-agents.md index ad7813cc04e..df7983cd26d 100644 --- a/scratchpad/agents/hierarchical-agents.md +++ b/scratchpad/agents/hierarchical-agents.md @@ -124,7 +124,7 @@ The hierarchical agent system consists of specialized meta-orchestrator workflow │ │ 1 │ │ 2 │ │ 3 │ │ 4 │ │ │ └──────┘ └──────┘ └──────┘ └──────┘ │ └─────────────────────────────────────────────┘ -```text +``` ### Key Principles diff --git a/scratchpad/breaking-cli-rules.md b/scratchpad/breaking-cli-rules.md index 92b52da12bb..7b081f70490 100644 --- a/scratchpad/breaking-cli-rules.md +++ b/scratchpad/breaking-cli-rules.md @@ -171,7 +171,7 @@ The following changes are **not breaking** and typically require: │ ▼ NO NOT BREAKING -```text +``` ## Guidelines for Contributors diff --git a/scratchpad/capitalization.md b/scratchpad/capitalization.md index 728ddfc3dc5..1fd17e18ff2 100644 --- a/scratchpad/capitalization.md +++ b/scratchpad/capitalization.md @@ -30,7 +30,7 @@ When referring to the gh-aw tool or GitHub Agentic Workflows as a product: ```text GitHub Agentic Workflows CLI from GitHub Next GitHub Agentic Workflows from GitHub Next -```text +``` ### Generic Workflow References (Lowercase) @@ -41,7 +41,7 @@ Enable agentic workflows Initialize repository for agentic workflows Download and analyze agentic workflow logs Add an MCP tool to an agentic workflow -```text +``` ### Technical Terms (Capitalized) @@ -50,7 +50,7 @@ Proper nouns and acronyms maintain their standard capitalization: ```text Compile Markdown workflows to GitHub Actions YAML MCP helpers -```text +``` ## Decision Flow diff --git a/scratchpad/code-organization.md b/scratchpad/code-organization.md index d5b4181c58e..5e1fd50c336 100644 --- a/scratchpad/code-organization.md +++ b/scratchpad/code-organization.md @@ -113,7 +113,7 @@ The codebase follows several consistent patterns that should be emulated: create_issue.go (160 lines) create_pull_request.go (238 lines) create_discussion.go (118 lines) -```text +``` **Avoid**: Single large file with all creation logic (600+ lines) @@ -125,14 +125,14 @@ create_issue.go # Issue creation logic create_issue_test.go # Issue creation tests add_comment.go # Comment addition logic add_comment_test.go # Comment tests -```text +``` **Avoid**: Type-based organization ```text models.go # All structs logic.go # All business logic tests.go # All tests -```text +``` ### 3. Use Descriptive File Names @@ -292,14 +292,14 @@ This demonstrates that even large subsystems benefit from logical file splits. ```text // Don't create files like this workflow.go (5000+ lines) // Everything related to workflows -```text +``` **Solution**: Split by responsibility ```text workflow_parser.go workflow_compiler.go workflow_validation.go -```text +``` ### ❌ 2. Vague Naming @@ -309,13 +309,13 @@ utils.go helpers.go misc.go common.go -```text +``` **Solution**: Use specific names ```text string_utils.go // If really needed engine_helpers.go // Shared engine utilities -```text +``` ### ❌ 3. Mixed Concerns @@ -325,7 +325,7 @@ engine_helpers.go // Shared engine utilities func CreateIssue() {} func ValidateNetwork() {} // Unrelated! func CompileYAML() {} // Unrelated! -```text +``` **Solution**: Keep files focused on one domain @@ -334,14 +334,14 @@ func CompileYAML() {} // Unrelated! **Problem**: All tests in one massive file ```text workflow_test.go (10000+ lines) // All tests -```text +``` **Solution**: Split by scenario ```text workflow_parser_test.go workflow_compiler_test.go workflow_integration_test.go -```text +``` ### ❌ 5. Premature Abstraction @@ -350,7 +350,7 @@ workflow_integration_test.go // Don't create these preemptively future_feature_helpers.go maybe_needed_utils.go -```text +``` **Solution**: Wait until you have 2-3 use cases, then extract common patterns @@ -374,7 +374,7 @@ Is this a new safe output type (create_*)? Is this functionality independent? ├─ YES → Create new file └─ NO → Add to existing file -```text +``` ### Should I Split an Existing File? @@ -394,7 +394,7 @@ Is the file > 1000 lines? Are there frequent merge conflicts? ├─ YES → CONSIDER splitting └─ NO → Keep as is -```text +``` ### What Should I Name This File? @@ -414,7 +414,7 @@ Is it a create operation for GitHub entity? Is it a cohesive feature? ├─ YES → .go └─ NO → Reconsider the organization -```text +``` ## Examples from the Codebase @@ -428,7 +428,7 @@ pkg/workflow/ ├── create_discussion.go (118 lines) ├── create_code_scanning_alert.go (136 lines) └── create_agent_task.go (120 lines) -```text +``` ### Recommended: Engine Organization ```text @@ -439,7 +439,7 @@ pkg/workflow/ ├── codex_engine.go (639 lines) - Codex implementation ├── custom_engine.go (300 lines) - Custom engine └── engine_helpers.go (424 lines) - Shared utilities -```text +``` ### Recommended: Focused Utilities ```text @@ -448,7 +448,7 @@ pkg/workflow/ ├── expressions.go (948 lines) - Expression handling ├── artifacts.go (60 lines) - Artifact management └── args.go (65 lines) - Argument parsing -```text +``` ## Quick Reference diff --git a/scratchpad/dev.md b/scratchpad/dev.md index c2508ff9fe6..f1ab3335d26 100644 --- a/scratchpad/dev.md +++ b/scratchpad/dev.md @@ -1,7 +1,7 @@ # Developer Instructions -**Version**: 3.1 -**Last Updated**: 2026-02-26 +**Version**: 3.2 +**Last Updated**: 2026-02-27 **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. @@ -2056,6 +2056,7 @@ These files are loaded automatically by compatible AI tools (e.g., GitHub Copilo --- **Document History**: +- v3.2 (2026-02-27): Fixed 42 non-standard code fence closing markers across 12 spec files (`` ```text `` and `` ```yaml `` incorrectly used as closing fences in actions.md, code-organization.md, github-actions-security-best-practices.md, and 9 others); identified 1 new test artifact file (smoke-test-22422877284.md) as non-spec content - v3.1 (2026-02-26): Fixed 173 non-standard code fence closing markers across 20 spec files (`` ```text `` incorrectly closing `` ```go ``, `` ```yaml ``, and other language blocks); files fixed include code-organization.md, validation-architecture.md, actions.md, safe-output-messages.md, github-actions-security-best-practices.md, and 15 others - v3.0 (2026-02-25): Added YAML Parser Compatibility section (YAML 1.1 vs 1.2 boolean parsing, `on:` trigger key false positive, YAML 1.2 parser recommendations); added yaml-version-gotchas.md to Related Documentation; fixed 17 non-standard closing code fences in yaml-version-gotchas.md - v2.9 (2026-02-24): Added Engine Interface Architecture (ISP 7-interface design, BaseEngine, EngineRegistry), JavaScript Content Sanitization Pipeline with HTML entity bypass fix (T24 template delimiter neutralization), and Activation Output Transformations compiler behavior; added 4 new Related Documentation links diff --git a/scratchpad/end-to-end-feature-testing.md b/scratchpad/end-to-end-feature-testing.md index a7b5b959de7..e592ef00fd0 100644 --- a/scratchpad/end-to-end-feature-testing.md +++ b/scratchpad/end-to-end-feature-testing.md @@ -28,7 +28,7 @@ In your pull request, instruct the GitHub Copilot coding agent to modify the `de - Adding the necessary configuration in the frontmatter - Updating the task description to use the feature - Including validation steps to verify the feature works correctly -```text +``` **What the agent should do:** @@ -120,7 +120,7 @@ Based on the results: ```text Modify dev.md → Recompile → Trigger workflow → Review results → Iterate -```text +``` Continue this cycle until the workflow succeeds and the feature works as expected. diff --git a/scratchpad/firewall-log-parsing.md b/scratchpad/firewall-log-parsing.md index 02f73532db8..7a4c28b0a04 100644 --- a/scratchpad/firewall-log-parsing.md +++ b/scratchpad/firewall-log-parsing.md @@ -68,14 +68,14 @@ Firewall logs use a space-separated format with 10 fields: ```text timestamp client_ip:port domain dest_ip:port proto method status decision url user_agent -```text +``` ### Example Log Entries ```text 1761332530.474 172.30.0.20:35288 api.enterprise.githubcopilot.com:443 140.82.112.22:443 1.1 CONNECT 200 TCP_TUNNEL:HIER_DIRECT api.enterprise.githubcopilot.com:443 "-" 1761332531.123 172.30.0.20:35289 blocked.example.com:443 140.82.112.23:443 1.1 CONNECT 403 NONE_NONE:HIER_NONE blocked.example.com:443 "-" -```text +``` ### Field Descriptions @@ -136,7 +136,7 @@ Allowed Domains: Blocked Domains: ✗ blocked-domain.example.com:443 (2 requests) ✗ blocked.malicious.site:443 (1 requests) -```text +``` ### JSON Output diff --git a/scratchpad/github-actions-security-best-practices.md b/scratchpad/github-actions-security-best-practices.md index 617e46cc847..88555bb43a8 100644 --- a/scratchpad/github-actions-security-best-practices.md +++ b/scratchpad/github-actions-security-best-practices.md @@ -121,7 +121,7 @@ steps: if [ "$COMMENT_BODY" = "approved" ]; then echo "Approved" fi -```yaml +``` --- @@ -266,7 +266,7 @@ steps: # Safe command usage result=$(grep -r "$INPUT_VALUE" . || true) echo "$result" -```yaml +``` --- @@ -708,7 +708,7 @@ safe-outputs: create-pull-request: # AI never has direct write access -```yaml +``` --- @@ -800,7 +800,7 @@ jobs: ```text workflow.yml:10:5: shellcheck reported issue in this script: SC2086:info:1:6: Double quote to prevent globbing and word splitting [shellcheck] workflow.yml:15:3: property "runs-on" is not set [syntax-check] -```text +``` **Action**: Fix shell quoting issues, add missing required fields. @@ -812,7 +812,7 @@ finding: artipacked level: Medium desc: Actions that upload artifacts without retention limits location: workflow.yml:25 -```text +``` **Action**: Add `retention-days` to artifact uploads. @@ -879,7 +879,7 @@ steps: # .github/CODEOWNERS .github/workflows/ @security-team .github/actions/ @security-team -```text +``` **Why**: Ensures workflow changes are reviewed by security team before merge. @@ -936,7 +936,7 @@ network: # Or deny all network access network: {} -```yaml +``` --- diff --git a/scratchpad/labels.md b/scratchpad/labels.md index 271c508493a..0f9ea020ff4 100644 --- a/scratchpad/labels.md +++ b/scratchpad/labels.md @@ -109,7 +109,7 @@ Priority: priority-high, priority-medium, priority-low Component: cli, workflow, mcp, actions, engine, automation Workflow: ai-generated, plan, ai-inspected, smoke-copilot Status: good first issue, dependencies -```text +``` This taxonomy provides clear filtering while avoiding label sprawl. Use GitHub's issue search to combine labels effectively: - `is:issue is:open label:bug label:priority-high` - Critical bugs diff --git a/scratchpad/safe-output-messages.md b/scratchpad/safe-output-messages.md index 124741a64eb..ca1f803d017 100644 --- a/scratchpad/safe-output-messages.md +++ b/scratchpad/safe-output-messages.md @@ -895,7 +895,7 @@ pkg/workflow/js/ ├── messages_run_status.cjs # Run status messages (getRunStartedMessage, getRunSuccessMessage, getRunFailureMessage) ├── messages_close_discussion.cjs # Close discussion messages (getCloseOlderDiscussionMessage) └── messages.cjs # Barrel file for backward compatibility -```text +``` ### Module Descriptions diff --git a/scratchpad/string-sanitization-normalization.md b/scratchpad/string-sanitization-normalization.md index c70c57878ef..ff80878461a 100644 --- a/scratchpad/string-sanitization-normalization.md +++ b/scratchpad/string-sanitization-normalization.md @@ -138,7 +138,7 @@ Need to process a string? └─ Need to standardize format? → Use NORMALIZE ├─ Remove file extensions → normalizeWorkflowName() └─ Convert conventions → normalizeSafeOutputIdentifier() -```text +``` ## Common Patterns diff --git a/scratchpad/validation-architecture.md b/scratchpad/validation-architecture.md index 54937406c63..6d131199650 100644 --- a/scratchpad/validation-architecture.md +++ b/scratchpad/validation-architecture.md @@ -296,7 +296,7 @@ Use this decision tree to determine where to place new validation logic: │ NO ▼ validation.go -```text +``` ## Validation Patterns