docs: document action candidate governance flow

[cursor]

🧠 Noēsis Pull Request

Overview

Documents the pre-act action-candidate governance flow so the public event reference, cognitive-loop narrative, and governed side-effects tutorial match the runtime trace contract.

Type of Change

• 📚 Documentation or research notes

Motivation & Context

Recent runtime work made action_candidate a first-class event phase for side-effect governance, but the docs still skipped its payload contract and omitted the blocked-direction trace emitted for enforced vetoes.

Technical Details

• Updated docs/reference/events.mdx with the action_candidate payload schema, required state/redaction fields, lineage rules, and act.payload.action_candidate_id linkage.
• Expanded the governance event reference with source-backed GovernanceResult.to_mapping() fields, including schema_version, decision_id, mode, failure_policy, enforced, and error.
• Updated docs/explanation/cognitive-loop.mdx to include action_candidate in the phase sequence, refresh the direction/governance examples, and explain enforced-veto versus pause-on-veto ordering.
• Updated docs/tutorials/governed-side-effects.mdx to show direction(status="blocked") → action_candidate → governance before terminate/checkpoint outcomes.

Covered codepaths: noesis/domain/action_candidates.py, noesis/usecases/action_gating.py, noesis/usecases/actuation/candidate_builder.py, noesis/usecases/governed_actuation.py, noesis/interfaces/observability.py, and governance/veto assertions in tests/insight/test_governance_metrics.py.

Key knowledge gaps addressed: missing action_candidate reference payload, unclear state_ref/state_hash/redaction constraints, missing action_candidate_id lineage for act, and misleading veto ordering for governed side effects.

Validation

Required

• Equivalent targeted suite: git show --check --stat --oneline HEAD; concrete JSON-fence parser for changed docs (22 parsed, 2 pre-existing placeholder fences skipped)
• Schema validation and export diff clean: docs-only change; no stable schema files changed

Situational

• Cognitive loop tested end-to-end (docs-only change)
• Docs build successfully (pnpm run build in docs/) (not run; no local docs package)
• CLI smoke tests pass (python scripts/pre_release.py --check-all) (not run; docs-only change)
• Benchmarks / eval sweeps reproduced (not applicable)
• Artifact integrity checked (not applicable)

Additional validation:

• npx --yes mintlify@latest broken-links from docs/

ADR-003 Schema Governance Checklist

• $schema_version bumped for every artifact whose stable fields changed (not applicable; docs-only)
• docs/schema/** regenerated (not applicable)
• KPI updates include version bumps plus math/clamp/rationale updates in internal_docs/schema/kpi*.yaml (not applicable)
• Relevant entry added to MIGRATIONS.schema.md or MIGRATIONS.kpi.md (not applicable)
• python scripts/schema_guard.py --strict --json passes locally (not run; docs-only)
• Docs under reference updated when new fields surface to users

Observability & Safety

Clarifies audit evidence and no-act invariants for governed side effects. No runtime behavior changed.

Educational / Research Value

Improves developer/operator understanding of how Noēsis records candidate side effects before governance and how veto evidence should be read from events.jsonl.

Screenshots / Logs

success no broken links found
Concrete JSON fences valid: 22; skipped placeholders: 2

Related Issues / References

• Source contracts: ActionCandidate, govern_pre_act_action, RuntimeEventBus.emit_action_candidate, GovernanceResult.to_mapping()

  

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
noesis	🟢 Ready	View Preview	Jun 29, 2026, 4:12 PM

💡 Tip: Enable Workflows to automatically generate PRs for you.