docs: document process registry contracts

[cursor]

🧠 Noēsis Pull Request

Overview

Documents the process registry contract across the public Python API, CLI workflows, and persisted artifacts. This is a documentation-only update for the existing process grouping subsystem.

Type of Change

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

Motivation & Context

Recent runtime and CLI surfaces expose process grouping via process=... / --process, process liveness inspection, and process blocks in summary.json and state.json. The docs did not yet explain how process names, opaque process IDs, run indices, and filters fit together.

Technical Details

• Updated docs/reference/python-api.mdx for ns.run(..., process=...), ns.solve(..., process=...), and noesis.io.list_runs() process rows.
• Updated docs/reference/cli.mdx with grouped-run examples, process liveness status meanings, filter usage, and runs --json output shape.
• Updated docs/reference/summary.mdx and docs/reference/state.mdx with the persisted process artifact block and field semantics.
• Verified behavior against noesis/__init__.py, noesis/domain/process.py, noesis/infrastructure/process_registry.py, noesis/usecases/process_registry.py, noesis/cli/__main__.py, and state/summary serialization code.

Validation

Required

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

Validation performed: git diff --check HEAD~1..HEAD passed. No runtime code or schema files changed.

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

No schema contract changed; this PR documents existing fields.

Observability & Safety

Clarifies that process liveness is best-effort registry metadata and that process IDs are opaque machine references derived from workspace identity plus process label.

Educational / Research Value

Helps operators and developers connect grouped episode runs to the process registry and artifact fields without reading implementation code.

Screenshots / Logs

git diff --check HEAD~1..HEAD passed.

Related Issues / References

Source paths verified: noesis/domain/process.py, noesis/infrastructure/process_registry.py, noesis/cli/__main__.py, noesis/runtime/summary.py, noesis/domain/state/models.py.