[#370] 🤖 - Localize branchsync notices for any repository locale

[efraespada]

📌 Summary

Localizes branch synchronization notices through a typed, versioned message-catalog boundary. The observer resolves one complete catalog slice before publishing, supports bundled en-US and es-ES copy, and falls back atomically to English for invalid or unavailable dynamic localization while preserving commands, refs, URLs, markers, and machine-readable state.

---

🎯 Related Issues / Tickets

• Closes [#370] 🤖 - Localize branchsync notices for any repository locale #370

---

🧩 Scope of Changes

• Added:
  • Typed branch-sync message IDs with bundled English and Spanish catalogs.
  • Shared resolved-catalog view support for static and dynamic localization.
  • Tests for locale selection, pluralization, dynamic resolution, fallback, and publication ordering.
• Updated:
  • Branch-sync notice rendering and observer composition.
  • Branch observation context to carry agent configuration.
  • Branch synchronization documentation and specification catalog evidence.
  • Generated build/cli/index.js and build/github_action/index.js bundles.
• Removed:
  • Feature-local English/Spanish branching from branch-sync notification rendering.
• Refactored:
  • Branch-sync publication to consume resolved localized messages while keeping semantic identity and state transitions locale-independent.

---

🛠️ Technical Details

• Bundled en-US and es-ES catalogs are selected by exact locale or compatible base language.
• Other valid BCP-47 locales use one schema-constrained catalog request for the complete branch-sync message slice.
• Incomplete, invalid, or unavailable dynamic output falls back atomically to English before any comment is written.
• Plural-aware message descriptors replace commit(s) copy for singular and plural counts.
• Branch names are rendered as bounded, Markdown-safe inline references, including neutralization of @ mentions.
• /copilot sync-branch, branch identities, comparison URLs, publication markers, and machine-readable state remain unchanged across locales.
• The language capability is wired at createSingleActionUseCaseCompositionRoot, keeping the runtime and dynamic localization cost boundary explicit.

---

🔍 How to Test

1. Install dependencies with pnpm install and build the project with corepack pnpm@​10.12.4 run build.
2. Run the focused branch-sync tests, or run the complete suite with corepack pnpm@​10.12.4 run test:coverage.
3. Verify type safety and linting with corepack pnpm@​10.12.4 run typecheck and corepack pnpm@​10.12.4 run lint.
4. Run documentation, workflow, specification, and generated-bundle validation with corepack pnpm@​10.12.4 run validate:agent-docs, corepack pnpm@​10.12.4 run validate:docs-page, corepack pnpm@​10.12.4 run validate:documentation, corepack pnpm@​10.12.4 run validate:workflows, corepack pnpm@​10.12.4 run validate:specifications, and git diff --check.
5. Exercise branch observation with en-US, es-ES, a compatible locale such as es-MX, and an unsupported locale to confirm localized output, stable machine content, and atomic English fallback.

---

🧪 Test Coverage

• Unit tests
• Integration tests
• End-to-end (E2E) tests
• Manual testing only (explain why)

Coverage includes catalog completeness and locale selection, singular and plural rendering, dynamic catalog resolution, atomic fallback, observer publication ordering, context projection, and publication-boundary enforcement.

---

📸 Screenshots / Recordings (UI changes only)

Not applicable; this change updates generated GitHub comment content and automated documentation rather than an interactive UI.

---

⚠️ Breaking Changes

• None

---

🚀 Deployment Notes

• Requires database migration
• Requires environment variable changes
• Requires feature flag toggle
• No special deployment steps

Details: Existing locale configuration is reused. Bundled locales require no new configuration; dynamic localization uses the already configured language capability and remains bounded to one request for a non-bundled locale.

---

🔒 Security Considerations

• No security impact
• Input validation changes
• Authentication / authorization changes
• Sensitive data handling changes

Branch references are sanitized and bounded for Markdown presentation, while commands, URLs, markers, and machine state remain stable. Dynamic catalog output is validated as a complete slice before publication.

---

📈 Performance Impact

• No performance impact
• Improves performance
• Potential performance regression (explain)

Bundled en-US and es-ES catalogs avoid dynamic provider calls. A non-bundled locale performs at most one bounded catalog-resolution request per observer run, before publication.

---

📝 Notes for Reviewers

Please verify the single-catalog-resolution boundary and the invariant that no branch-sync comment is written until the complete catalog slice has resolved. Also check that localized prose does not alter /copilot sync-branch, branch references, comparison URLs, publication markers, or machine-readable state.

---

✅ Checklist

• I have self-reviewed my code
• Code follows project standards and conventions
• Tests have been added or updated
• Documentation has been updated (if applicable)
• No new warnings or lint errors
• Breaking contract changes and required consumer updates are documented

---

📚 Additional Context

The specification catalog registers the new branch-sync catalog policy, resolved-catalog policy, observer use case, and their test evidence. Generated build/cli/index.js and build/github_action/index.js are included and validated.

[docs-page]

To preview the documentation for this pull request, visit the following URL:

docs.page/vypdev/copilot~370

Documentation is deployed and generated using docs.page

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 92.12%. Comparing base (274db40) to head (d71c6ff).
⚠️ Report is 706 commits behind head on develop.

Additional details and impacted files

@@             Coverage Diff             @@
##           develop     #370      +/-   ##
===========================================
+ Coverage    90.94%   92.12%   +1.18%     
===========================================
  Files          135      642     +507     
  Lines         6251    16463   +10212     
  Branches      1338     4240    +2902     
===========================================
+ Hits          5685    15167    +9482     
- Misses         172      523     +351     
- Partials       394      773     +379     

Files with missing lines	Coverage Δ
...pplication/policies/branch_sync_message_catalog.ts	100.00% <100.00%> (ø)
...cation/policies/branch_sync_notification_policy.ts	100.00% <100.00%> (ø)
...cation/policies/resolved_message_catalog_policy.ts	100.00% <100.00%> (ø)
...n/usecases/actions/observe_branch_sync_use_case.ts	100.00% <100.00%> (ø)
...pplication/usecases/push_single_action_contexts.ts	98.85% <ø> (ø)
...ure/composition/main_run_route_composition_root.ts	93.22% <100.00%> (ø)

... and 698 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[vypbot]

Bugbot: review incomplete

Current status: The review of d71c6ff has partial coverage and cannot declare the whole pull request clean.

Action: Inspect the omitted items or reduce the PR scope. Rerun the review only after changing the scope, limits, or access.

Incomplete coverage

• selection: complete; retained=1
• issue-comments: complete; retained=3
• pull-request-comments: complete; retained=0
• review-threads: complete; retained=0
• diff: partial; retained=13, truncated=1
• previous-findings: complete; retained=0
• human-conversation: partial; retained=2, truncated=1
• rules: complete; retained=0

Pull request · Verified commit · Workflow run