# Phase 8: Cron Reporting - Context

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

<domain>
## 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
</domain>

<decisions>
## 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)

### Technical Corrections from Research

- **`hermes sessions export`** has NO `--older-than` flag — exports ALL sessions, filters by `--source` or `--session-id` only. Archive script must export all then `prune --older-than 30 --yes` to clean up.
- **`hermes sessions prune`** uses `--yes` (not `--confirm`)
- **`hermes sessions list`** has NO `--json` flag
- **Jira-session mapping** lives in hindsight memory (saved by Phase 7 session skill), not in the session DB — cron agent must use `hindsight_recall` to discover which Jira tickets belong to which sessions
- **System timezone already SGT (+08)** — no TZ configuration needed
- **Three cron jobs required**: Daily report (09:00 SGT), weekly stale summary (Sunday 20:00 SGT), weekly archive (Sunday 20:05 SGT — 5 min after summary to avoid race conditions)

### the agent's Discretion
- **Report formatting**: Telegram message structure — planner designs based on 4096-char limit
- **Cron job naming**: Standard naming convention for the three cron jobs
- **Dry-run phase**: First archive via `hermes sessions export sessions.jsonl` then review JSONL before enabling prune
</decisions>

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

<specifics>
## 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
</specifics>

<deferred>
## 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
</deferred>

---

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