docs: Update checkpoint system docs for v2 [doc-updater]

[james-in-a-box]

Summary

Update documentation to reflect checkpoint v2 changes from #643.

Changes made:

docs/architecture/README.md:

• Expanded checkpoint system section to describe v2 features
• Added description of two trigger types (commit and session-end)
• Added session status types (completed, expired, failed)
• Documented all CLI filter options (--trigger, --status, --agent-type, --phase, --pr, --session)
• Clarified that v2 captures all sessions, not just commits

docs/development/STRUCTURE.md:

• Updated checkpoint_handler.py comment to reflect both commit and session-end triggers

Why these updates were needed:

Checkpoint v2 introduced significant new capabilities:

1. Session-end capture: Checkpoints are now captured when agent containers terminate, not just on commits
2. Session status tracking: Sessions can end with completed, expired, or failed status
3. Rich querying: Multi-dimensional index supports filtering by issue, PR, session, agent type, phase, trigger type, and status
4. Workflow context: Checkpoints now include issue_number, pr_number, pipeline_phase, and agent_type fields

The previous docs only described commit-based checkpoints with basic filtering. They didn't mention session-end capture or the rich query capabilities that are now available.

Triggered by: #643

Authored-by: egg

[egg-reviewer]

No agent-mode design concerns. This is a documentation-only update reflecting checkpoint v2 capabilities — no agent workflows, output formats, or pre-fetching patterns are introduced or modified.

— Authored by egg

[egg-reviewer]

Documentation Review

Verified all documentation claims against the codebase. The content is accurate — triggers, session statuses, CLI commands, filter options, captured data fields, and branch references all match the implementation.

Two minor issues:

1. Escaped pipes inside backtick code spans (lines 114-117 of docs/architecture/README.md)

The filter value examples use \| (backslash-pipe) inside backtick code spans:

`--trigger <commit\|session_end>`

Inside backtick code spans, markdown does not interpret pipe characters, so the backslash renders literally as a visible \ character. The rendered output will show commit\|session_end instead of the intended commit|session_end. The backslash escaping is only needed inside table cells, not in code spans or bullet lists. Remove the backslashes.

2. Missing unknown agent type (line 116)

The --agent-type filter lists coder|tester|documenter|integrator|reviewer, but the AgentType enum in shared/egg_contracts/checkpoints.py:162 also defines UNKNOWN = "unknown". While users are unlikely to filter by unknown, the documentation should either include it for completeness or note that it's omitted intentionally.

Neither issue is blocking. The documentation is otherwise accurate, well-structured, and covers the v2 changes comprehensively.

— Authored by egg

[james-in-a-box]

Both issues addressed in e34765c:

1. Escaped pipes: Removed backslash escaping from all four filter code spans. Pipes render correctly now.
2. Missing unknown agent type: Added unknown to the --agent-type filter values to match the AgentType enum.

— Authored by egg

[egg-reviewer]

Re-review of e34765c

Both issues from the previous review are properly fixed:

1. Escaped pipes: All four \| sequences in code spans replaced with |. Verified they render correctly.
2. Missing unknown agent type: Added to --agent-type filter values. Verified all enum values in docs match the source (TriggerType, SessionStatus, AgentType in shared/egg_contracts/checkpoints.py, PipelinePhase in shared/egg_contracts/models.py).

No new issues introduced.

— Authored by egg

[egg-reviewer]

No agent-mode design concerns. The delta since last review (e34765c) addresses previous review feedback — fixing escaped pipes in code spans and adding the missing unknown agent type. Documentation-only changes with no impact on agent workflows.

— Authored by egg

[james-in-a-box]

egg review completed. View run logs

4 previous review(s) hidden.

[james-in-a-box]

egg agent-mode-design completed. View run logs

4 previous review(s) hidden.