[Schema Consistency] Gold Standard: branch-prefix Feature Implementation Analysis

[github-actions[bot]]

Executive Summary

The branch-prefix feature demonstrates exemplary schema-implementation-documentation consistency and serves as the gold standard for feature implementation in this codebase. This analysis traces the feature end-to-end across all implementation layers.

1. Schema Definition (JSON Schema)

Location: /home/runner/work/gh-aw/gh-aw/pkg/parser/schemas/main_workflow_schema.json

The schema defines branch-prefix in two contexts (object configuration and array configuration) with identical constraints:

Constraints Defined

{
  "branch-prefix": {
    "type": "string",
    "minLength": 4,
    "maxLength": 32,
    "pattern": "^[a-zA-Z0-9_-]+$",
    "description": "Branch prefix for memory storage (default: 'memory'). Must be 4-32 characters, alphanumeric with hyphens/underscores, and cannot be 'copilot'. Branch will be named {branch-prefix}/{id}"
  }
}

Schema Constraints:

• Type: string
• minLength: 4
• maxLength: 32
• pattern: ^[a-zA-Z0-9_-]+$ (alphanumeric, hyphens, underscores)
• Reserved keyword: Cannot be copilot (mentioned in description)

Locations in Schema:

• Lines 3239-3244: Object configuration (tools.repo-memory.branch-prefix)
• Lines 3317-3322: Array configuration (tools.repo-memory[].branch-prefix)

2. Compiler Implementation (Go)

Location: /home/runner/work/gh-aw/gh-aw/pkg/workflow/repo_memory.go

Validation Function

The validateBranchPrefix() function (lines 69-95) enforces all schema constraints plus the reserved keyword check:

func validateBranchPrefix(prefix string) error {
    if prefix == "" {
        return nil // Empty means use default
    }

    // Check length (4-32 characters)
    if len(prefix) < 4 {
        return fmt.Errorf("branch-prefix must be at least 4 characters long, got %d", len(prefix))
    }
    if len(prefix) > 32 {
        return fmt.Errorf("branch-prefix must be at most 32 characters long, got %d", len(prefix))
    }

    // Check for alphanumeric and branch-friendly characters
    if !branchPrefixValidPattern.MatchString(prefix) {
        return fmt.Errorf("branch-prefix must contain only alphanumeric characters, hyphens, and underscores, got '%s'", prefix)
    }

    // Cannot be "copilot"
    if strings.ToLower(prefix) == "copilot" {
        return fmt.Errorf("branch-prefix cannot be 'copilot' (reserved)")
    }

    return nil
}

Implementation Details

Regex Pattern (line 33):

branchPrefixValidPattern = regexp.MustCompile(`^[a-zA-Z0-9_-]+$`)
```

**Validation Coverage**:
1. ✅ **minLength (4)**: Explicit check with clear error message
2. ✅ **maxLength (32)**: Explicit check with clear error message  
3. ✅ **pattern**: Pre-compiled regex matching schema exactly (`^[a-zA-Z0-9_-]+$`)
4. ✅ **Reserved keyword**: Case-insensitive check for "copilot" with explicit "(reserved)" label
5. ✅ **Empty string handling**: Allowed (uses default "memory")

**Integration Points**:
- Line 158: Called in array configuration parsing
- Line 291: Called in object configuration parsing

### Error Messages

All validation error messages are:
- **Descriptive**: State what constraint failed
- **Actionable**: Include the actual value received
- **Consistent**: Follow same format pattern

```
❌ branch-prefix must be at least 4 characters long, got 3
❌ branch-prefix must be at most 32 characters long, got 33
❌ branch-prefix must contain only alphanumeric characters, hyphens, and underscores, got 'my@prefix'
❌ branch-prefix cannot be 'copilot' (reserved)

3. Test Coverage (Go)

Location: /home/runner/work/gh-aw/gh-aw/pkg/workflow/repo_memory_test.go

Test Functions

