docs: document process registry operations

[cursor]

Noēsis Pull Request

Overview

Documents the process registry operational contract for grouped episode runs, process-oriented CLI inspection, liveness, and troubleshooting.

Type of Change

• 🧩 Core framework (runtime, faculties, orchestrator, schema)
• 📈 Cognitive model or paper implementation (ReAct, Reflexion, ToT, Meta-CoT, etc.)
• 🧠 Meta-cognition or learning feedback logic
• ⚙️ Infrastructure / CI / build system
• 📚 Documentation or research notes
• 🧪 Experiment / benchmark / curriculum update
• 🧰 Developer experience (CLI, codemod, viewer, tooling)
• 🗃️ Dataset / artifact update (checkpoints, corpora, prompt packs)
• Other (please describe):

Motivation & Context

The process registry subsystem has source-backed behavior for stable process identity, per-process run indexes, process liveness, and CLI filtering, but the public docs only briefly mentioned noesis processes and noesis runs. This PR adds a concise operator/developer reference so teams can use and troubleshoot grouped runs without reading implementation code.

Technical Details

Docs added/updated:

• Added docs/reference/process-registry.mdx covering architecture, CLI usage, canonical .noesis/processes/ layout, process record fields, artifact links, liveness states, and troubleshooting.
• Updated docs/reference/cli.mdx with grouped-run examples, process liveness semantics, runs --json output shape, and a link to the new runbook.
• Updated docs/docs.json navigation to include the new reference page.

Codepaths covered:

• noesis.core._bootstrap_episode, _start_process_heartbeat, and _finalize_episode
• noesis.domain.process.derive_process_identity and Process
• noesis.infrastructure.process_registry.FileProcessRegistry
• noesis.usecases.process_registry.ProcessRegistryService
• Typer CLI commands in noesis.cli.__main__: run --process, ps --process, processes, and runs

Key knowledge gaps addressed:

• How --process labels map to opaque process ids.
• Where registry records are stored and how index.json is used/rebuilt.
• What running, stale, idle, and error mean for operator views.
• How process metadata appears in summary.json, state.json, and final.json.
• How to troubleshoot missing process rows, stale processes, and unexpected process ids.

No runtime code or schemas changed.

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 JSON/read validation for docs/docs.json, docs/reference/process-registry.mdx, and docs/reference/cli.mdx passed.
• Installed local validation dependencies in the automation environment, then ran:
  python3 -m pytest tests/cli/test_process_commands.py tests/infrastructure/test_process_registry.py tests/infrastructure/test_process_registry_concurrency.py tests/infrastructure/test_process_registry_resilience.py tests/usecases/test_process_registry_staleness.py tests/domain/test_process_identity.py
• Result: 8 passed.

Notes:

• Initial targeted pytest run failed because the base environment lacked typer; installing the package in editable mode resolved the missing runtime dependency.
• Full docs build was not run because this repository does not include a docs package script in the checkout.

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

Schema checklist not applicable: documentation-only change with no artifact field changes.

Observability & Safety

Improves operational clarity for process liveness and registry troubleshooting. No telemetry, policy logic, or runtime behavior changed.

Educational / Research Value

Helps developers understand how repeated agent workflows are grouped into stable process identities and how those identities connect to episode artifacts.

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

Screenshots / Logs

8 passed in 0.43s

Related Issues / References

N/A