ngn-agent/.planning/phases/08-cron-reporting/08-CONTEXT.md

Phase 8: Cron Reporting - Context

Gathered: 2026-06-14 Status: Ready for planning

## Phase Boundary

Set up daily operational reporting and weekly stale session lifecycle management using Hermes' built-in cron and session management capabilities.

In scope: Daily report cron job via Telegram, Jira progress updates for active sessions, weekly stale session summary, weekly stale session archive using hermes sessions export + hermes sessions prune

Out of scope: Session lifecycle skill (Phase 7 already done), tool provisioning (Phase 9), portable setup script (Phase 9), auto-closing Jira tickets (user must specify), modifying Jira ticket statuses without user instruction

## Implementation Decisions

Report Schedule

• D-01: Daily report runs at 09:00 SGT (UTC+8) — Hermes cron job using hermes cron create
• D-02: Weekly stale session summary runs Sunday 20:00 SGT (UTC+8) — separate cron job
• D-03: Weekly stale session archive runs Sunday 20:00 SGT (UTC+8) — same cron job as summary (archive after summary)

Daily Report Content

• D-04: Daily report updates all Jira tickets linked to active sessions with last activity and progress (session → Jira is 1-to-many mapping)
• D-05: Do NOT update Jira ticket statuses — only add comments with session progress/state
• D-06: Daily report delivered via Telegram to user's DM channel
• D-07: Report includes: list of active sessions, last activity timestamp, Jira ticket keys updated

Weekly Stale Report

• D-08: Weekly report summarizes all inactive sessions (>30d since last activity) — session title, last activity date, linked Jira ticket
• D-09: Delivered via Telegram to user's DM channel
• D-10: No auto-comments on stale tickets — only reported in the summary

Session Archive

• D-11: Use native Hermes commands — no custom scripts:
  • Export: hermes sessions export --older-than 30d --output ~/.hermes/archive/sessions/sessions-$(date +%Y%m%d).jsonl
  • Prune: hermes sessions prune --older-than 30d --confirm (after export verification)
• D-12: Archive location: ~/.hermes/archive/sessions/
• D-13: Run weekly Sunday 20:00 SGT, after the stale summary report

Jira Integration

• D-14: Active sessions with linked Jira tickets get daily progress comments added automatically
• D-15: Stale sessions with Jira tickets are mentioned in the weekly summary only (no auto-comment)
• D-16: Ticket status transitions only happen when user explicitly asks

Cron Job Mechanism

• D-17: Both cron jobs use Hermes skill-backed cron (hermes cron create with a skill that defines the report behavior)
• D-18: The daily report skill references the existing session skill (Phase 7) and ngn-jira skill (Phase 4) for operations
• D-19: The stale archive step uses no_agent: true mode (deterministic CLI commands, no LLM cost)

the agent's Discretion

• Report formatting: How the Telegram message is structured (sections, bullet points) — planner can design based on Telegram's 4096-char limit
• Cron job naming: Standard naming convention for the two cron jobs
• Dry-run phase: First archive run should be manual (hermes sessions export --older-than 30d then review JSONL before enabling prune)

<canonical_refs>

Canonical References

Downstream agents MUST read these before planning or implementing.

Hermes Documentation

• ~/.hermes/config.yaml §cron: — Existing cron configuration (wrap_response, max_parallel_jobs)
• ~/.hermes/config.yaml §TELEGRAM_HOME_CHANNEL — Delivery channel for cron output
• hermes cron create --help — Cron job creation syntax

Session Management

• hermes sessions export --help — Session export to JSONL
• hermes sessions prune --help — Session pruning
• hermes sessions list --help — Session listing

Completed Phases (Dependencies)

• .planning/phases/05-hindsight-memory-provider/05-01-SUMMARY.md — Hindsight active for cross-session insights
• .planning/phases/07-main-session-skill/07-01-SUMMARY.md — Session lifecycle skill creates structured sessions with Jira links

Project Documents

• initial-plan.md §func daily_report() — Original reporting spec
• .planning/REQUIREMENTS.md §CRON-01, CRON-02, CRON-03 — Requirement definitions
• .planning/ROADMAP.md §Phase 8 — Phase goal and success criteria

Existing Skills (Referenced by cron skills)

• ~/.hermes/skills/ngn-agent/session/SKILL.md — Session lifecycle skill
• ~/.hermes/skills/ngn-agent/jira/SKILL.md — Jira query skill </canonical_refs>

<code_context>

Existing Code Insights

Reusable Assets

• Hermes cron system: Fully operational in gateway — hermes cron create with skill-backed or no_agent jobs
• Telegram delivery: TELEGRAM_HOME_CHANNEL already set to user's DM (474440517)
• Session DB: SQLite-based, queryable via hermes sessions list --json
• ngn-jira script: Available in Docker for Jira operations

Established Patterns

• Skill-backed cron: Cron job that loads a SKILL.md and lets the agent compose the report
• no_agent cron: Deterministic commands without LLM involvement (for archive step)

Integration Points

• hermes cron create → Register daily report job
• hermes cron create --no-agent → Register archive job
• ~/.hermes/archive/sessions/ → Archive storage directory (create) </code_context>

## Specific Ideas

• The daily report should be a Hermes skill that instructs the agent to query session DB for active sessions, then update each session's Jira ticket with a progress comment, then compose a Telegram summary
• The stale archive should be a no_agent cron: hermes sessions export ... && hermes sessions prune ...
• Start with dry-run on archive: run export manually first, verify JSONL, then enable the prune
• SGT (UTC+8) timezone should be set explicitly in the cron job or system config

## Deferred Ideas

• Auto-close tickets for archived sessions — user wants manual control
• Teams gateway delivery — only Telegram for now
• Custom archive dashboard — JSONL files are searchable via grep/FTS5

---

Phase: 8-Cron Reporting Context gathered: 2026-06-14