# =============================================================================
# Built-in Task: Changelog Generator
# =============================================================================
# Task for: documentation agent
#
# This built-in task generates changelogs from CI session history. Can be
# scheduled weekly to automatically update your CHANGELOG.md.
#
# To customize: Copy to oak/ci/agents/changelog.yaml and modify as needed.
# =============================================================================

name: changelog
display_name: "Changelog Generator"
agent_type: documentation
is_builtin: true
description: >
  Generates changelog entries from session history. Uses CI data to accurately
  document what changed, why, and any important notes for each period.

default_task: |
  Generate a changelog entry for the recent development period.

  ## Your CI-Powered Workflow (History IS the Source of Truth)

  1. **Read Existing Changelog First**
     - Read CHANGELOG.md to understand current format and style
     - Note the last documented date/version to avoid duplicates
     - Identify any project-specific conventions

  2. **Gather Session History**
     - Use `oak_sessions(limit=20)` to get recent coding sessions
     - Filter to sessions AFTER the last changelog entry
     - Group sessions by logical feature/fix
     - Identify the date range covered

  3. **Categorize Changes**
     Using session summaries and memories:
     - **Added**: New features (from sessions mentioning "add", "create", "implement")
     - **Changed**: Modifications to existing behavior
     - **Fixed**: Bug fixes (from `oak_memories(type=bug_fix)`)
     - **Deprecated**: Features marked for removal
     - **Removed**: Deleted functionality
     - **Security**: Security-related changes

  4. **Enrich with CI Context**
     - Link each change to its source session
     - Include relevant gotchas as notes
     - Reference related memories for context

  5. **Write Keep-a-Changelog Format**
     ```markdown
     ## [Version/Date] - YYYY-MM-DD

     ### Added
     - Feature description — [Session Title](session_link)

     ### Fixed
     - Bug fix description — [Session Title](session_link)

     ### Notes
     - Any gotchas or important information from memories
     ```

  **Observation lifecycle note:** Use `include_resolved=true` when querying
  `oak_memories` for changelog generation. Resolved observations represent
  completed work and are appropriate source material for documenting what
  was fixed or addressed.

  Focus on user-facing changes and significant internal improvements.
  Skip trivial refactors unless they affect behavior.

  ## Reference: Good Changelog Entry

  ```markdown
  ## [2024-01-15]

  ### Added
  - **Team search** — Semantic search across code and memories
    — [Add CI search feature]({daemon_url}/activity/sessions/abc123-full-uuid)

  ### Fixed
  - Email classification silent failures when subject contains special characters
    — [Fix email classification]({daemon_url}/activity/sessions/def456-full-uuid)

  > **Gotcha**: The classifier regex was too greedy. Now validates input length first.

  ### Changed
  - Migrated session storage from JSON files to SQLite for better performance
    — [Migrate session storage]({daemon_url}/activity/sessions/ghi789-full-uuid)

  ### Developer Notes
  - The search index now supports plans/SDDs as a searchable type
  ```

# Schedule for weekly execution (optional - uncomment to enable)
# schedule:
#   cron: "0 0 * * MON"
#   description: "Weekly changelog update every Monday at midnight"

# Execution limits
execution:
  timeout_seconds: 300
  max_turns: 50
  permission_mode: acceptEdits
  model: claude-sonnet-4-6

# Files this task maintains
maintained_files:
  - path: "{project_root}/CHANGELOG.md"
    purpose: "Version history and release notes"
    auto_create: true

# CI queries to gather context
oak_queries:
  discovery:
    - tool: oak_sessions
      limit: 30
      include_summary: true
      purpose: "Get recent sessions for changelog content"

  context:
    - tool: oak_memories
      filter: bug_fix
      limit: 15
      purpose: "Find bug fixes to document"

    - tool: oak_memories
      filter: discovery
      limit: 10
      purpose: "Find significant discoveries"

    - tool: oak_memories
      filter: decision
      limit: 10
      purpose: "Find architectural decisions"

# Output format
output_requirements:
  format: "keepachangelog"
  link_sources: true
  required_sections:
    - name: "Added"
      source: "sessions"
      description: "New features"
    - name: "Fixed"
      source: "memories"
      description: "Bug fixes from bug_fix memories"

# Style preferences
style:
  tone: "concise"
  include_examples: false
  link_sessions: true
  conventions:
    - "Use imperative mood (Add, Fix, Change)"
    - "Link every entry to source session"
    - "Group related changes together"

schema_version: 1
