docs: sync skill docs with lifecycle plugin plan

references/doctor-spec.md

@@ -9,50 +9,74 @@ 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.
+  because incorrect fixes can overwrite valid state.
 - **Fast and offline.** No API calls, no database queries. Reads files only.
 - **Exit codes matter.** 0 = healthy, 1 = warnings found, 2 = critical issues.
+- **Working-state focus.** The doctor validates active-work recovery hygiene,
+  not long-term memory quality.
 
 ## Checks performed
 
 ### 1. Existence check
 - Does `memory/CURRENT_STATE.md` exist?
-- Severity: CRITICAL if missing (no recovery possible)
+- Severity: CRITICAL if missing (no deterministic recovery point)
 
 ### 2. Staleness check
 - When was `CURRENT_STATE.md` last modified?
-- If older than the most recent session transcript, it is stale.
+- If older than the most recent relevant session activity, 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
+  (`Objective`, `Current Step`, `Key Decisions`, `Next Action`, `Blockers`, `Unsurfaced Results`)
+- Are any sections still showing placeholder text?
+- Severity: WARNING for missing sections, INFO/WARNING for unresolved placeholders depending on severity
 
-### 4. Unsurfaced results
+### 4. Active-work usability
+- Does `Objective` appear meaningful, or is it empty / placeholder / idle?
+- If active work exists, does `Next Action` look usable?
+- Severity: WARNING when a checkpoint exists but does not provide a usable recovery surface
+
+### 5. Unsurfaced results
 - Is the `Unsurfaced Results` section non-empty?
-- If yes, someone needs to review those results.
+- If yes, someone likely still needs to review or forward 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.)
+### 6. Archive consistency
+- Are there files in `memory/session_archive/`?
+- Does the newest archive differ significantly from `CURRENT_STATE.md`?
+  (This may be expected after task switches, but is 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)
+### 7. Recovery-priority hygiene (best-effort)
+- If workspace/session evidence suggests a recovery scenario recently occurred,
+  did the agent still prefer generic greeting over recovered work state?
+- Severity: WARNING when detectable
+- Note: this may depend on transcript/session inspection and can remain best-effort
+
+### 8. Optional alignment checks
+- If a `tasks.md`, `openspec/`, or similar planning artifact exists, does the
+  `Objective` roughly align with active work?
+- Severity: INFO
+
+## Important boundaries
+The doctor is **not** trying to replace:
+- OpenClaw compaction summaries
+- native `memoryFlush`
+- session transcript memory search
+
+It only answers:
+- is the working-state checkpoint present?
+- is it fresh?
+- is it structurally usable for recovery?
 
 ## Output format
 
-```
+```text
 [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
+[WARNING]  Recovery state exists but Next Action is placeholder text
 [INFO]     Archive objective differs from current objective (task switch?)
 [OK]       Template compliance: all sections present
 ```
@@ -61,4 +85,6 @@ It reports problems but does **not** auto-fix them.
 
 - Multi-workspace scan (check all sub-agent workspaces)
 - JSON output mode for programmatic consumption
-- Integration with OpenClaw cron for scheduled health checks
+- Integration with scheduled health checks
+- More transcript-aware recovery-priority detection
+- Validation support for future lifecycle-plugin checkpoints

references/template.md

@@ -8,7 +8,7 @@
 [What step are we on, what was the last thing completed]
 
 ## Key Decisions
-- None yet
+- None
 
 ## Next Action
 [Exactly what should happen next]
@@ -18,3 +18,11 @@ None
 
 ## Unsurfaced Results
 None
+
+---
+
+## Template notes
+- Use this file for **active working state**, not long-term memory.
+- Overwrite it; do not turn it into a running journal.
+- If `Objective` is empty, placeholder, or idle, recovery should not pretend active work exists.
+- In recovery scenarios, agents should surface this state before generic greetings when active work is present.