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-<session-slug>.md , where <session-slug> 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.