📋 docs: add detailed scheduled tasks integration plan

[AndreiDrang]

📋 Scheduled Tasks Integration Plan

Summary

Добавлены детальные планы интеграции фичи периодического обновления AGENTS.md файлов в zai-code-bot.

What's Added

1. SCHEDULED_TASKS_INTEGRATION_PLAN.md

Детальный технический план интеграции с:

• Архитектурой решения
• Детальным планом интеграции по фазам
• Техническими деталями реализации
• Критериями успеха
• Вопросами и ответами
• Полезными ресурсами

2. SCHEDULED_TASKS_QUICK_START.md

Быстрое руководство для пользователей с:

• Быстрой настройкой за 3 шага
• Примерами конфигурации
• Руководством по устранению неполадок
• Примерами cron-выражений
• Советами и лучшими практиками

Why This PR

Этот PR адресует запрос пользователя на:

1. ✅ Интеграция как отдельный хендлер - Документирована существующая архитектура
2. ✅ Гибкая настройка расписания - YAML-конфигурация подробно описана
3. ✅ Автоматическое выполнение и PR - Алгоритмы и потоки данных описаны
4. ✅ Гибкость для будущих команд - Архитектура расширяемости документирована

Current Status

Фича уже реализована в этом форке! Эти документы:

• Документируют существующую реализацию
• Предоставляют план для улучшений и расширений
• Служат справочником для пользователей
• Помогают в будущем развитии

Next Steps

1. Обсудить и утвердить план
2. Реализовать улучшения из Фазы 2 (опционально)
3. Добавить документацию в README.md
4. Создать docs/scheduled-tasks.md

Related Files

• src/lib/handlers/scheduled.js - Основной обработчик
• src/lib/config/scheduled-config.js - Конфигурация
• .zai-scheduled.yml - Конфигурация для этого репо
• .zai-scheduled.yml.template - Шаблон для пользователей
• .github/workflows/zai-agents-update.yml - Пример workflow

---

Note: Это draft PR для обсуждения. После утверждения планов можно будет приступить к реализации улучшений.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 75.52%. Comparing base (5a379a5) to head (a13a5ba).

Additional details and impacted files

@@           Coverage Diff           @@
##             main      #12   +/-   ##
=======================================
  Coverage   75.52%   75.52%           
=======================================
  Files          22       22           
  Lines        6500     6500           
=======================================
  Hits         4909     4909           
  Misses       1591     1591           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 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.

[github-actions]

Z.ai Code Review

## 🔍 Review Summary
The PR introduces comprehensive documentation for a "Scheduled Tasks" feature, including a detailed integration plan and a quick start guide. The architecture is well-thought-out, covering event handling, configuration via YAML, and automation workflows. However, there are significant concerns regarding hardcoded dependencies in the examples and the robustness of AI response parsing, along with minor language consistency issues.

## 🚨 Critical Issues & Bugs

• SCHEDULED_TASKS_QUICK_START.md: Hardcoded External Dependency (Supply Chain Risk)
  • Description: The Quick Start guide and the Integration Plan explicitly include a hardcoded Gist URL belonging to a specific user (https://gist.githubusercontent.com/AndreiDrang/...). Users copying this configuration will depend on a third-party resource that can be modified, deleted, or hijacked, leading to arbitrary code execution in their CI/CD pipeline.
  • Impact: Users following the guide will execute unverified code if the Gist changes, or their workflows will break if the Gist is deleted.
  • Fix: Use placeholders or instruct users to create their own Gist.

  # Bad
  gist_url: https://gist.githubusercontent.com/AndreiDrang/1580ae796fe56074b600cee6352a5f14/raw
  
  # Good
  gist_url: https://gist.githubusercontent.com/YOUR_USERNAME/YOUR_GIST_ID/raw

## 💡 Suggestions & Best Practices

• SCHEDULED_TASKS_INTEGRATION_PLAN.md: JSON Parsing Robustness & Security

  • Description: The proposed JSON parsing logic (Phase 2.3) relies on Regex (/\{[\s\S]*\}/) to extract JSON from the LLM response. This is fragile; if the LLM generates conversational text containing braces before or after the JSON block, this regex might capture invalid JSON or too much content.
  • Fix: Implement strict boundary detection or a parser specifically designed for markdown code blocks, followed by schema validation (e.g., using Zod or Ajv) to ensure the structure matches { files: [{ path, content }] } before writing to the repository.

  // Suggestion: Use a dedicated markdown parser or stricter regex for code blocks
  const match = text.match(/```json\n([\s\S]*?)\n```/);
  if (match) {
     const data = JSON.parse(match[1]);
     // Validate schema strictly here
  }

• SCHEDULED_TASKS_INTEGRATION_PLAN.md: Branch Naming Collision

  • Description: The algorithm suggests creating branches named zai-scheduled/yyyy.mm.dd_hh.mm. If two tasks run in the same minute, or if a workflow is re-run, this could cause a collision or fail to push changes if the branch already exists.
  • Fix: Include a unique identifier (UUID or GitHub Run ID) in the branch name to ensure uniqueness.

  const branchName = `zai-scheduled/${dateStr}_${context.runId}`; // or uuid

• SCHEDULED_TASKS_INTEGRATION_PLAN.md & SCHEDULED_TASKS_QUICK_START.md: Language Consistency

  • Description: The document headers and some sections are in Russian (e.g., "Детальный План Интеграции...", "Цели и Требования"), while the technical content and code comments are in English. This limits the accessibility of the documentation for a global audience and creates inconsistency within the codebase.
  • Fix: Translate all documentation to English to align with the rest of the repository and technical standards.

• SCHEDULED_TASKS_QUICK_START.md: Security Warning on Gist Content

  • Description: Users should be warned that the Gist URL effectively acts as executable code/script. If they use a public Gist, anyone with edit access to that Gist can alter the behavior of their bot.
  • Fix: Add a security note advising users to either control the Gist strictly or pin the Gist to a specific commit SHA.

## 📊 Final Assessment

• Rating: Normal
• Reason: The documentation is thorough and structurally sound, providing a clear path for implementation. However, the rating is downgraded from "Good" due to the hardcoded third-party dependency in the examples (a security/operational risk) and the fragility of the proposed JSON parsing logic.