Bagas Purwa Sentika
47d0b80be8
- Created ~/.hermes/scripts/archive-stale-sessions.sh (1146 bytes, executable) - Script has DRY_RUN=true safe default (export only, no prune) - Export uses date-stamped JSONL filename - Prune gated behind DRY_RUN=false with --older-than 30 --yes - set -euo pipefail strict error handling - Created ~/.hermes/archive/sessions/ archive directory - Progress echo statements for Telegram delivery
136 lines
7.0 KiB
Markdown
136 lines
7.0 KiB
Markdown
# 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*
|