memory-continuity/references/doctor-spec.md

Continuity Doctor — Specification

Purpose

The continuity doctor is a diagnostic tool that checks whether the memory-continuity protocol is being followed correctly in a workspace. It reports problems but does not auto-fix them.

Design philosophy

• Diagnose, don't repair. Automated repair of state files is dangerous because incorrect "fixes" can overwrite valid state. The doctor flags issues for human or agent review.
• Fast and offline. No API calls, no database queries. Reads files only.
• Exit codes matter. 0 = healthy, 1 = warnings found, 2 = critical issues.

Checks performed

1. Existence check

• Does memory/CURRENT_STATE.md exist?
• Severity: CRITICAL if missing (no recovery possible)

2. Staleness check

• When was CURRENT_STATE.md last modified?
• If older than the most recent session transcript, it is stale.
• Severity: WARNING

3. Template compliance

• Does the file contain all mandatory sections? (Objective, Current Step, Key Decisions, Next Action, Blockers, Unsurfaced Results)
• Are any sections still showing placeholder text like [One sentence: ...]?
• Severity: WARNING for missing sections, INFO for placeholder text

4. Unsurfaced results

• Is the Unsurfaced Results section non-empty?
• If yes, someone needs to review those results.
• Severity: WARNING

5. Archive consistency

• Are there files in memory/session_archive/ ?
• Does the newest archive have a different Objective than CURRENT_STATE.md? (This is expected if the user switched tasks, but worth flagging.)
• Severity: INFO

6. Conflict detection (optional, if tasks file exists)

• If a tasks.md or openspec/ directory exists, does the Objective in CURRENT_STATE.md align with any active task?
• Severity: INFO (alignment is nice-to-have, not mandatory)

Output format

[CRITICAL] memory/CURRENT_STATE.md does not exist
[WARNING]  CURRENT_STATE.md is stale (last modified 2h ago, session ran 30m ago)
[WARNING]  Unsurfaced Results section is not empty — review needed
[INFO]     Archive objective differs from current objective (task switch?)
[OK]       Template compliance: all sections present

Future extensions (not yet implemented)

• Multi-workspace scan (check all sub-agent workspaces)
• JSON output mode for programmatic consumption
• Integration with OpenClaw cron for scheduled health checks