8. Session Model

aDNA Specification v2.5 Section 8 of 20 Full text

Scan: Bounded units of agent work — lifecycle (create → execute → close → archive), session tiers, SITREP close-out, next-session prompt, the 75% rule.

Decisions: D3, D4, D5

8.1 Session Lifecycle

A session is a bounded unit of agent work. Every session follows this lifecycle:

Create: Write a session file in how/sessions/active/
Execute: Perform work, logging activity
Close: Write SITREP + next-session prompt
Archive: Set status: completed, move to how/sessions/history/YYYY-MM/

A session file MUST be created before an agent modifies any other project files. This is the audit trail.

stateDiagram-v2
    [*] --> Create: Agent starts work
    Create --> Active: Session file written
    Active --> Active: Work + log activity
    Active --> Close: SITREP written
    Close --> Archive: Move to history/YYYY-MM/
    Archive --> [*]

    state Active {
        [*] --> Working
        Working --> Working: Modify files<br/>Update frontmatter
    }

8.2 Session ID Format

Session IDs MUST use the timestamped format:

session_{user}_{YYYYMMDD}_{HHMMSS}_{descriptor}

Example: session_{username}_20260211_120000_gap_analysis

Timestamped IDs are machine-sortable, collision-free across agents, and self-documenting. The descriptor SHOULD be a brief lowercase-underscore slug describing the session’s purpose.

8.3 Session Tiers

Tier	When	Requirements
Tier 1 (default)	Normal content work	Session file with intent, activity log, SITREP close-out
Tier 2	Shared config edits (governance files, plugin configs)	Tier 1 requirements + scope declaration + conflict scan + heartbeat

Tier 1 is a lightweight audit trail. Tier 2 adds coordination safeguards for edits that affect shared infrastructure.

Sessions MAY include a Technical Readiness Review (TRR) quality gate before close-out — a structured check that deliverables meet acceptance criteria. TRR is particularly useful for code-generation sessions or sessions producing artifacts that downstream tasks depend on.

8.4 SITREP Close-Out

Every session MUST end with a SITREP:

## SITREP

**Completed**: [what was finished]
**In progress**: [what was started but not finished, with handoff notes]
**Next up**: [recommended next actions]
**Blockers**: [anything preventing progress]
**Files touched**: [created, modified, moved]

8.5 Next-Session Prompt

Every session MUST include a next-session prompt after the SITREP:

## Next Session Prompt

[Self-contained paragraph that a fresh agent can read to continue this work.
Include: what was accomplished, what remains, key context, recommended approach.]

The next-session prompt ensures continuity. A fresh agent reading this prompt and STATE.md SHOULD be able to continue the work without needing to read the full session history.

8.6 STATE.md Update

STATE.md SHOULD be updated on every session close. It MUST be updated when the current phase, blockers, or priorities change.

8.7 The 75% Rule

Agents MUST scope each session to use no more than approximately 75% of the context window. The remaining 25% is reserved for thinking, debugging, and course correction.

If a task requires more than 75% of the context window, the agent MUST split the work across sessions, checkpointing progress in the session close-out.

No other session sizing prescriptions are universal. Time, task count, and line-count guidelines are project-specific — different work paradigms (code generation, knowledge synthesis, CRM maintenance) have different natural session sizes.