Add standardized connector YAMLs, operational docs, and validation script

[NguyenCuong1989]

Motivation

• Provide a standardized, machine-readable set of connector definitions to normalize integration contracts and runtime guardrails across the system.
• Capture realtime cooperative execution and search-space-collapse operational specifications to guide orchestration and multi-agent behavior.
• Supply an ecosystem node map and relationship report to make dependency topology explicit for risk and migration planning.
• Add an automated validator to enforce the connector standard and catch regression in connector artifacts.

Description

• Added 12 connector specification files under connectors/ including conductor, mcp_hub, runtime_observer, llm_engine, github, jira, asana, linear, mail, telegram, web_agent, and tech_debt_auditor with standardized top-level keys and guardrails.
• Added operational documentation under docs/operations/ including REALTIME_COOPERATIVE_EXECUTION_SPEC.md, ECOSYSTEM_RELATIONSHIP_REPORT.md, ECOSYSTEM_NODE_MAP.yaml, SEARCH_SPACE_COLLAPSE_EXECUTION_MAP.md, search_space_collapse_policy.yaml, CONNECTOR_STANDARDIZATION_BASELINE.md, and realtime_phase_checklist.yaml to formalize contracts, protocols, and phase rollouts.
• Updated docs/index.md to reference the new operational artifacts and maps.
• Added an executable validation script scripts/validate_connector_standardization.py that enforces required top-level keys, queue naming conventions, contract keys, and core profile expectations for designated realtime connectors.

Testing

• Ran the connector validator with python3 scripts/validate_connector_standardization.py, which completed successfully and reported validation for the connector files (exit code 0).

---

Codex Task

Summary by Sourcery

Giới thiệu các đặc tả connector chuẩn hóa, tài liệu vận hành thực thi, và một bộ validator tự động để đảm bảo hợp đồng nhất quán và hàng rào bảo vệ cho điều phối thời gian thực trên toàn hệ sinh thái.

Tính năng mới:

• Thêm các định nghĩa connector dựa trên YAML cho hệ thống điều phối, LLM, trình theo dõi issue, VCS, thông báo, web agent và bộ kiểm toán tech-debt với các khả năng được chuẩn hóa và ngữ nghĩa hàng đợi thống nhất.
• Thêm bản đồ node hệ sinh thái có thể đọc được bằng máy và các artifact chính sách “thu gọn không gian tìm kiếm” để mô tả quan hệ phụ thuộc và hành vi thực thi quyết định (deterministic).
• Thêm một đặc tả thực thi hợp tác thời gian thực và checklist theo từng phase để hướng dẫn triển khai multi-agent và gia cố vận hành.

Cải tiến:

• Mở rộng mục lục tài liệu chính để hiển thị các đặc tả vận hành mới, bản đồ và chính sách nhằm giúp dễ khám phá hơn.

Tài liệu:

• Ghi lại baseline chuẩn hóa connector, các mối quan hệ trong hệ sinh thái, và luồng thực thi “thu gọn không gian tìm kiếm” dưới docs/operations để đồng bộ vận hành giữa các repo.

Kiểm thử:

• Thêm script validation chuẩn hóa connector để kiểm tra các file YAML của connector về cấu trúc bắt buộc, quy ước đặt tên hàng đợi, và các profile thời gian thực cốt lõi.

Original summary in English

Summary by Sourcery

Introduce standardized connector specifications, operational execution docs, and an automated validator to enforce consistent contracts and realtime orchestration guardrails across the ecosystem.

New Features:

• Add YAML-based connector definitions for orchestration, LLM, issue trackers, VCS, notifications, web agent, and tech-debt auditor with normalized capabilities and queue semantics.
• Add machine-readable ecosystem node map and search-space-collapse policy artifacts to describe dependencies and deterministic execution behavior.
• Add a realtime cooperative execution spec and phase checklist to guide multi-agent rollout and operational hardening.

Enhancements:

