docs: clarify human approval lifecycle

[cursor]

🧠 Noēsis Pull Request

Overview

Updates the human-in-the-loop documentation to reflect the verified unsealed-run lifecycle for approvals and checkpoint/resume behavior. Also expands the Python API run lifecycle reference with checkpoint artifact integrity details.

Type of Change

• 📚 Documentation or research notes
• 🧰 Developer experience (CLI, codemod, viewer, tooling)

Motivation & Context

The previous human approval guide showed interrupting/checkpointing after ns.solve(...) returned, which does not match sealed terminal run behavior. These docs now explain where approval gates must sit, how paused runs expose checkpoint evidence, and how prepared tool approvals bind to durable draft identity.

Technical Details

Docs added/updated:

• docs/guides/human-in-the-loop.mdx: rewritten as a concise operational runbook for human approval workflows.
• docs/reference/python-api.mdx: documents checkpoint metadata and artifact_manifest_hash behavior.

Codepaths covered:

• ns.interrupt(...), ns.checkpoint(...), ns.resume(...), ns.resume_run(...)
• governance pause-on-veto flow (run.interrupt -> run.checkpoint)
• prepared tool approval repositories and ToolApprovalDecision
• checkpoint consistency checks around event prefixes, state.json, and manifest/artifact digesting

Key knowledge gaps addressed:

• terminal runs are sealed and reject lifecycle mutation with RunSealedError
• resume emits evidence only while resume_run continues execution
• approvals must change the condition that caused the pause
• pre-manifest checkpoints hash the checkpointed artifact set and events.jsonl prefix
• common resume failures now map to likely causes and fixes

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)

Validation performed:

• python3 -c ... import smoke for documented approval symbols passed.
• python3 -c ... pause-on-veto lifecycle smoke passed, verifying run.interrupt, run.checkpoint, skipped side effect, and absent terminal artifacts.
• uv run pytest ... could not run because uv is not installed in the runner.
• python3 -m pytest ... could not run because pytest is not installed in the runner.

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

No schema or artifact field changes; documentation only.

Observability & Safety

Improves operator guidance for approval gates, paused run inspection, checkpoint integrity failures, and prepared tool approval binding.

Educational / Research Value

Clarifies how Noēsis preserves auditable same-run continuity for human-reviewed actions.

Screenshots / Logs

python3 -c import smoke: passed
python3 -c pause-on-veto lifecycle smoke: passed
uv run pytest: uv not installed
python3 -m pytest: pytest not installed

Related Issues / References

• noesis/usecases/run_lifecycle.py
• noesis/usecases/tool_invocation/runtime_bridge.py
• tests/runtime/test_run_lifecycle.py
• tests/runtime/test_tool_invocation_runtime_bridge.py