Implement validator, hooks, and validation wiring

[nnoce14]

Summary

Implement the enforcement layer that keeps the orchestration workflow consistent.

Why

Prompts, instructions, and agent files alone are not strong enough to enforce a delivery protocol consistently.

The orchestration system itself needs validation, runtime enforcement, and explicit workflow-state control.

Scope

Conformance validator

Implement a repo-local validator that checks whether the orchestration system is wired correctly for the active repo capability profile and orchestration spec.

Validation should cover things like:

• repo capability profile is valid
• required package/path class mappings are present
• enabled lane families are coherent with the selected profile
• required agents exist for supported behavior
• required skills exist for supported behavior
• hook configuration references valid files/scripts
• framework-oriented components are not activated in application-only
• artifact mode configuration is valid
• completion gate references are valid
• workflow states and transitions are structurally valid

Workflow enforcement runtime

Implement a workflow-enforcement runtime that maintains lightweight per-session state and enforces the orchestration state machine.

At minimum, it should support:

• session identity
• current workflow state
• selected task lane
• selected/recent agent role
• transition history
• minimal counters/guardrails needed for safety and loop prevention

This runtime may persist its state under a lightweight repo-local working area such as .agents-work/, but it must respect the minimal artifact posture by default.

Phase/state transition enforcement

Use hooks and enforcement scripts to:

• validate state transitions
• block invalid transitions
• validate whether a requested agent is permitted in the current state
• validate whether a requested tool/action is permitted in the current state
• move the workflow to the next valid state when allowed

Phase-based agent allowlists

Implement phase/state-based agent allowlists.

Examples:

• planner roles valid in planning states
• implementor roles valid in implementation/revision states
• reviewer roles valid in review states
• framework-surface review only valid when framework-oriented behavior and lane routing require it

Hook guidance and denial responses

Hook denials must include actionable guidance rather than only returning allow/deny.

When blocking or redirecting a workflow step, the system should return enough context to help the orchestrator recover correctly.

Examples:

• wrong agent for current phase
• invalid next transition
• missing planning step
• framework-only behavior requested in application-only profile

Idempotency and safety-valve behavior

Add safeguards for:

• repeated hook events
• duplicate transition processing
• retry/idempotency behavior
• blocked-stop / retry loops
• deadlock or infinite-review churn

The enforcement engine itself must be treated as product code and tested accordingly.

Hooks

Add a narrow, high-value first version of hook-based enforcement for things such as:

• session initialization
• missing task classification detection
• disallowed command/tool blocking by role
• validation evidence logging
• blocked/escalation handling

Validation wiring

Add repo-local commands and CI/local validation entrypoints so the orchestration system can be checked like other product code.

Explicit integration with PR #186

The validator and enforcement layer should recognize cellix-tdd as a framework-oriented skill and verify that:

• it is available when reusable framework work is supported
• it is not required for application-only
• the wiring remains coherent as PR Add new agent skill cellix-tdd #186 lands

Artifact posture

Do not require heavyweight runtime artifacts for trivial tasks.

The enforcement layer must respect the artifact mode policy defined by the orchestration model.

Future extensibility requirement

The validator and hooks must target abstract rules such as:

• valid profile/capability usage
• valid lane selection
• valid state transition
• valid skill/agent availability
• valid completion gates

Do not make enforcement depend on today’s specific folder names or package namespaces.

Acceptance criteria

• orchestration conformance validator implemented
• validator reads the orchestration spec
• validator fails on inconsistent configuration
• workflow-enforcement runtime implemented
• per-session workflow state persisted and validated
• workflow state transitions enforced by hooks
• phase-based agent allowlists implemented
• hook denials include actionable guidance
• enforcement engine tested for transition correctness, idempotency, and loop-safety
• first-pass hooks implemented
• validation commands documented and runnable
• CI/local validation wiring added
• enforcement distinguishes between portable core and framework-oriented extensions
• enforcement works for mixed, framework-only, and application-only repo profiles