aoa-session-memory-doctor

name	aoa-session-memory-doctor
description	Use when the `.aoa` session-memory filesystem contract, registry, generated indexes, naming policy, live hooks, or Codex grounding need health checks.
license	Apache-2.0
metadata	{"aoa_scope":"session-memory","aoa_invocation_mode":"manual"}

aoa-session-memory-doctor

Use this for local health and repair orientation. doctor checks consistency; it does not replace audit.

Trigger Boundary

• A session archive looks inconsistent.
• Required root files, indexes, manifests, or registry entries may be missing.
• Live hook wiring or Codex grounding needs a health check.
• The user-level router skill needs to be checked for the current Codex user.
• A change touched bundle structure, naming, schemas, hooks, or generated surfaces.

Procedure

Run the narrow filesystem and metadata doctor first:

python3 scripts/aoa_session_memory.py doctor \
  --workspace-root <workspace-root> \
  --aoa-root <aoa-root>

The default route is intentionally fast on large live archives. It checks required surfaces, manifests, registry and generated-surface presence without parsing every event in every segment index.

When live hooks and Codex grounding matter, run:

python3 scripts/aoa_session_memory.py doctor \
  --workspace-root <workspace-root> \
  --aoa-root <aoa-root> \
  --check-live-hooks \
  --check-user-skill \
  --check-codex-grounding

When the task is specifically to validate event payloads inside segment index files, use the explicit deep route:

python3 scripts/aoa_session_memory.py doctor \
  --workspace-root <workspace-root> \
  --aoa-root <aoa-root> \
  --deep-segment-indexes

Verification

• ok=true
• status=current or an explicitly deferred live-tail status
• no problems
• warnings are reported, not hidden
• if live checks were requested, hook and grounding subreports are green
• if --check-user-skill was requested, the global router points at this install

Stop Line

Do not treat a green doctor as completion readiness. Use audit for that.