docs(08): capture phase context

.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
+
+<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)
+
+### 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)
+</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*

.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