📋 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

❌ Patch coverage is 98.93191% with 8 lines in your changes missing coverage. Please review.
✅ Project coverage is 86.00%. Comparing base (5a379a5) to head (fa974fe).

Files with missing lines	Patch %	Lines
src/lib/repository-context.js	98.64%	5 Missing ⚠️
src/lib/handlers/scheduled.js	98.24%	3 Missing ⚠️

Additional details and impacted files

@@             Coverage Diff             @@
##             main      #12       +/-   ##
===========================================
+ Coverage   75.52%   86.00%   +10.48%     
===========================================
  Files          22       24        +2     
  Lines        6500     7204      +704     
===========================================
+ Hits         4909     6196     +1287     
+ Misses       1591     1008      -583     

☔ 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

This PR significantly enhances the "Scheduled Tasks" pipeline by implementing a "Grounded Generation" architecture to fix hallucination bugs (specifically PR #15). It introduces robust context collection (repository-context.js), validation guards (agents-validation.js), and extensive configuration scoping. The changes are well-structured, thoroughly tested, and the documentation is comprehensive.

🚨 Critical Issues & Bugs

• src/lib/agents-validation.js: The hallucination detection logic in extractReferencedPaths ignores tokens that do not contain a slash (/) or a file extension (e.g., Dockerfile, Makefile, Procfile, LICENSE). If the LLM hallucinates one of these specific extensionless root files, the validation guard will skip checking them, allowing false positives to pass through the "hallucination check."

  • Why this is a problem: The core purpose of this PR is to prevent hallucinated files from being committed. This logic gap undermines that safety guarantee for common root-level configuration files.
  • Fix: Modify the filter logic to treat tokens that appear in file-list-like structures (e.g., after - or |) as potential file paths even if they lack extensions or slashes.

  // Inside extractReferencedPaths
  // Existing check
  if (GENERIC_TERMS.has(token)) continue;
  
  // Improved check: Allow extensionless tokens if they look like typical config filenames
  // or if they appear in a list context (simplified heuristic).
  const isExtensionless = !EXT_RE.test(token);
  const looksLikeConfigFile = /^(Makefile|Dockerfile|Procfile|Rakefile|Gemfile|Cargo\.toml|go\.mod|requirements\.txt|package\.json)$/i.test(token);
  
  if (token.includes('/') || EXT_RE.test(token) || looksLikeConfigFile) {
    found.add(token);
  }

💡 Suggestions & Best Practices

• src/lib/repository-context.js: The globToRegExp function is a custom implementation. While it handles the basic cases in the PR (**, *), custom glob parsers can be fragile for edge cases (e.g., character classes [...], brace expansion {a,b}).
  • Suggestion: Add a comment explicitly documenting the supported glob syntax to prevent users from relying on unsupported features like src/**/*.{js,ts}. Alternatively, consider using a lightweight, well-maintained library like minimatch if the bundle size permits, to ensure RFC-compliant glob matching.
• src/lib/handlers/scheduled.js: In handleUpdateAgentsTask, if the repository tree is truncated by the GitHub API (truncated: true), the context passed to the LLM is incomplete. However, the validation step (validateGeneratedAgentFiles) runs against this incomplete tree.
  • Suggestion: This creates a "Fail Closed" scenario where valid files in the truncated part might be flagged as hallucinations if the LLM infers them. This is generally safe (better to reject a good update than accept a bad one), but it might be noisy. Consider logging a specific warning if validation fails and the tree was truncated, so users understand the limitation.

📊 Final Assessment

• Rating: Good
• Reason: The PR successfully addresses the critical hallucination vulnerability with a multi-layered defense (Grounding + Validation). The code is clean, well-documented, and backed by solid unit tests. The identified issue with extensionless files is a refinement opportunity for the guardrail logic rather than a fundamental flaw.