docs: document final artifact sealing

[cursor]

🧠 Noēsis Pull Request

Overview

Documents the final.json artifact sealing contract for terminal episode runs and wires the final schema into the docs reference navigation.

Type of Change

• 📚 Documentation or research notes

Motivation & Context

The runtime and tests define final.json as the canonical seal marker, but the main artifact docs did not explain the contract. This PR closes that gap for developers and operators reading episode artifacts.

Technical Details

• Added docs/reference/final.mdx for the final/2.0.0 schema, outcome values, verification status values, lifecycle constraints, and examples.
• Updated docs/explanation/artifacts.mdx with final.json, sealing order, manifest rollback behavior, pause-on-veto constraints, and a corrected manifest verification snippet.
• Aligned artifact lists in docs/explanation/core-concepts.mdx, docs/index.mdx, docs/quickstart.mdx, and docs/guides/adopting-noesis.mdx.
• Added reference/final to docs/docs.json under Schema reference.

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/) or equivalent docs check
• CLI smoke tests pass (python scripts/pre_release.py --check-all)
• Benchmarks / eval sweeps reproduced
• Artifact integrity checked (hashes, licensing, storage footprint)

Validation run:

• npx --yes mintlify@latest broken-links from docs/
• custom Python check for reference/final, schema presence, and final/2.0.0 enum contract
• /tmp/noesis-docs-venv/bin/python -m pytest tests/runtime/test_sealing_flow.py tests/runtime/test_final_schema.py tests/runtime/test_run_lifecycle.py -q (22 passed)

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 fields changed; this is documentation for the existing docs/schema/final/2.0.0.json contract.

Observability & Safety

Clarifies the operational distinction between sealed terminal runs and unsealed paused runs, including RunSealedError behavior and manifest rollback semantics.

Educational / Research Value

Improves trace literacy for teams auditing Noēsis episode bundles and trace-based evals.

Screenshots / Logs

N/A.

Related Issues / References

Verified against:

• noesis/core.py
• noesis/domain/artifacts/finalization.py
• noesis/usecases/finalization.py
• noesis/usecases/immutability.py
• noesis/usecases/run_lifecycle.py
• tests/runtime/test_sealing_flow.py
• tests/runtime/test_final_schema.py
• tests/runtime/test_run_lifecycle.py