• Extend the main documentation index to surface new operational specs, maps, and policies for easier discovery.

Documentation:

• Document the connector standardization baseline, ecosystem relationships, and search-space-collapse execution flow under docs/operations for cross-repo operational alignment.

Tests:

• Add a connector standardization validation script that checks connector YAMLs for required structure, queue naming, and core realtime profiles.

[qodo-code-review]

CI Feedback 🧐

(Feedback updated until commit d0c993f)

A test triggered by this PR failed. Here is an AI-generated analysis of the failure:

Action: Test on Python 3.12

Failed stage: Set up job [❌]

Failed test name: ""

Failure summary: The workflow failed due to repository policy restrictions: it uses unpinned GitHub Actions versions (actions/checkout@v4, actions/setup-python@v5, codecov/codecov-action@v4). The repository NguyenCuong1989/DAIOF-Framework requires all actions to be pinned to a full-length commit SHA, so these version tags are not allowed and the run was blocked before executing any steps.

Relevant error logs: 1: ##[group]Runner Image Provisioner 2: Hosted Compute Agent ... 28: Issues: write 29: Metadata: read 30: Models: read 31: Packages: write 32: Pages: write 33: PullRequests: write 34: RepositoryProjects: write 35: SecurityEvents: write 36: Statuses: write 37: VulnerabilityAlerts: read 38: ##[endgroup] 39: Secret source: Actions 40: Prepare workflow directory 41: Prepare all required actions 42: Getting action download info 43: ##[error]The actions actions/checkout@v4, actions/setup-python@v5, and codecov/codecov-action@v4 are not allowed in NguyenCuong1989/DAIOF-Framework because all actions must be pinned to a full-length commit SHA.

[qodo-code-review]

CI Feedback 🧐

A test triggered by this PR failed. Here is an AI-generated analysis of the failure:

Action: build (3.10)

Failed stage: Set up job [❌]

Failed test name: ""

Failure summary: The workflow failed during action preparation because it uses unpinned GitHub Actions references: - actions/checkout@v4 - actions/setup-python@v5 The repository NguyenCuong1989/DAIOF-Framework enforces a policy requiring all actions to be pinned to a full-length commit SHA, so version tags like @v4 and @v5 are rejected.

Relevant error logs: 1: ##[group]Runner Image Provisioner 2: Hosted Compute Agent ... 28: Issues: write 29: Metadata: read 30: Models: read 31: Packages: write 32: Pages: write 33: PullRequests: write 34: RepositoryProjects: write 35: SecurityEvents: write 36: Statuses: write 37: VulnerabilityAlerts: read 38: ##[endgroup] 39: Secret source: Actions 40: Prepare workflow directory 41: Prepare all required actions 42: Getting action download info 43: ##[error]The actions actions/checkout@v4 and actions/setup-python@v5 are not allowed in NguyenCuong1989/DAIOF-Framework because all actions must be pinned to a full-length commit SHA.

[qodo-code-review]

CI Feedback 🧐

A test triggered by this PR failed. Here is an AI-generated analysis of the failure:

Action: build (3.9)

Failed stage: Set up job [❌]

Failed test name: ""

Failure summary: The workflow failed due to a repository policy that requires all GitHub Actions to be pinned to a full-length commit SHA. - The workflow references actions/checkout@v4 and actions/setup-python@v5, which are version tags rather than full commit SHAs. - GitHub blocked the run with: The actions actions/checkout@v4 and actions/setup-python@v5 are not allowed ... because all actions must be pinned to a full-length commit SHA.

Relevant error logs: 1: ##[group]Runner Image Provisioner 2: Hosted Compute Agent ... 28: Issues: write 29: Metadata: read 30: Models: read 31: Packages: write 32: Pages: write 33: PullRequests: write 34: RepositoryProjects: write 35: SecurityEvents: write 36: Statuses: write 37: VulnerabilityAlerts: read 38: ##[endgroup] 39: Secret source: Actions 40: Prepare workflow directory 41: Prepare all required actions 42: Getting action download info 43: ##[error]The actions actions/checkout@v4 and actions/setup-python@v5 are not allowed in NguyenCuong1989/DAIOF-Framework because all actions must be pinned to a full-length commit SHA.

