Session Logging

We keep an append-only project log as per-session markdown files under log/ so every session leaves a paper trail of: what changed, why it changed, and how to verify it.

Rules:

• Every working session that leads to changes must add or update one per-session file in log/ (analysis-only sessions do not). • Name new files log/YYYY-MM-DD-.md , where is a short lowercase hyphenated identifier for that session. • Keep one file per working session, not one giant active log or one file per branch. • If you continue the same session later in the day, rewrite that session file to tell the whole story so far instead of appending a tiny delta. • If you start a distinct session on the same day, create a new file with a different slug. • When you need prior context, search recent per-session files in log/ . • Keep entries factual and specific; avoid "we should" without a concrete follow- up. • Do not include secrets/tokens/credentials in the log. • Include the session partner when available (git user.name locally; "agent" in CI). Use "Unknown" if not available.

Log template:

## YYYY-MM-DD - Short Title

Session
- Partner: (from git `user.name`, or "agent")

Context
- Why this work happened (ticket/user request/bug report)

Decisions
- Key choices + tradeoffs (storage, ports, APIs, defaults)

Changes
- User-visible behavior
- Implementation notes (what/where)

Verification
- Commands run + expected results

Continuous Improvement

• Look for opportunities to improve the agent UX while working.
• Make small, directly related improvements to the AGENTS.md when they are low-risk and clearly beneficial.
• Suggest broader additions with concrete rationale and a proposed next step instead of silently expanding scope.
• Prefer durable repo guidance over snapshots of current implementation details in AGENTS.md.