ai_ops/docs/pipeline-policies.md

Pipeline Policies and Lifecycle Hooks

Why this exists

PipelineExecutor previously handled DAG traversal, failure heuristics, state persistence, and domain-event emission in one execution loop. This made behavior harder to isolate and test.

Current structure

• FailurePolicy (src/agents/failure-policy.ts)
  • Owns hard vs soft failure classification.
  • Determines whether a sequence of hard failures should abort execution.
• PersistenceLifecycleObserver (src/agents/lifecycle-observer.ts)
  • Handles state patching, project-context updates, and domain-event publishing for each node attempt.
• PipelineExecutor (src/agents/pipeline.ts)
  • Coordinates DAG traversal and retry behavior.
  • Computes aggregate run status from executed terminal nodes plus critical-path failures.
  • Applies dedicated SecurityViolationError handling policy (hard_abort or validation_fail mapping).
  • Resolves per-attempt ResolvedExecutionContext (phase/model/tool/security contract) and injects it into actor executors.

Aggregate status semantics

Run status is success only when both are true:

1. All executed terminal nodes (leaves in the executed subgraph) have final status success.
2. No executed node in the critical path has final status failure.

Otherwise status is failure.

Persistence guarantees

State and project-context writes are now atomic via temp-file + rename. Project-context patch/write operations are serialized both in-process (promise queue) and cross-process (lock file).

Tool enforcement guarantees

• Pipeline resolves a flat allowedTools list per node attempt.
• MCP config exposed to executors is pre-filtered to allowedTools.
• Claude tool callbacks are expected to use the provided policy handler so unsupported shared MCP tool filters cannot bypass enforcement.