[qodo-code-review]

CI Feedback 🧐

A test triggered by this PR failed. Here is an AI-generated analysis of the failure:

Action: Build and Push Docker Image

Failed stage: Set up job [❌]

Failed test name: ""

Failure summary: The workflow failed during the “Prepare all required actions” step because the repository policy requires all GitHub Actions to be pinned to a full-length commit SHA, but the workflow references actions by version tags instead: - actions/checkout@v4 - docker/login-action@v3 - docker/metadata-action@v5 - docker/setup-buildx-action@v3 - docker/build-push-action@v6 Because these actions are not pinned to a full commit SHA, they are blocked and the job stops before running any build or tests.

Relevant error logs: 1: ##[group]Runner Image Provisioner 2: Hosted Compute Agent ... 13: ##[group]Runner Image 14: Image: ubuntu-24.04 15: Version: 20260413.86.1 16: Included Software: https://github.com/actions/runner-images/blob/ubuntu24/20260413.86/images/ubuntu/Ubuntu2404-Readme.md 17: Image Release: https://github.com/actions/runner-images/releases/tag/ubuntu24%2F20260413.86 18: ##[endgroup] 19: ##[group]GITHUB_TOKEN Permissions 20: Contents: read 21: Metadata: read 22: Packages: write 23: ##[endgroup] 24: Secret source: Actions 25: Prepare workflow directory 26: Prepare all required actions 27: Getting action download info 28: ##[error]The actions actions/checkout@v4, docker/login-action@v3, docker/metadata-action@v5, docker/setup-buildx-action@v3, and docker/build-push-action@v6 are not allowed in NguyenCuong1989/DAIOF-Framework because all actions must be pinned to a full-length commit SHA.

[sourcery-ai]

