Engifoundry Exec

EngiFoundry Exec

Execution Selection

This section applies only to the controlling Agent arranging execution. A session that received engifoundry.executor-task/v1 is already the Executor Worker; the protocol is a terminal routing fact. It skips Executor selection and invocation, must not compare or infer its model identity, executes only the referenced Job, and returns one engifoundry.executor-handback/v1 object. It must never invoke or select another Executor.

The controlling Agent reads ./engifoundry.config.json, the project-owned workspace guide, the complete Executor and Workflow config files, contracts.md, and executor-task.template.json in full. Follow the Executor config's schemaRef and read that complete schema before selecting or invoking an Executor. Do not extract only executor, command, model, or usage; the surrounding fields and every declared Gate remain binding. Then read the Phase, PAK, and Job contracts before acting.

Compare only the active model with the configured Executor model; CLI identity and executorId do not decide execution ownership. When the configuration pins the same canonical model as the active model, the controlling Agent directly executes eligible Jobs in the current session without invoking an Executor Worker or producing a Worker handback. This is normal configured execution, not fallback or self-approval. The controlling Agent still applies all Exec discipline, evidence, Review, approval, and completion rules.

When the pinned models differ, invoke the configured Executor through its verified CLI usage, including the configured canonical model argument. A cli-default selection makes no model identity promise and therefore has no same-model fast path; invoke its configured CLI. Once the invocation accepts the task, model selection is settled by the controlling session and the receiving Worker executes it. Natural-language model self-identification is not trusted evidence: a model may know only its family name rather than the configured product alias.

Boundary

Execute only a heavyweight package PAK with planning.status: ready. A direct PAK is light work performed by the controlling Agent and never enters Exec or uses the configured Executor. Treat Package JSON as authoritative. Never change scope, dependencies, acceptance criteria, allowed or forbidden areas, stop conditions, or Review requirements. Contract revision belongs to Orch.

Run eligible Jobs in dependency order. A Job is eligible only when every dependency is complete. Obey its type, allowed areas, forbidden areas, and stop conditions.

When external invocation is required, use only the single configured executor. It is usable only when its configured command and pinned model, if any, are available and the Agent can start its verified invocation. Read its recorded input capabilities and construct protocol engifoundry.executor-task/v1 exactly as defined in the reference contract. Its handback member always embeds the complete handback schema; a format-only reference is invalid because the Worker must not discover that schema elsewhere. Prefer verified native structured input and a separate system/instruction role channel when recorded; otherwise use the canonical plain-text wrapper. Identity fields, handback schema, and zero-delegation rules are identical in both forms and are never optional. A legacy configuration without capability facts uses the text wrapper.

Run bounded work from the project root, provide only the selected Job contract paths and required concise handback, and inspect actual process state before deciding availability. The controlling session owns all routing, orchestration, Review, Verify, delivery, and control-record writes. A running or quiet process is not unavailable; inspect available liveness facts before making that conclusion. Do not persist prompts, raw streams, or transient process state.

Apply the reference contract's strict production and tolerant consumption rules to normalize raw Executor output. Do not retry merely because one semantically valid handback has surrounding prose or unknown fields.

Validate normalized identity before accepting work. A wrong role, delegated: true, non-empty controlActions, further Agent or worker invocation, or controlling behavior is executor-role-violation: stop, inspect workspace effects, and reject the handback. This is an execution failure, not gate.executorUnavailable. Retry only for missing or ambiguous required semantics or another safely correctable invalid handback. Never repair the prompt ad hoc or accept recursively delegated work.

Evaluate gate.executorUnavailable before any fallback when external invocation is required. Objective unavailability exists only when the command is missing, authentication fails, the verified invocation cannot start, the CLI explicitly rejects the configured model, or trusted transport metadata identifies a different canonical model. Never activate the Gate from the Worker's self-description or inference. Stop the task and ask whether the current controlling session may take over. Proceed only after explicit approval; that approval applies to the current task and never rewrites project configuration. The configured same-model path never reaches this Gate because it requires no external invocation. Do not silently substitute another CLI, model, or Agent. A started invocation that returns incorrect output, failing tests, a self-reported model mismatch, or another work result is an execution failure and follows normal handback validation, debugging, or rework rules, not this Gate.

