Workflow engine and validation

Workflow engine

The dag model

The workflow graph defines the main steps, dependencies, output contracts, review defaults, and return paths. It describes valid progression, not an autonomous scheduler. The domain graph and its artifact contracts survive the current agent-body migration. Removing UI handoff metadata does not remove graph edges or their approval gates.

Use Run the workflow for the reader-facing sequence. Product changes to the graph, agent definitions, or skills require their own review and validation. Editing project state is not a way to customize the graph.

Gates and approval points

The human approves requirements, architecture and cost, governance constraints, and the implementation plan. Code validation precedes deployment, and explicit apply authorization is still required. After deployment, inspect the actual resources and health checks before accepting the as-built record.

Review defaults differ by step. In particular, Architecture has a separate cost-estimate review, Governance has reconciliation, and Deploy has no Challenger review. See the review matrix.

If a gate fails, return to the owning step and resolve its evidence. A retained artifact can still be stale after an upstream decision changes.

Native tasks and questions

Select a main agent directly when you want it to ask and resolve material questions. Requirements, Architect, Design, and Governance retain their native question tools. A delegated main worker returns USER_INPUT_REQUIRED, including request_id, phase, message, requestedSchema.properties, and missing inputs, to its interactive parent instead. Leaves never ask users or delegate.

Use the native task result and lifecycle available in that session. Continue an asynchronous task only through a handle that actually supports same-task continuation. A one-shot task returns its result; it does not promise a resumable worker. Neither model selection nor a static tool list proves permission isolation.

The source migration removes worker-ready, nonce, WORKER_EXECUTE, mandatory verifier, and log-preflight rituals from active bodies and shared caller guidance. Historical diagnostic readers remain. Production independent review receipts, record-review attribution, and freshness validation still apply.

For independent review, the owner-approved October 19 candidate adapts the existing challenger-review-subagent into one read-only structured JSON leaf. Automatic producers, authorized Orchestrator calls, and optional manual 10-Challenger reviews use the same synchronous native APEX_REVIEW task contract. The interactive owner captures metadata and records the actual attributed output centrally, then validates schema, freshness, and provenance. Review budgets, lenses, step gates, security requirements, and owner approvals are unchanged. Final source and native runtime evidence remain pending. See review finalization and recovery.

IaC routing

Requirements records the chosen Bicep or Terraform track. Step 4 uses the shared 05-IaC Planner. Steps 5 and 6 select the matching CodeGen and Deploy agents. Do not invent separate Step 4 agents or activate both tracks implicitly.

Session state and resume

Use apex-recall show <project> --json to inspect state. It reads primary state without restoring backups. Participating writers use locks and revision checks. Primary replacement and index updates are separate operations, so a write can commit while leaving the index stale.

The public state contract defines conflicts, idempotent retries, and authorized recovery. These mechanisms do not lock arbitrary editors or guarantee a multi-file transaction.

Reopening a completed step with start-step --force marks the steps that depend on it as stale and sets plan_status to SUPERSEDED when a Plan approval rested on it. A stale step must be completed again in order before the next step can start. See Reopen a completed step.

Session break protocol

Before starting a new chat, retain the handoff, current decisions, relevant artifacts, and unresolved findings. Select the appropriate main agent in the new session and inspect current evidence. Do not assume the old conversation contains everything needed to resume safely. Retain 00-handoff.md even though active definitions omit handoffs: metadata. Use a native task result or explicitly select the next named agent, not an assumed handoff button. A question answer does not independently authorize the transition.

For damaged state, follow session recovery.

Quality and safety systems

Validation scripts

Product validators check artifact structure, agent and skill definitions, governance contracts, IaC, and source metadata. The validation reference identifies the relevant commands. Use the product’s package.json for its current command inventory.

The apex-docs build, link checks, and browser tests validate this website instead. A passing website build is not an infrastructure validation result.

Git hooks (pre-commit and pre-push)

The product uses lefthook to run checks on staged changes and before a push. Read the configured hooks for their actual scope. Hooks are not proof that all changes were scanned, especially when tools are missing or a commit bypasses hooks.

Circuit breaker

Repeated failures should stop work and preserve diagnostic evidence. Follow the owning agent’s retry and escalation rules. Do not use a generic retry count or waiting period as permission to repeat a failed cloud mutation.

Unavailable or empty review output does not satisfy a required review. Use the declared recovery path and human handoff rather than inventing an inline approval.

Context compression

The apex-context-management skill describes selective loading and summarization. Read the necessary artifact sections and keep decision evidence available. Do not describe estimated context percentages as measured runtime guarantees.

A short summary cannot replace the exact input coverage required by a validator or reviewer. Skills and runtime artifact summaries serve different purposes.

Copilot hooks

The owner intentionally deleted APEX .github/hooks/ runtime hooks in the October 18 migration. tool-guardian and subagent-validation are historical, not active protections or setup requirements. Do not restore or replace them. Native tool restrictions do not establish equivalent protection; verify their permission boundaries separately. Git Lefthook and CI remain separate. See the runtime-hook retirement record.