Hướng dẫn cho người review (Reviewer's Guide)

Giới thiệu một schema YAML chuẩn hóa cho các connector, chính thức hóa cơ chế thực thi realtime mang tính hợp tác và các thao tác thu hẹp không gian tìm kiếm (search-space-collapse) thông qua tài liệu mới và bản đồ hệ sinh thái, liên kết các artifact này vào mục lục tài liệu, và thêm một script Python dùng để kiểm tra việc tuân thủ schema connector và các hợp đồng core realtime profile.

Thay đổi theo từng file

Thay đổi	Chi tiết	File
Chuẩn hóa schema YAML cho connector trên các thành phần orchestration, integration và notification.	Thêm định nghĩa connector với cấu trúc chung ở cấp cao nhất bao gồm id, type, version, capabilities, mailboxes, scheduler, triggers, state, health, policies, guardrails và contracts. Định nghĩa các realtime orchestration profile cho conductor, mcp_hub và runtime_observer thông qua các profile contracts.input_schema/output_schema để hỗ trợ luồng công việc search-space-collapse và deny-rule. Chuẩn hóa cách đặt tên queue và capabilities của connector cho các connector GitHub, Jira, Asana, Linear, mail, telegram, web_agent, llm_engine và tech_debt_auditor.	connectors/conductor.yaml connectors/mcp_hub.yaml connectors/runtime_observer.yaml connectors/llm_engine.yaml connectors/github.yaml connectors/jira.yaml connectors/asana.yaml connectors/linear.yaml connectors/mail.yaml connectors/telegram.yaml connectors/web_agent.yaml connectors/tech_debt_auditor.yaml
Ghi lại topology hệ sinh thái, cơ chế thực thi hợp tác realtime và policy search-space-collapse trong các artifact vận hành.	Ghi nhận các phụ thuộc upstream/downstream và quan hệ mesh giữa các connector trong một báo cáo quan hệ có thể đọc được bởi con người và một bản đồ node hệ sinh thái có thể đọc được bởi máy. Chỉ định spec thực thi hợp tác realtime, bao gồm trách nhiệm của conductor/MCP hub/runtime observer, vòng đời trạng thái task, các giai đoạn rollout và các cổng an toàn (safety gate). Chính thức hóa cách thực thi và policy search-space-collapse trong Markdown và YAML, bao gồm các bất biến (invariants), quá trình “hóa thạch hóa” deny-rule, tái phân bổ tài nguyên và telemetry/tiêu chí chấp nhận. Xác định baseline chuẩn hóa connector và checklist theo giai đoạn cho việc rollout realtime, liên kết kỳ vọng schema với từng giai đoạn vận hành.	docs/operations/ECOSYSTEM_RELATIONSHIP_REPORT.md docs/operations/ECOSYSTEM_NODE_MAP.yaml docs/operations/REALTIME_COOPERATIVE_EXECUTION_SPEC.md docs/operations/SEARCH_SPACE_COLLAPSE_EXECUTION_MAP.md docs/operations/search_space_collapse_policy.yaml docs/operations/CONNECTOR_STANDARDIZATION_BASELINE.md docs/operations/realtime_phase_checklist.yaml
Xuất bản tài liệu vận hành mới trong mục lục tài liệu chính.	Liên kết spec thực thi realtime mới, các báo cáo hệ sinh thái, bản đồ node và tài liệu search-space-collapse từ mục lục (index) của docs.	docs/index.md
Thêm script validator tự động để đảm bảo chuẩn hóa connector và các core realtime profile.	Cài đặt một script Python tải toàn bộ connectors/*.yaml, kiểm tra các key bắt buộc ở cấp cao nhất và trong contracts, xác thực pattern tên queue và ID dạng snake_case, và xác minh kỳ vọng profile cho các connector core realtime. Định nghĩa pattern CLI trả về mã khác 0 khi validation thất bại và in ra thông điệp pass/fail để dùng trong môi trường dev cục bộ hoặc CI.	scripts/validate_connector_standardization.py

---

Mẹo và câu lệnh

Tương tác với Sourcery

• Kích hoạt một lượt review mới: Comment @sourcery-ai review trên pull request.
• Tiếp tục thảo luận: Trả lời trực tiếp vào các comment review của Sourcery.
• Tạo GitHub issue từ một comment review: Yêu cầu Sourcery tạo một issue từ comment review bằng cách trả lời comment đó. Bạn cũng có thể trả lời comment review với @sourcery-ai issue để tạo issue từ comment đó.
• Tạo tiêu đề pull request: Viết @sourcery-ai ở bất kỳ đâu trong tiêu đề pull request để tạo tiêu đề bất kỳ lúc nào. Bạn cũng có thể comment @sourcery-ai title trên pull request để (tái) tạo tiêu đề bất kỳ lúc nào.
• Tạo tóm tắt pull request: Viết @sourcery-ai summary ở bất kỳ đâu trong phần nội dung (body) của pull request để tạo tóm tắt PR ngay tại vị trí bạn muốn. Bạn cũng có thể comment @sourcery-ai summary trên pull request để (tái) tạo tóm tắt bất kỳ lúc nào.
• Tạo reviewer's guide: Comment @sourcery-ai guide trên pull request để (tái) tạo reviewer's guide bất kỳ lúc nào.
• Resolve tất cả comment của Sourcery: Comment @sourcery-ai resolve trên pull request để resolve tất cả comment của Sourcery. Hữu ích khi bạn đã xử lý hết comment và không muốn thấy chúng nữa.
• Dismiss tất cả review của Sourcery: Comment @sourcery-ai dismiss trên pull request để dismiss toàn bộ các review hiện có của Sourcery. Đặc biệt hữu ích nếu bạn muốn bắt đầu lại với một lượt review mới – đừng quên comment @sourcery-ai review để kích hoạt review mới!

Tùy chỉnh trải nghiệm của bạn

Truy cập dashboard của bạn để:

• Bật hoặc tắt các tính năng review như tóm tắt pull request do Sourcery tạo, reviewer's guide, và các tính năng khác.
• Thay đổi ngôn ngữ review.
• Thêm, xóa hoặc chỉnh sửa các hướng dẫn review tùy chỉnh.
• Điều chỉnh các cài đặt review khác.

Nhận hỗ trợ

• Liên hệ đội ngũ hỗ trợ để đặt câu hỏi hoặc gửi phản hồi.
• Truy cập tài liệu của chúng tôi để xem các hướng dẫn chi tiết và thông tin.
• Giữ liên lạc với đội Sourcery bằng cách theo dõi chúng tôi trên X/Twitter, LinkedIn hoặc GitHub.

Original review guide in English

Reviewer's Guide

Introduces a standardized YAML schema for connectors, formalizes realtime cooperative execution and search-space-collapse operations through new docs and ecosystem maps, wires these artifacts into the docs index, and adds a Python validator script to enforce connector schema and core realtime profile contracts.

File-Level Changes

Change	Details	Files
Standardized connector YAML schema across orchestration, integration, and notification components.	Added connector definitions with common top-level structure including id, type, version, capabilities, mailboxes, scheduler, triggers, state, health, policies, guardrails, and contracts. Defined realtime orchestration profiles for conductor, mcp_hub, and runtime_observer via contracts.input_schema/output_schema profiles to support search-space-collapse and deny-rule workflows. Normalized queue naming and connector capabilities for GitHub, Jira, Asana, Linear, mail, telegram, web_agent, llm_engine, and tech_debt_auditor connectors.	connectors/conductor.yaml connectors/mcp_hub.yaml connectors/runtime_observer.yaml connectors/llm_engine.yaml connectors/github.yaml connectors/jira.yaml connectors/asana.yaml connectors/linear.yaml connectors/mail.yaml connectors/telegram.yaml connectors/web_agent.yaml connectors/tech_debt_auditor.yaml
Documented ecosystem topology, realtime cooperative execution, and search-space-collapse policy in operational artifacts.	Captured upstream/downstream dependencies and connector mesh relationships in a human-readable relationship report and a machine-readable ecosystem node map. Specified the realtime cooperative execution spec, including conductor/MCP hub/runtime observer responsibilities, task state lifecycle, rollout phases, and safety gates. Formalized search-space-collapse execution and policy in Markdown and YAML, including invariants, deny-rule fossilization, resource reallocation, and telemetry/acceptance criteria. Defined a connector standardization baseline and a phase checklist for realtime rollout, linking schema expectations to operational phases.	docs/operations/ECOSYSTEM_RELATIONSHIP_REPORT.md docs/operations/ECOSYSTEM_NODE_MAP.yaml docs/operations/REALTIME_COOPERATIVE_EXECUTION_SPEC.md docs/operations/SEARCH_SPACE_COLLAPSE_EXECUTION_MAP.md docs/operations/search_space_collapse_policy.yaml docs/operations/CONNECTOR_STANDARDIZATION_BASELINE.md docs/operations/realtime_phase_checklist.yaml
Exposed new operational documentation in the main docs index.	Linked new realtime execution spec, ecosystem reports, node map, and search-space-collapse documents from the docs index navigation.	docs/index.md
Added an automated validator script to enforce connector standardization and realtime core profiles.	Implemented a Python script that loads all connectors/*.yaml, checks for required top-level and contracts keys, validates queue name patterns and snake_case IDs, and verifies profile expectations for core realtime connectors. Defined a CLI entry pattern returning non-zero on validation failures and emitting pass/fail messages for use in local dev or CI.	scripts/validate_connector_standardization.py

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.