1. TestBranchPrefixValidation (lines 715-829)

   • 16 test cases covering all validation rules
   • Tests valid inputs: alphanumeric, hyphens, underscores, mixed, boundary cases (4 chars, 32 chars)
   • Tests invalid inputs: too short (3 chars), too long (33 chars), special characters, reserved word
   • Tests case-insensitivity of "copilot" reserved word

2. TestBranchPrefixInConfig (lines 831-852)

   • Tests object-style configuration
   • Validates prefix is correctly extracted and applied to branch name

3. TestBranchPrefixInArrayConfig (lines 854-881)

   • Tests array-style configuration
   • Validates prefix applies to all memory entries

4. TestBranchPrefixWithExplicitBranchName (lines 883-906)

   • Tests that explicit branch-name overrides prefix
   • Validates precedence rules

5. TestInvalidBranchPrefixRejectsConfig (lines 908-936)

   • Tests that invalid prefixes cause configuration rejection
   • Validates error propagation

Test Case Examples

{
    name:    "valid prefix - exactly 4 chars",
    prefix:  "mem1",
    wantErr: false,
},
{
    name:    "valid prefix - exactly 32 chars",
    prefix:  "12345678901234567890123456789012",
    wantErr: false,
},
{
    name:    "invalid - too short (3 chars)",
    prefix:  "mem",
    wantErr: true,
    errMsg:  "must be at least 4 characters long",
},
{
    name:    "invalid - reserved word 'copilot'",
    prefix:  "copilot",
    wantErr: true,
    errMsg:  "cannot be 'copilot' (reserved)",
},
{
    name:    "invalid - reserved word 'COPILOT' (case-insensitive)",
    prefix:  "COPILOT",
    wantErr: true,
    errMsg:  "cannot be 'copilot' (reserved)",
},

4. Documentation

Reference Documentation

Location 1: /home/runner/work/gh-aw/gh-aw/docs/src/content/docs/reference/memory.md

Line 124:

Branch Prefix: Use branch-prefix to customize the branch name prefix (default is memory). The prefix must be 4-32 characters, alphanumeric with hyphens/underscores, and cannot be copilot. When set, branches are created as {branch-prefix}/{id} instead of memory/{id}.

Location 2: /home/runner/work/gh-aw/gh-aw/docs/src/content/docs/reference/frontmatter-full.md

Lines 1625-1627:

# Branch prefix for memory storage (default: 'memory'). Must be 4-32 characters,
# alphanumeric with hyphens/underscores, and cannot be 'copilot'. Branch will be
# named {branch-prefix}/{id}

Documentation Coverage:

• ✅ minLength (4): Explicitly stated
• ✅ maxLength (32): Explicitly stated
• ✅ pattern: Described as "alphanumeric with hyphens/underscores"
• ✅ Reserved keyword: "cannot be 'copilot'" explicitly mentioned
• ✅ Default value: "memory" documented
• ✅ Behavior: Branch naming pattern {branch-prefix}/{id} explained

Usage Examples

Location: /home/runner/work/gh-aw/gh-aw/docs/src/content/docs/reference/memory.md

Lines 111-122 (Object configuration):

tools:
  repo-memory:
    branch-name: memory/custom-agent
    branch-prefix: campaigns  # Custom prefix instead of "memory"
    description: "Long-term insights"

Lines 131-141 (Array configuration):

tools:
  repo-memory:
    - id: insights
      branch-prefix: daily  # Creates daily/insights branch
      file-glob: ["daily/insights/*.md"]
    - id: state
      file-glob: ["memory/state/*.json"]

5. Workflow Usage (Real-World Examples)

Location: /home/runner/work/gh-aw/gh-aw/.github/workflows/daily-code-metrics.md

Lines 13-14:

tools:
  repo-memory:
    branch-prefix: daily
    description: "Historical code quality and health metrics"

This demonstrates the feature in production use with a valid 5-character prefix.

6. Schema-Implementation Consistency Analysis

✅ Perfect Alignment

