Add documentation headers to helper files

[Copilot]

Several helper files lacked file-level documentation explaining their purpose, organization rationale, and usage patterns. Added comprehensive headers following the pattern established in config_helpers.go.

Changes

• git_helpers.go - Documents Git repository utilities for extracting tags and version metadata during compilation
• close_entity_helpers.go - Documents shared utilities for building close entity jobs using registry pattern
• update_entity_helpers.go - Documents shared utilities for update operations, including field parsing modes (key existence vs. bool value)
• prompt_step_helper.go - Documents prompt generation helpers with security considerations for expression handling

Documentation Structure

Each header includes:

• Purpose statement and organization rationale
• Key functions organized by category
• Usage patterns and when to use vs. alternatives
• Cross-references to related files (e.g., create_*.go, other helpers)

Example

// Package workflow provides Git repository utilities for workflow compilation.
//
// This file contains helper functions for interacting with Git repositories
// to extract metadata such as tags and version information.
//
// # Organization Rationale
//
// These Git utilities are grouped in a helper file because they:
//   - Provide Git-specific functionality (tags, versions)
//   - Are used by multiple workflow compilation modules
//   - Encapsulate Git command execution and error handling
//   - Have a clear domain focus (Git repository metadata)
//
// # Key Functions
//
// Tag Detection:
//   - GetCurrentGitTag() - Detect current Git tag from environment or repository

Note: map_helpers.go and engine_helpers.go already had comprehensive documentation and required no changes.

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[plan] Add documentation headers to helper files</issue_title>
<issue_description>## Objective

Add clear file header documentation to helper files that lack it, following the pattern established in config_helpers.go.

Context

Several helper files lack documentation explaining their purpose and usage:

• map_helpers.go (2 functions)
• git_helpers.go (1 function)
• engine_helpers.go (6 functions)
• close_entity_helpers.go (4 functions)
• update_entity_helpers.go (4 functions)
• prompt_step_helper.go (2 functions)

The file config_helpers.go serves as an excellent example with clear documentation of purpose and usage patterns.

Approach

1. Review existing documentation:

   • Study pkg/workflow/config_helpers.go as the documentation template
   • Identify what makes it clear and helpful

2. Add file headers to each helper file with:

   • Brief purpose statement
   • When to use this helper (vs alternatives)
   • Key patterns or conventions
   • Example usage if appropriate

3. Document the "why":

   • Explain why the helper file exists
   • Clarify separation from main implementation files

Files to Modify

• pkg/workflow/map_helpers.go - Add header documentation
• pkg/workflow/git_helpers.go - Add header documentation
• pkg/workflow/engine_helpers.go - Add header documentation
• pkg/workflow/close_entity_helpers.go - Add header documentation
• pkg/workflow/update_entity_helpers.go - Add header documentation
• pkg/workflow/prompt_step_helper.go - Add header documentation

Acceptance Criteria

• Each helper file has a clear file header comment
• Documentation explains purpose and usage patterns
• Documentation style consistent with config_helpers.go
• Comments explain when to use vs alternatives (where applicable)
• No functional changes (documentation only)
  Related to [refactor] Semantic Function Clustering Analysis - Code Organization Opportunities #7136

AI generated by Plan Command for #7136

Comments on the Issue (you are @copilot in this section)

• Fixes [plan] Add documentation headers to helper files #7143

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.