docs: align HITL resume, sealing, and layout with runtime contracts

[cursor]

🧠 Noēsis Pull Request

Overview

Align published docs with the current runtime contracts for human-in-the-loop continuation, artifact layout/sealing, planner vs governance config, and runs_dir resolution. This is documentation-only.

Type of Change

• 📚 Documentation or research notes

Motivation & Context

Several how-to and explanation pages still described behavior that the runtime rejects:

• HITL examples interrupted a sealed ns.solve / started a new ns.run after approval.
• Artifact trees used nested label/ dirs and ns.set(label=...) / ns.set(seed=...) / log_prompts (not config keys).
• Planner docs treated planner_mode="minimal" as "skip governance" and called ns.config().
• Shared-storage examples used NOESIS_RUNS_DIR=/srv/noesis/episodes, which resolves to {runs_dir}/.noesis/episodes.
• CheckpointConsistencyError docs omitted artifact_manifest_hash (checkpoint integrity from fix(lifecycle): enforce checkpoint artifact integrity during resume #210).
• docs.json already linked reference/llms-txt but the page was missing.

Docs added/updated

Updated

• docs/guides/human-in-the-loop.mdx — pause-on-veto + ns.resume_run runbook
• docs/reference/python-api.mdx — lifecycle flow, checkpoint hash, EpisodeIndex path
• docs/reference/events.mdx — run.interrupt / run.checkpoint / run.resume payloads
• docs/explanation/artifacts.mdx — flat layout, final.json seal, index, manifest files[]
• docs/explanation/core-concepts.mdx — ULID IDs, lifecycle states, no ns.set(seed=)
• docs/explanation/prompt-provenance.mdx — path without label nesting
• docs/index.mdx, docs/quickstart.mdx, docs/guides/adopting-noesis.mdx — matching layout
• docs/guides/configure-planner-modes.mdx — planner_mode vs governance_mode, ns.get()
• docs/guides/configure-shared-storage.mdx — .noesis parent rule + migrate-layout
• docs/reference/configuration.mdx, docs/reference/cli.mdx — runs_dir pitfall, migrate-layout constraints
• docs/guides/write-policies.mdx, docs/tutorials/first-policy.mdx — shipped CLI has no --intuition

Added

• docs/reference/llms-txt.mdx — page already referenced from docs/docs.json

Codepaths covered

• noesis/usecases/episode_runner.py pause-on-veto (_pause_on_governance_veto)
• noesis/usecases/run_lifecycle.py checkpoint anchors / _artifact_digest / _assert_checkpoint_consistency
• noesis/core.py _seal_episode, non-terminal skip of _finalize_episode, resume_run goal reuse, EpisodeIndex(layout.index_dir, ttl_days=30)
• noesis/runtime/paths.py resolve_noesis_root / resolve_noesis_paths
• noesis/domain/config/settings.py ALLOWED_CONFIG_KEYS
• noesis/infrastructure/layout_migration.py + noesis/cli/__main__.py migrate-layout
• noesis/io.py list_runs (skips dirs without summary.json)
• Tests: tests/runtime/test_run_lifecycle.py, tests/runtime/test_sealing_flow.py, tests/runtime/test_episode_dir_layout.py, tests/governance/test_pre_act.py

Key knowledge gaps addressed

• Approval is same-run continuation; sealed runs cannot be interrupted.
• resume_run does not rewrite the goal; PreActGovernor can veto again.
• artifact_manifest_hash fails if manifest.json appears or disappears after checkpoint.
• planner_mode does not enable/disable governance (governance_mode does; default is off).
• Episode dirs are flat ep_<ULID>/; final.json is the seal; index is .noesis/index/.
• runs_dir parent must be .noesis (or the path is .noesis).

Technical Details

Documentation-only. No schema or runtime changes.

Validation

Required

• All tests pass locally (uv run pytest) or equivalent targeted suite — docs-only; not re-run
• Schema validation and export diff clean — N/A (no schema edits)

Situational

• Docs build successfully — npx mintlify@latest broken-links from docs/ reported no broken links
• CLI smoke tests pass (python scripts/pre_release.py --check-all) — N/A

ADR-003 Schema Governance Checklist

N/A — no schema/KPI changes.

Observability & Safety

No runtime or telemetry changes. Docs now match fail-closed sealing and checkpoint integrity behavior.

Related Issues / References

Follows merged runtime work in #210 (checkpoint artifact integrity) and #219 (direction/veto docs). Overlapping draft docs PRs #220–#240 cover some of the same ground and should not be merged as duplicates if this lands.