[#374] 🤖 - Localize and simplify deployment presentation

[efraespada]

📌 Summary

Localizes deployment orchestration across issue dashboards, milestone notifications, managed pull requests, and GitHub Actions Job Summaries. Adds locale-aware catalogs, safe BCP-47 resolution, atomic English fallback, durable locale snapshots, and compatibility for legacy version-1 operation state.

---

🎯 Related Issues / Tickets

• Closes [#374] 🤖 - Localize and simplify deployment presentation #374

---

🧩 Scope of Changes

• Added:
  • Typed deployment message catalogs with complete en-US and es-ES support.
  • Dynamic catalog resolution for valid unsupported BCP-47 locales.
  • Repository, issue, and pull-request locale handling with English defaults.
  • Durable locale snapshots for new deployment operations.
  • Deployment presentation, catalog resolution, fallback, and security tests.
• Updated:
  • Issue dashboards, milestone messages, managed PRs, and Job Summaries to use effective destination locales.
  • Release and hotfix workflow templates to pass repository-locale and preserve inherited issue and pull-request locale overrides.
  • Deployment documentation, specifications, capability catalog, coverage budgets, and generated bundles.
• Removed:
  • Deployment UI replay of internal Result.steps.
  • Redundant internal “created”, “reused”, and “skipped” logs from operator-facing Job Summaries.
• Refactored:
  • Deployment presentation and message resolution behind reusable policies and runtime dependencies.
  • Deployment milestone publication from rendered strings to structured semantic inputs.

---

🛠️ Technical Details

• New durable operations resolve and snapshot the complete canonical locale profile when they start. Later repository Variable changes cannot switch an in-flight deployment between languages.
• Legacy version-1 operation state without locale metadata remains valid and uses the current effective locale profile until completion.
• Catalogs are resolved and cached once per destination. Unsupported locales use a bounded planning-agent catalog request; unavailable, incomplete, invalid, or unsafe responses fall back atomically to English without mixed-language artifacts.
• Presentation rendering remains independent of GitHub adapters and preserves provider facts such as refs, SHAs, tags, IDs, and machine-readable fallback reasons.
• Dynamic catalog text rejects unsafe Markdown, links, mentions, commands, control characters, bidi controls, and table delimiters before publication.
• Job Summaries report semantic deployment facts, distinguish external waits from workflow failures, and include status, required action, durable revision facts, retryability, and descriptive links.

---

🔍 How to Test

1. Run pnpm test and pnpm run test:coverage.
2. Run pnpm run typecheck and pnpm run lint.
3. Run pnpm run validate:documentation, pnpm run validate:workflows, pnpm run validate:specifications, pnpm run validate:npm-package, pnpm run validate:build, and pnpm run smoke:npm-package.
4. Exercise a release or hotfix deployment with repository-locale set to en-US or es-ES, and verify that the issue dashboard, milestone messages, managed PR, and Job Summary use their configured destination locale.
5. Configure a valid unsupported locale such as fr-FR and verify that a safe catalog is resolved or the complete artifact falls back to English.
6. Change locale configuration during an in-flight deployment and verify that the durable operation continues using its snapshotted locale profile.
7. Verify that legacy version-1 operation state without locale metadata remains readable and continues with the current effective profile.
8. Verify that Job Summaries do not contain replayed internal step logs such as “created” or “reused”.

---

🧪 Test Coverage

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

---

📸 Screenshots / Recordings (UI changes only)

Not included. The change affects generated GitHub issue, pull-request, milestone, and Job Summary content rather than a standalone visual interface.

---

⚠️ Breaking Changes

• None

---

🚀 Deployment Notes

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

Details: Existing version-1 deployment state remains compatible. New deployments snapshot the effective locale profile automatically, and generated bundles are included in the change. Locale Variables remain optional because issue and pull-request overrides inherit repository-locale when empty.

---

🔒 Security Considerations

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

Dynamic catalog output is validated before Markdown publication, including rejection of unsafe markup, URLs, mentions, commands, bidi controls, control characters, and table delimiters. Provider facts and untrusted values remain subject to bounded rendering and URL validation.

---

📈 Performance Impact

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

Catalog resolution is cached once per destination. The additional resolution work is bounded and does not materially change the performance characteristics of supported locales.

---

📝 Notes for Reviewers

Please review the locale-scope mapping carefully: issue surfaces use the effective issue locale, managed PRs use the effective pull-request locale, and Job Summaries use the repository locale. Also verify atomic fallback behavior, compatibility with legacy version-1 operations, and removal of internal step-log replay from operator-facing output.

---

✅ 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 change updates the deployment orchestration specification and repository localization evidence, adds coverage budgets for the new presentation behavior, and includes regenerated action, CLI, and API bundles.

[docs-page]

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

docs.page/vypdev/copilot~374

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.44%. Comparing base (274db40) to head (c6862c5).
⚠️ Report is 719 commits behind head on develop.

Additional details and impacted files

@@             Coverage Diff             @@
##           develop     #374      +/-   ##
===========================================
+ Coverage    90.94%   92.44%   +1.49%     
===========================================
  Files          135      644     +509     
  Lines         6251    16644   +10393     
  Branches      1338     4258    +2920     
===========================================
+ Hits          5685    15386    +9701     
- Misses         172      505     +333     
- Partials       394      753     +359     

Files with missing lines	Coverage Δ
src/actions/github_action_completion.ts	90.47% <100.00%> (ø)
src/application/policies/action_summary_policy.ts	96.96% <100.00%> (ø)
...application/policies/deployment_message_catalog.ts	100.00% <100.00%> (ø)
src/application/policies/deployment_plan_policy.ts	88.75% <ø> (ø)
...ication/policies/deployment_presentation_policy.ts	100.00% <100.00%> (ø)
...ation/services/deployment_orchestration_runtime.ts	86.52% <100.00%> (ø)
...ns/deployment_handlers/accept_promotion_handler.ts	100.00% <ø> (ø)
...deployment_handlers/confirm_publication_handler.ts	97.95% <ø> (ø)
...s/deployment_handlers/prepare_promotion_handler.ts	93.33% <ø> (ø)
...ions/deployment_handlers/reconciliation_handler.ts	95.12% <ø> (ø)
... and 5 more

... and 691 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 c6862c5 has partial coverage and cannot declare the whole pull request clean.

Action: Inspect the omitted items or reduce the pull request 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=1
• review-threads: complete; retained=1
• diff: partial; retained=20, omitted=18, truncated=2
• previous-findings: complete; retained=1
• human-conversation: partial; retained=1, truncated=1
• rules: complete; retained=0

Pull request · Verified commit · Workflow run

[vypbot]

Current status: Overall coverage is partial; this snapshot does not prove that all of its findings are resolved.
Last reconciled on c6862c5. See aggregate Bugbot status.

🤖 Bugbot review snapshot

Bugbot reported 1 potential problem when commit 519de5d was analyzed. This snapshot is historical; use the status block above for current state. 1 finding is linked to changed code.

Findings

• medium: Publish the sanitized failure message in milestone comments — src/application/services/deployment_orchestration_runtime.ts:70