docs: add lifecycle resume integrity troubleshooting runbooks

[cursor]

🧠 Noēsis Pull Request

Overview

Strengthens lifecycle documentation for paused/approved runs by adding explicit resume integrity troubleshooting runbooks to existing docs pages.

Type of Change

• 📚 Documentation or research notes

Motivation & Context

Recent lifecycle changes enforce stronger checkpoint consistency (event_offset, causal anchors, state_hash, artifact digest/manifest hash). Existing docs listed the errors but lacked a practical operator runbook for diagnosing resume failures.

Technical Details

Updated existing documentation (no new pages):

• docs/reference/python-api.mdx
  • Clarified CheckpointConsistencyError to include artifact_manifest_hash
  • Added a Resume integrity runbook section covering:
    • sealed-run boundary (final.json)
    • checkpoint anchor checks
    • artifact drift checks (events.jsonl, state.json, optional manifest.json)
    • explicit caused_by constraints
    • common consistency failure causes
• docs/guides/human-in-the-loop.mdx
  • Added a Resume troubleshooting runbook for approval workflows
  • Added a failure-mode table for RunSealedError, CheckpointNotFoundError, CheckpointConsistencyError, and ResumeAdapterMismatchError

Validation

Required

• All tests pass locally (uv run pytest) or equivalent targeted suite
• Schema validation and export diff clean

Situational

• Cognitive loop tested end-to-end (Observe → Learn)
• Docs build successfully (pnpm run build in docs/)
• CLI smoke tests pass (python scripts/pre_release.py --check-all)
• Benchmarks / eval sweeps reproduced
• Artifact integrity checked (hashes, licensing, storage footprint)

ADR-003 Schema Governance Checklist

• $schema_version bumped for every artifact whose stable fields changed
• docs/schema/** regenerated (no diff after python scripts/gen_schema.py)
• KPI updates include version bumps plus math/clamp/rationale updates in internal_docs/schema/kpi*.yaml
• Relevant entry added to MIGRATIONS.schema.md or MIGRATIONS.kpi.md
• python scripts/schema_guard.py --strict --json passes locally
• Docs under docs/app/reference/* updated when new fields/KPIs surface to users

Observability & Safety

Docs now explicitly describe fail-closed lifecycle behavior at resume boundaries, reducing operational ambiguity and unsafe retries against drifted/sealed artifacts.

Educational / Research Value

Clarifies the practical implications of lifecycle invariants for teams building approval-gated and human-in-the-loop workflows.

• Replication kit (configs, seeds, sweeps, data access notes): n/a

Screenshots / Logs

n/a (docs-only)

Related Issues / References

• noesis/usecases/run_lifecycle.py
• tests/runtime/test_run_lifecycle.py