A Review blocking finding is not gate.executorUnavailable and is not a factual blocked state while it remains correctable within the current authorized contract.

Discipline

Apply all four rules:

1. TDD: For behavior changes, write the failing test first when feasible. Otherwise record the factual exception and use alternative verification.
2. Systematic debugging: Reproduce or characterize, gather evidence, form a hypothesis, make a targeted fix, then verify. Never jump from a symptom to a broad rewrite.
3. Review: Apply the Job's reviewRequired. When true, output and fresh evidence lead to pending-review, and the configured Reviewer reads engifoundry-review in the current PAK Review chain. The first PAK Review or a contract-defined reset starts clean; otherwise Planning, Job, and rework Reviews continue the same Reviewer session. When false, required outputs and execution evidence can complete Review facts without an independent Review record. Scope expansion, failed required checks, shared-interface changes, or material security, data, compatibility, destructive, or delivery risk set reviewRequired to true before completion.
4. Verification before completion: Produce fresh, task-appropriate execution evidence for Review. Failed checks are failed results. Do not claim a Job complete from Executor handback alone.

Review correction is governed by contract satisfaction and Review's new-finding limits, never an attempt count. Read Review and apply its complete convergence rules. Continue while observed reality can still be reconciled with the contract. Follow a stable, evidenced correction path immediately when it identifies bounded changes within allowed areas, addresses the cited fact, has runnable verification, and needs no unauthorized contract change; otherwise continue systematic debugging. Its absence is a reason to investigate, not to interrupt. Pause only when objective evidence meets the blocked threshold, a contract-required user or external fact is unavailable, or the user bounds the work. Rework never permits scope expansion, forbidden edits, skipped verification, or self-approval.

Completion

Write one concise Job result using the reference contract. Normal results contain only effective information. Add exceptions only for fallback, deviation, failure, or blocker facts. Never store prompts, reasoning, raw streams, routine progress, command transcripts, or long logs.

Before implementation begins, the Package and selected Job record in-progress. Finished implementation with required outputs and fresh evidence is pending-review when reviewRequired is true; otherwise it is eligible for completion or configured approval. Executor handback alone is never completion.

A Job is completed while its required outputs and evidence exist, any required Review is pass, and configured user approval exists. A skipped Review is valid only with reviewRequired: false. The other completion facts are:

• approval-pending: current execution evidence and any required Review passed, but job-approval has no user decision.
• rework-required: current self-test evidence, blocking Review, Deliver rejection, or user evidence shows a correctable failure to satisfy the current authorized contract.
• blocked: an objective condition prevents bounded execution or Review, or safe resolution requires a user-authorized contract, design, scope, or authority change.

Record every actionable self-test, Review, user, or Deliver finding that requires Job correction in reworkFacts with its source and available contract and evidence references. Under job-approval, present the current Job execution conclusion and its Review result when Review occurred. User approval supplies the missing completion fact. A rejection that changes the contract also makes Package planning rework-required.

A downstream finding affects its current Job by default, and reopening a completed upstream Job is discouraged. Dependency or a non-blocking finding alone does not justify reopening. When current evidence identifies an upstream Job as the appropriate correction boundary, record the finding in that Job's reworkFacts, reopen only the minimum affected work, and re-Review only changed Jobs; unchanged completion and evidence remain current.

When evidence proves that safe resolution cannot fit the current authorized contract, record the affected Job and Package as blocked, preserve the exact conflict and evidence, explain why in-contract correction is impossible, identify the user decision required, and stop implementation. Repeated failed corrections alone do not establish this fact. After the user authorizes a direction, read Orch to revise the minimum affected contracts before implementation resumes. A rejection without an actionable blocking fact leaves approval-pending and requires the reason.

Package execution is jobs-completed when every current Job satisfies completed. Historical completion evidence remains attached even if a qualifying blocking fact later changes current state. The Agent does not perform final Package verification or delivery while applying Exec.

Continuation

For an endpoint that includes verification or delivery, jobs-completed is the fact that lets the Agent read Verify and continue with the PAK. An approval pause, factual blocker, or explicit user boundary is terminal for the current application of Exec.