Constraint	Schema	Implementation	Tests	Documentation
Type	string	✅ string	✅ Tested	✅ Documented
minLength	4	✅ len(prefix) < 4 check	✅ Test case: 3 chars → error	✅ "4-32 characters"
maxLength	32	✅ len(prefix) > 32 check	✅ Test case: 33 chars → error	✅ "4-32 characters"
pattern	^[a-zA-Z0-9_-]+$	✅ Identical regex	✅ Multiple test cases	✅ "alphanumeric with hyphens/underscores"
Reserved	"cannot be 'copilot'"	✅ Case-insensitive check	✅ Tested copilot/Copilot/COPILOT	✅ "cannot be 'copilot'"
Default	"memory" (in description)	✅ Default: "memory"	✅ Empty string test	✅ "(default: 'memory')"

Error Message Documentation

Gap Identified: ❌ Error messages are NOT explicitly documented

The implementation produces 4 distinct error messages:

1. "branch-prefix must be at least 4 characters long, got %d"
2. "branch-prefix must be at most 32 characters long, got %d"
3. "branch-prefix must contain only alphanumeric characters, hyphens, and underscores, got '%s'"
4. "branch-prefix cannot be 'copilot' (reserved)"

Current Documentation: Constraints are documented in prose, but specific error message text is not shown.

Recommendation: This is acceptable - error messages are self-explanatory and map directly to documented constraints. No action needed.

7. Key Success Factors (Gold Standard Characteristics)

Why This Is Exemplary

1. Schema Completeness

   • All constraints explicitly defined in JSON Schema
   • Clear descriptions in schema
   • Consistent across both object and array configurations

2. Implementation Fidelity

   • Every schema constraint enforced in code
   • Additional business rule (reserved keyword) properly implemented
   • Pre-compiled regex for performance
   • Clear, actionable error messages

3. Comprehensive Testing

   • 16+ test cases covering all validation paths
   • Boundary testing (4 chars, 32 chars, 3 chars, 33 chars)
   • Reserved word testing with case variations
   • Integration tests for both configuration formats
   • Precedence testing (explicit branch-name override)

4. Documentation Quality

   • Constraints documented in reference docs
   • Multiple usage examples provided
   • Both object and array configurations shown
   • Default behavior explained
   • Used in real production workflows

5. Consistency

   • Regex pattern identical in schema and code
   • Error messages map to documented constraints
   • Reserved keyword mentioned in schema description and enforced in code

8. Lessons for Other Features

Checklist for Gold Standard Implementation

• Schema: Define all constraints (type, minLength, maxLength, pattern, enum)
• Schema: Document reserved keywords and business rules in description
• Implementation: Enforce ALL schema constraints with explicit checks
• Implementation: Use pre-compiled regexes matching schema patterns exactly
• Implementation: Provide clear, actionable error messages with actual values
• Tests: Boundary testing for numeric constraints
• Tests: Valid and invalid cases for patterns
• Tests: Case sensitivity testing for reserved keywords
• Tests: Integration tests for feature usage
• Docs: State all constraints in prose
• Docs: Provide usage examples
• Docs: Document default behavior
• Usage: Use feature in real workflows to validate UX

9. Comparison with Other Features

This gold standard serves as a contrast baseline for identifying gaps in other features. When analyzing features like max-file-size, max-file-count, tracker-id, etc., we should evaluate:

1. Are schema constraints as complete as branch-prefix?
2. Are all schema constraints enforced in code?
3. Is test coverage as comprehensive?
4. Are constraints documented as clearly?
5. Do error messages match quality standards?

Any deviations from the branch-prefix pattern represent opportunities for improvement.

---

Conclusion: The branch-prefix feature demonstrates end-to-end consistency across schema, implementation, testing, and documentation. It should be referenced as the model for all feature implementations in this codebase.

AI generated by Schema Consistency Checker

• expires on Feb 7, 2026, 12:02 AM UTC

[github-actions[bot]]

This discussion was automatically closed because it expired on 2026-02-07T00:02:01.110Z.