docs: document process identity workflows

[cursor]

🧠 Noēsis Pull Request

Overview

Documents process identity workflows and state authority boundaries for process-scoped runs.

Docs added/updated:

• docs/reference/state.mdx: documents state.process, fields, constraints, and resume requirement.
• docs/reference/cli.mdx: adds home-screen behavior, process grouping examples, process liveness fields, JSON shapes, and troubleshooting.
• docs/reference/python-api.mdx: documents the process parameter for ns.run, ns.solve, and sessions.
• docs/explanation/artifacts.mdx: adds a concise authority model for trace-derived, registry-backed, and persisted state slices.

Type of Change

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

Motivation & Context

Recent runtime and state work made process identity operationally important, but public docs did not explain state.process, process-scoped CLI workflows, or which state slices are trace-derived versus registry-backed.

Technical Details

Codepaths covered and verified against:

• noesis/domain/process.py
• noesis/infrastructure/process_registry.py
• noesis/usecases/process_registry.py
• noesis/core.py
• noesis/domain/state/models.py
• noesis/infrastructure/state_repository.py
• noesis/cli/__main__.py

Key knowledge gaps addressed:

• How process.id, process.name, process.kind, and process.run_index are emitted and used.
• How to group runs with --process, inspect registry liveness, and filter process runs.
• Why state.process is registry-backed while plan, outcomes, and links have trace/projection authorities.
• Which process metadata is required for same-run continuation.

Validation

Required

• Targeted tests pass: /tmp/noesis-docs-venv2/bin/python -m pytest tests/cli/test_process_commands.py tests/domain/test_process_identity.py tests/cli/test_home_help.py -q (19 passed)
• Schema validation and export diff clean: not applicable; documentation-only, no schema fields changed

Situational

• Cognitive loop tested end-to-end (Observe → Learn)
• Docs build/link check: cd docs && npx --yes mintlify@latest broken-links (success, no broken links)
• CLI smoke tests pass (python scripts/pre_release.py --check-all)
• Benchmarks / eval sweeps reproduced
• Artifact integrity checked (hashes, licensing, storage footprint)

Additional check:

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

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 (equivalent Mintlify reference docs updated under docs/reference/*)

Observability & Safety

No runtime behavior changed. The new docs clarify operational liveness versus persisted state snapshots so operators do not treat stale state.process data as current registry state.

Educational / Research Value

• Replication kit (configs, seeds, sweeps, data access notes): N/A

Screenshots / Logs

19 passed in 0.48s
success no broken links found

Related Issues / References

Automated documentation maintenance run for process identity and state authority gaps.