From 7755cbe3d1ace9029c7381ca3aff68393deb1fca Mon Sep 17 00:00:00 2001 From: Bagas Purwa Sentika Date: Mon, 15 Jun 2026 21:46:33 +0800 Subject: [PATCH] docs(08): capture phase context --- .../phases/08-cron-reporting/08-CONTEXT.md | 126 ++++++++++++++++++ .../08-cron-reporting/08-DISCUSSION-LOG.md | 47 +++++++ 2 files changed, 173 insertions(+) create mode 100644 .planning/phases/08-cron-reporting/08-CONTEXT.md create mode 100644 .planning/phases/08-cron-reporting/08-DISCUSSION-LOG.md diff --git a/.planning/phases/08-cron-reporting/08-CONTEXT.md b/.planning/phases/08-cron-reporting/08-CONTEXT.md new file mode 100644 index 0000000..ebab03e --- /dev/null +++ b/.planning/phases/08-cron-reporting/08-CONTEXT.md @@ -0,0 +1,126 @@ +# 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 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 + + + +## 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) + + + +## 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* diff --git a/.planning/phases/08-cron-reporting/08-DISCUSSION-LOG.md b/.planning/phases/08-cron-reporting/08-DISCUSSION-LOG.md new file mode 100644 index 0000000..485bdb8 --- /dev/null +++ b/.planning/phases/08-cron-reporting/08-DISCUSSION-LOG.md @@ -0,0 +1,47 @@ +# Phase 8: Cron Reporting - Discussion Log + +> **Audit trail only.** Do not use as input to planning, research, or execution agents. + +**Date:** 2026-06-14 +**Phase:** 8-Cron Reporting +**Areas discussed:** Report schedule, Report content, Archive behavior, Jira integration depth + +--- + +## Report Schedule + +**User's choice:** Daily at 09:00 SGT (UTC+8). Weekly Sunday 20:00 SGT for stale summary + archive. + +**Notes:** Two separate cron jobs — daily report and weekly stale/archive. + +--- + +## Report Content + +**User's choice:** Daily report updates JIRA with last activity (session → JIRA is 1-to-many). No ticket status updates unless user specifies. Weekly stale report summarizes all inactive sessions. + +**Notes:** Daily = active session progress comments on linked JIRAs. Weekly = inactive session summary only. + +--- + +## Archive Behavior + +**User's choice:** Use Hermes-native commands (`hermes sessions export` + `hermes sessions prune`). + +**Notes:** Native Hermes tools exist — no custom scripting needed. Archive to `~/.hermes/archive/sessions/`. Dry-run mode first. + +--- + +## Jira Integration Depth + +**User's choice:** Active tickets get daily progress comments. Stale tickets get mentioned in summary only (no auto-comment). No auto status transitions. + +**Notes:** User must explicitly ask for ticket status changes. 1-to-many session→Jira mapping. + +--- + +## Deferred Ideas + +- Auto-close tickets for archived sessions +- Teams gateway delivery +- Custom archive dashboard