Skip to content

AIFACTORY-FEAT-109: Workflow definition: Module blueprints

Generated from the architecture model

This page is rendered from model/**/*.yaml by tools/docs_model during mkdocs build. Edit the YAML, not this page; hand-written design lives on the linked service, platform and plane pages.

A design artefact, not a tracker

This backlog is generated from model/backlog/ and validated against the architecture model. No work item exists in any tracker, and no item carries a date, an estimate or an assignee (ADR-0029).

Epic Factory assets: workflow definitions, agents and skills · Increment I1 Generate a microservice · State elaborated · Route solution-architect · Build order 87 of 185 (Factory code)

The workflow definition module-blueprints as a published asset: Produces one Module Blueprint per context of a derived context map: the clean-architecture layout, template switches and adapters each module will be scaffolded with. It has 6 steps, names the agents solution-architect and the tools blueprint-submit-version, blueprint-validate, and is executed by WorkflowEngineService under Run Control.

Delivers —
Stubs —
Realizes workflows: module-blueprints
adrs: ADR-0014, ADR-0024, ADR-0026, ADR-0027
Requirements FR-11, XL-09
Depends on —
Sources model/workflows/module-blueprints.yaml

Scenarios to trace (7, catalog): SCN-module-blueprints-001 ✓, SCN-module-blueprints-002 ✓, SCN-module-blueprints-003 ✓, SCN-module-blueprints-004 ✓, SCN-module-blueprints-005 ✓, SCN-module-blueprints-006 ✓, SCN-module-blueprints-007 ✓

AIFACTORY-US-010: One Module Blueprint per context, drafted in parallel

behavior · persona requester As a requester, I want a validated Module Blueprint for every context of my product, so that each module can be designed and generated on its own.

The integration PBI of the definition module-blueprints. The run is activated, not submitted by a person: the readiness correlation of WorkflowEngineService for the project waits for two required members, service-blueprint satisfied by BlueprintValidated of kind Service with passed true and context-map satisfied by ContextMapDerived with at least one context for that blueprint version, and then submits exactly one run through SubmitRun of RunControlService with a service token that names the project and the idempotency key of scope, operation, workflow release and bundle fingerprint; a newer Service Blueprint version opens a new correlation and supersedes the open one. After RunAccepted the engine loads the Draft release through AgentRegistryService and runs fan-out-contexts, which starts one branch per context of the map; in each branch the solution-architect release drafts the Module Blueprint, the tools blueprint-submit-version and blueprint-validate store and validate it, and check-valid loops back to the draft at most twice; join waits for every branch. Every agent and tool step declares failure_policy Retry and submit-version declares idempotency_key documentHash (ADR-0014). The run outputs are the Module Blueprints of every branch and their receipts; each passed receipt publishes BlueprintValidated of kind Module, the signal that activates application-design and lets GenerationRecipeService pin the module. The run reports exactly one outcome within the declared budget. The step behaviour is specified in AIFACTORY-US-1145 to AIFACTORY-US-1148; this PBI proves the chain on the recorded fixture. How a branch is bound to its context and whether the loop limit counts per branch are not declared by the definition and are carried as assumptions by AIFACTORY-US-1145 and AIFACTORY-US-1148. The tasks AIFACTORY-TASK-209 and AIFACTORY-TASK-210 of this PBI moved to AIFACTORY-US-1146 and AIFACTORY-US-1145, the PBIs whose behaviour they prove, with their repository and kind unchanged.

Acceptance criteria

AC1 Given the Draft release of module-blueprints (workflow-definition-v1) with its readiness activation, 6 steps, mappings, retry policies, timeouts and the idempotency_key documentHash of module-blueprints/submit-version exactly as in model/workflows/module-blueprints.yaml, when BlueprintService/BlueprintValidated of kind Service with passed true and BlueprintService/ContextMapDerived for that version both arrive, then the WorkflowEngineService/ReadinessCorrelation submits one run through RunControlService/SubmitRun with a service token naming the project and WorkflowEngineService/ReadinessRunSubmitted is published.
AC2 Given RunControlService/RunAccepted with inputs service-blueprint and context-map of three contexts, when the run executes, then WorkflowEngineService/WorkflowRunStarted is emitted, module-blueprints/fan-out-contexts starts three branches, each runs module-blueprints/draft-module, module-blueprints/submit-version, module-blueprints/validate and module-blueprints/check-valid on the pinned release of solution-architect, and module-blueprints/join completes after the last branch.
AC3 Given every branch passes, when the run completes, then module-blueprints (blueprint-module-v1) holds one validated Module Blueprint per context, BlueprintService/BlueprintValidated of kind Module was published once per module with passed true, WorkflowEngineService/WorkflowRunCompleted is emitted once and RunControlService/RunCompleted follows exactly once (ADR-0014, FR-11).
AC4 Given one branch fails, when module-blueprints/join is reached, then WorkflowEngineService/WorkflowRunFailed names the failed step, the Module Blueprints of the other branches stay recorded as artifacts and as Draft or Validated versions, RunControlService/RunFailed is published exactly once, and a gated submit waits on RunControlService/ApprovalRequested until RunControlService/ApprovalDecided (ADR-0026).
AC5 Given the recorded fixture inputs of model/workflows/module-blueprints.yaml, when the fixture run executes in the pipeline, then its outputs match the recorded ones field by field, every step output validates against its descriptor and the run stays within the declared budget (ADR-0024).
Traces: workflows module-blueprints
Traces: steps module-blueprints/fan-out-contexts, module-blueprints/draft-module, module-blueprints/submit-version, module-blueprints/validate, module-blueprints/check-valid, module-blueprints/join
Traces: agents solution-architect
Traces: tools blueprint-submit-version, blueprint-validate
Traces: services WorkflowEngineService, RunControlService, AgentRegistryService, BlueprintService
Traces: aggregates WorkflowEngineService/ReadinessCorrelation
Traces: apis RunControlService/SubmitRun
Traces: events BlueprintService/BlueprintValidated, BlueprintService/ContextMapDerived, WorkflowEngineService/ReadinessRunSubmitted, WorkflowEngineService/WorkflowRunStarted, WorkflowEngineService/WorkflowRunCompleted, WorkflowEngineService/WorkflowRunFailed, RunControlService/RunAccepted, RunControlService/RunCompleted, RunControlService/RunFailed, RunControlService/ApprovalRequested, RunControlService/ApprovalDecided
Traces: descriptors workflow-definition-v1, readiness-bundle-v1, blueprint-service-v1, blueprint-module-v1, blueprint-validation-receipt-v1
Traces: adrs ADR-0014, ADR-0024, ADR-0026, ADR-0027
Traces: requirements FR-11, XL-09
Depends on AIFACTORY-US-1145, AIFACTORY-US-1146, AIFACTORY-US-1147, AIFACTORY-US-1148, feature:workflow-engine-service, feature:run-control-service, feature:agent-registry-service-thin, feature:blueprint-service, feature:wf-architecture-decomposition
Sources model/workflows/module-blueprints.yaml, model/agents/architecture/solution-architect.yaml, docs/planes/agent-runtime/workflow-definitions/module-blueprints.md

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-172 Author the release of the workflow definition module-blueprints from the model implementation A Draft release of module-blueprints (workflow-definition-v1) with its readiness activation on BlueprintValidated of kind Service and ContextMapDerived, its 6 steps with the parallel fan-out-contexts and join, input mappings, retry policies, timeouts, the on_false loop of check-valid, the compensation policy and the budget as in model/workflows/module-blueprints.yaml, the failure_policy Retry of draft-module, submit-version and validate copied as it stands and the idempotency_key documentHash of submit-version; loadable by AgentRegistryService. ConnectSoft.AI.SoftwareFactory.WorkflowEngineService
AIFACTORY-TASK-173 Author the agent releases solution-architect with their prompts and skills implementation A Draft release of solution-architect with its instructions, the skill solution-architect-draft-module among its bound skills, the tool bindings and the model profile reasoning-high; the release passes a smoke evaluation of the suite architecture-core-v1 on a fixture Service Blueprint and context map. ConnectSoft.AI.SoftwareFactory.AgentTemplate
AIFACTORY-TASK-174 Fixture run of module-blueprints against recorded inputs verification The definition runs end to end on a fixture project from the readiness signals to RunCompleted; every step output of every branch validates against its descriptor and the outputs module-blueprints and validation-receipt match the recorded ones field by field (AC1 to AC3 and AC5 of AIFACTORY-US-010). ConnectSoft.AI.SoftwareFactory.WorkflowEngineService
AIFACTORY-TASK-730 Verify module-blueprints-in-parallel by running the declared command verification Run dotnet test -c Release --filter Category=WorkflowFixture; it passes and proves AC1 to AC5 of AIFACTORY-US-010, including the failed branch of AC4 with the other branches kept and RunFailed exactly once. ConnectSoft.AI.SoftwareFactory.WorkflowEngineService

AIFACTORY-US-1145: The engine starts one branch per context of the map and joins them with every output kept

behavior · persona requester As a requester, I want every context of my context map drafted in its own branch, in parallel, and one failed branch to fail the run without losing the others, so that the modules are designed at the same time and a single bad module does not erase the good ones.

The two parallel steps of module-blueprints, which the engine evaluates itself without an agent, a tool or a retry. The step summary says fan-out-contexts starts one branch per context of the context map and the branches run in parallel within the token, cost and time caps of the run. The definition does not say how: it gives the fan-out no input and no collection expression, it gives draft-module no branch item but the whole input.context-map, and WorkflowEngineService defines only the step kinds Fanout and Join and the option Workflows:Engine:MaxFanout (default 16). This PBI therefore states as an assumption, pending the owner, that the engine iterates the contexts of the recorded context-map input and that each branch carries its context to draft-module, submit-version, validate and check-valid; what happens when the map names more contexts than MaxFanout is not stated and is reported to the owner as well. A context map without contexts never reaches the engine, because the readiness member requires contexts greater than zero. The fan-out completes with exactly one outcome within PT1M. When join becomes ready it waits for every branch: when all branches passed their check-valid it completes with one outcome and the run completes with the Module Blueprints and receipts of every branch as outputs; when one branch failed, because a step exhausted its retries or its condition reached the iteration limit, the join fails the run with that branch's evidence while the outputs of the other branches stay recorded as artifacts under the run envelope and their versions stay as BlueprintService left them. Neither step changes a shared system; a fan-out or join that exceeds its timeout PT1M fails with evidence and is not retried (none, 0 attempts).

Acceptance criteria

AC1 Given the recorded input context-map names three contexts, when the engine evaluates module-blueprints/fan-out-contexts, then, under the assumption of this PBI that the fan-out iterates the contexts of that input and binds one to each branch, three branches start, each with module-blueprints/draft-module ready for its own context, and the fan-out records exactly one outcome under the run envelope; the binding and the case of more contexts than Workflows:Engine:MaxFanout stay pending the owner (SCN-module-blueprints-001).
AC2 Given every branch passed module-blueprints/check-valid, when the engine evaluates module-blueprints/join, then the join completes with one outcome and WorkflowEngineService/WorkflowRunCompleted carries the Module Blueprints and receipts of all branches as run outputs (SCN-module-blueprints-007).
AC3 Given one branch failed and the others passed, when module-blueprints/join is reached, then WorkflowEngineService/WorkflowRunFailed names the failed step of that branch, the outputs of the other branches stay recorded as artifacts and no version is changed by the join (SCN-module-blueprints-007, ADR-0014).
AC4 Given the fan-out or the join exceeds its timeout PT1M, when the engine applies the policy of model/workflows/module-blueprints.yaml, then the step fails with evidence without a retry and the run follows the compensation policy (SCN-module-blueprints-001, SCN-module-blueprints-007).
Traces: workflows module-blueprints
Traces: steps module-blueprints/fan-out-contexts, module-blueprints/join
Traces: services WorkflowEngineService
Traces: aggregates WorkflowEngineService/WorkflowRun
Traces: events WorkflowEngineService/StepReady, WorkflowEngineService/WorkflowRunCompleted, WorkflowEngineService/WorkflowRunFailed
Traces: descriptors artifact-v1, blueprint-module-v1
Traces: scenarios SCN-module-blueprints-001, SCN-module-blueprints-007
Traces: adrs ADR-0014
Traces: requirements FR-11
Depends on feature:workflow-engine-service, feature:run-control-service
Sources model/workflows/module-blueprints.yaml, model/services/agent-mesh/WorkflowEngineService.yaml, model/scenarios/module-blueprints.yaml

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-210 Fixture run with three contexts verification A fixture Service Blueprint whose context map names three contexts yields three branches and three validated Module Blueprints, and a second fixture in which the branch of one context fails after its iteration limit while the two other Module Blueprints stay recorded; proves SCN-module-blueprints-001 and SCN-module-blueprints-007 (AC1 to AC4 of AIFACTORY-US-1145). ConnectSoft.AI.SoftwareFactory.WorkflowEngineService
AIFACTORY-TASK-4571 Verify the fan-out and the join of the Draft release against the definition verification A check of the release authored by AIFACTORY-TASK-172 against model/workflows/module-blueprints.yaml proves that fan-out-contexts and join carry kind parallel, gate none, side_effect_class sandbox, timeout PT1M and no retry, that draft-module depends on fan-out-contexts and join on check-valid, and that draft-module maps service-blueprint and context-map from the run inputs; the branch binding and the per-branch iteration count are not checked, because the definition declares neither and both are pending the owner. ConnectSoft.AI.SoftwareFactory.WorkflowEngineService
AIFACTORY-TASK-4572 Recorded context maps for the parallel paths fixture Recorded context-map inputs (artifact-v1) with one and with three contexts and the expected branch list, as the oracle of SCN-module-blueprints-001. ConnectSoft.AI.SoftwareFactory.WorkflowEngineService

AIFACTORY-US-1146: The Solution Architect drafts the Module Blueprint of one context with template, switches and adapters

behavior · persona requester As a requester, I want each module of my product drafted with the template, the switches and the adapters it will be scaffolded with, so that generation scaffolds every module from an explicit, checkable choice.

The sandbox-class agent step draft-module, run once in every branch. When the engine marks it ready it resolves service-blueprint from input.service-blueprint and context-map from input.context-map, the whole map, since the definition declares no branch item; that the branch names the context the module is drafted for is the binding assumed by AIFACTORY-US-1145, pending the owner. On a revision pass the findings of the branch's last receipt are attached as feedback. The solution-architect release runs the skill solution-architect-draft-module, writes the Module Blueprint with write-file in the isolated workspace and returns module-blueprint-draft (blueprint-module-v1): the one bounded context it references (MOD-001), the template id and version, the switches it uses (persistence, messaging profile, actors, scheduler, AI), each outbound dependency with its port and owning context (MOD-003) and for persistence the store class and the TenantId convention (MOD-004). The step writes nothing outside the run envelope and needs no approval. It declares failure_policy Retry with the exponential budget of 3 attempts and backoff 30s for a Failed attempt of failure class transient; an attempt that exceeds PT30M, fails with another failure class or exhausts the budget fails its branch with evidence, which join turns into a failed run.

Acceptance criteria

AC1 Given a branch for one context under the binding assumed by AIFACTORY-US-1145, when solution-architect executes module-blueprints/draft-module with solution-architect-draft-module, then module-blueprint-draft validates against blueprint-module-v1, references exactly that context of the Service Blueprint, names the template version, the switches and the adapters, and is recorded once under the run envelope (SCN-module-blueprints-002).
AC2 Given a revision pass of the branch after module-blueprints/check-valid took its false branch, when the step re-runs, then the findings of the branch's receipt are in its context and the new draft addresses each finding by rule id MOD-001 to MOD-004 or by schema path (SCN-module-blueprints-002, ADR-0026).
AC3 Given an attempt exceeds PT30M, settles Failed with a non-transient failure class or exhausts the exponential budget of 3 attempts, when the engine applies the policy of model/workflows/module-blueprints.yaml, then the branch fails with evidence, the sandbox output stays in place and no shared system is changed (SCN-module-blueprints-002, ADR-0014).
Traces: workflows module-blueprints
Traces: steps module-blueprints/draft-module
Traces: agents solution-architect
Traces: services WorkflowEngineService
Traces: events WorkflowEngineService/StepReady
Traces: descriptors blueprint-service-v1, artifact-v1, blueprint-module-v1
Traces: scenarios SCN-module-blueprints-002
Traces: adrs ADR-0014, ADR-0026, ADR-0027
Traces: requirements FR-11
Depends on AIFACTORY-US-1145, feature:workflow-engine-service, feature:run-control-service
Sources model/workflows/module-blueprints.yaml, model/skills/architecture/solution-architect-draft-module.yaml, model/blueprints.yaml, model/scenarios/module-blueprints.yaml

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-209 Solution architect release implementation The step draft-module of the release authored by AIFACTORY-TASK-172 runs solution-architect-draft-module with service-blueprint and context-map mapped as in model/workflows/module-blueprints.yaml and the context of its branch under the binding assumed by AIFACTORY-US-1145; the release chooses template version, switches and adapters for a context and its fixture output is valid against blueprint-module-v1. ConnectSoft.AI.SoftwareFactory.AgentTemplate
AIFACTORY-TASK-4573 Fixture Module Blueprint drafts per context with a revision pass fixture The expected module-blueprint-draft (blueprint-module-v1) for each of the three fixture contexts, and a revision fixture with a MOD-003 finding as feedback and the draft that resolves it, as the oracle of SCN-module-blueprints-002. ConnectSoft.AI.SoftwareFactory.AgentTemplate
AIFACTORY-TASK-4574 Prove the draft-module step on the fixture verification A fixture run proves SCN-module-blueprints-002 (AC1 to AC3 of AIFACTORY-US-1146); every draft references exactly its context, the revision pass resolves the finding by rule id, and the timeout path fails the branch with evidence. ConnectSoft.AI.SoftwareFactory.WorkflowEngineService

AIFACTORY-US-1147: Each Module Blueprint is stored as a Draft version and validated against the MOD rules and the pinned template manifest

behavior · persona requester As a requester, I want every drafted Module Blueprint stored as a Draft version and validated against its schema, the MOD rules and the manifest of the template it pins, so that a module never reaches generation with a switch its template does not declare.

The two tool steps of each branch, whose service behaviour BlueprintService, ToolAdapterService and TemplateRegistryService deliver; this PBI binds them and proves what the definition expects. submit-version resolves document from steps.draft-module.module-blueprint-draft, the engine emits StepReady with actionClass shared-write, and blueprint-submit-version reaches Blueprints.SubmitDraftVersion, which stores a project-scope Draft BlueprintVersion of kind Module, idempotent on its document hash; Draft versions are autonomous unless the project policy (BC-20) gates blueprint drafts, in which case the invocation waits on an approval requested through RunControl.RequestApproval with proposalKind tool-invocation that names the run and the step and is bound to the request hash and the exact tool version (D64). The declared idempotency_key documentHash lets Run Control retry a Failed attempt of failure class transient under the fixed budget of 2 attempts; an Uncertain attempt is settled only by an operator through ConfirmToolEffect. validate calls Blueprints.Validate with the version reference: BlueprintService checks blueprint-module-v1 and the rules MOD-001 to MOD-004 and evaluates MOD-002 against the manifest of the pinned template version, which it reads through Catalog.ResolveManifest of TemplateRegistryService, one finding per switch the manifest does not declare. The receipt is recorded whether it passed or not and BlueprintValidated of kind Module carries passed; BlueprintService moves a passed version to Validated and leaves a failed one Draft. While the registry does not answer the call is answered Unavailable, the version stays as it was and the attempt is transient and retried; a version reference of another tenant is answered NOT_FOUND and the attempt is permanent and not retried (ADR-0015).

Acceptance criteria

AC1 Given steps.draft-module.module-blueprint-draft is recorded and the project policy does not gate blueprint drafts, when module-blueprints/submit-version runs blueprint-submit-version through BlueprintService/Blueprints.SubmitDraftVersion, then a Draft BlueprintService/BlueprintVersion of kind Module exists in project scope, version-ref is recorded once and a resubmission of the same document returns the same reference (SCN-module-blueprints-003, D64).
AC2 Given the project policy gates blueprint drafts, or an attempt settles Failed transient or Uncertain, when module-blueprints/submit-version runs, then the approval is requested through RunControlService/RunControl.RequestApproval with proposalKind tool-invocation, bound to the invocation request hash and the exact tool version, the write waits for an approving RunControlService/ApprovalDecided after RunControlService/ApprovalRequested naming the run and the step, a rejection yields ToolAdapterService/ToolInvocationDenied, a transient failure is retried under the fixed budget of 2 attempts, and an Uncertain attempt raises ToolAdapterService/ToolEffectUncertain and waits for ToolAdapterService/ConfirmToolEffect (SCN-module-blueprints-003, ADR-0014).
AC3 Given steps.submit-version.version-ref is recorded, when module-blueprints/validate runs blueprint-validate through BlueprintService/Blueprints.Validate, then MOD-002 is evaluated against the manifest that TemplateRegistryService/Catalog.ResolveManifest returns for the pinned template version, validation-receipt is recorded once with findings by rule id MOD-001 to MOD-004 whether it passed or not, and BlueprintService/BlueprintValidated of kind Module carries passed (SCN-module-blueprints-004).
AC4 Given TemplateRegistryService does not answer, when module-blueprints/validate runs, then the call is answered Unavailable, no receipt is written, the version stays as it was and the attempt is retried as transient until the fixed budget of 2 attempts or the timeout PT5M is spent; given a version reference of another tenant, it is answered NOT_FOUND and the attempt takes failure class permanent without a retry (SCN-module-blueprints-004, ADR-0015).
Traces: workflows module-blueprints
Traces: steps module-blueprints/submit-version, module-blueprints/validate
Traces: tools blueprint-submit-version, blueprint-validate
Traces: services BlueprintService, TemplateRegistryService, ToolAdapterService, RunControlService, WorkflowEngineService
Traces: aggregates BlueprintService/BlueprintVersion
Traces: apis BlueprintService/Blueprints.SubmitDraftVersion, BlueprintService/Blueprints.Validate, TemplateRegistryService/Catalog.ResolveManifest, ToolAdapterService/ConfirmToolEffect, RunControlService/RunControl.RequestApproval
Traces: events BlueprintService/BlueprintValidated, RunControlService/ApprovalRequested, RunControlService/ApprovalDecided, ToolAdapterService/ToolInvocationDenied, ToolAdapterService/ToolEffectUncertain
Traces: descriptors blueprint-module-v1, blueprint-version-ref-v1, blueprint-validation-receipt-v1
Traces: scenarios SCN-module-blueprints-003, SCN-module-blueprints-004
Traces: adrs ADR-0014, ADR-0015, ADR-0026, ADR-0027
Traces: requirements FR-11
Depends on AIFACTORY-US-1146, feature:blueprint-service, feature:template-registry-service, feature:tool-adapter-service, feature:run-control-service, feature:workflow-engine-service
Sources model/workflows/module-blueprints.yaml, model/tools/blueprint-submit-version.yaml, model/tools/blueprint-validate.yaml, model/services/template-library/BlueprintService.yaml, model/services/template-library/TemplateRegistryService.yaml, model/scenarios/module-blueprints.yaml

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-4575 Fixture Module Blueprints with their manifests and expected receipts fixture One fixture Module Blueprint whose switches the pinned template manifest declares, with its expected receipt and Validated state, one that uses an undeclared switch with its MOD-002 finding and Draft state, a registry that does not answer with the expected Unavailable and unchanged version, and a version reference of another tenant with the expected NOT_FOUND. ConnectSoft.AI.SoftwareFactory.BlueprintService
AIFACTORY-TASK-4576 Verify submit-version and validate of the Draft release against the definition verification A check of the release authored by AIFACTORY-TASK-172 against model/workflows/module-blueprints.yaml proves that the steps submit-version and validate name the tools blueprint-submit-version and blueprint-validate, carry side_effect_class shared-write and sandbox, failure_policy Retry, the idempotency_key documentHash on submit-version only, the fixed retry of 2 attempts with backoff 10s, the timeouts PT2M and PT5M and the mappings document from steps.draft-module.module-blueprint-draft and version-ref from steps.submit-version.version-ref; the tool bindings are consumed from feature tool-adapter-service and nothing is authored here. ConnectSoft.AI.SoftwareFactory.WorkflowEngineService
AIFACTORY-TASK-4577 Prove the submit and validate steps for Module Blueprints on the fixture verification A fixture run proves SCN-module-blueprints-003 and SCN-module-blueprints-004 (AC1 to AC4 of AIFACTORY-US-1147), including the idempotent resubmission, the gated path, the Uncertain path settled through ConfirmToolEffect, the MOD-002 finding against the manifest returned by Catalog.ResolveManifest, the transient retry while the registry does not answer and the NOT_FOUND of another tenant. ConnectSoft.AI.SoftwareFactory.WorkflowEngineService

AIFACTORY-US-1148: The engine checks each branch's receipt and sends its findings back to its draft at most twice

behavior · persona requester As a requester, I want a failed Module Blueprint validation to go back to its own draft a bounded number of times, so that each module improves on its findings while the other branches are not held back.

The condition step of each branch of module-blueprints. When check-valid becomes ready in a branch the engine evaluates steps.validate.validation-receipt.passed == true over that branch's recorded receipt; the condition is read class, calls no service, never retries and completes within PT1M. A passed receipt completes the branch with one outcome and the branch waits at join. A failed one takes the on_false branch to draft-module of the same branch with that receipt as feedback; draft-module, submit-version and validate re-run in order for that context only, and the revised document gets its own Draft version and receipt. The definition declares max_iterations 2 but not whether it counts per branch or per run, WorkflowEngineService does not say either, and the scenario derived from the definition counts the iteration on the run. This PBI assumes a count per branch, so that one context's revisions do not use up another's, and reports the point to the owner; the per-branch statements below hold only under that assumption. When the receipt is still failed after the second iteration the branch fails with the validation report as evidence and failure class validation, its Draft versions stay Draft, and join fails the run while the other branches' outputs stay recorded. A missing or unreadable receipt fails the condition with evidence instead of being read as passed (ADR-0026, D61).

Acceptance criteria

AC1 Given a branch's receipt is recorded with passed true, when the engine evaluates module-blueprints/check-valid for that branch, then the condition completes with exactly one outcome, no service is called and the branch reaches module-blueprints/join (SCN-module-blueprints-005).
AC2 Given a branch's receipt has passed false and fewer than 2 iterations were counted, per branch under the assumption of this PBI that is pending the owner, when the engine evaluates module-blueprints/check-valid, then it takes the false branch to module-blueprints/draft-module of the same branch with the receipt as feedback and only that branch re-runs submit and validate (SCN-module-blueprints-006).
AC3 Given a branch's receipt is still passed false after the second iteration, when the engine evaluates module-blueprints/check-valid, then the branch fails with the report and failure class validation, WorkflowEngineService/WorkflowRunFailed names check-valid once module-blueprints/join is reached, and RunControlService/RunFailed is published exactly once (SCN-module-blueprints-006, ADR-0014).
AC4 Given the receipt is missing or unreadable or the evaluation exceeds PT1M, when the engine evaluates module-blueprints/check-valid, then the condition is not retried and the branch fails with evidence as the compensation policy of model/workflows/module-blueprints.yaml says (SCN-module-blueprints-005, ADR-0026).
Traces: workflows module-blueprints
Traces: steps module-blueprints/check-valid, module-blueprints/draft-module, module-blueprints/join
Traces: services WorkflowEngineService
Traces: events WorkflowEngineService/WorkflowRunFailed, RunControlService/RunFailed
Traces: descriptors blueprint-validation-receipt-v1
Traces: scenarios SCN-module-blueprints-005, SCN-module-blueprints-006
Traces: adrs ADR-0014, ADR-0026
Traces: requirements FR-11
Depends on AIFACTORY-US-1147, feature:workflow-engine-service, feature:run-control-service
Sources model/workflows/module-blueprints.yaml, model/services/agent-mesh/WorkflowEngineService.yaml, model/scenarios/module-blueprints.yaml

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-4578 Fixture receipt sequences per branch for the pass, loop and limit paths fixture Recorded receipt sequences for a three-branch run in which one branch passes at once, one passes after a loop and one fails three times, with the expected run outcome and the expected iteration count per branch, the latter dependent on the owner decision whether max_iterations counts per branch or per run. ConnectSoft.AI.SoftwareFactory.WorkflowEngineService
AIFACTORY-TASK-4579 Prove the per-branch condition and bounded loop on the fixture verification A fixture run proves SCN-module-blueprints-005 and SCN-module-blueprints-006 (AC1 to AC4 of AIFACTORY-US-1148); one outcome on pass, a loop back to the draft of the same branch with feedback, iteration counts per branch as assumed pending the owner, and WorkflowRunFailed naming check-valid after the limit with the other branches kept. ConnectSoft.AI.SoftwareFactory.WorkflowEngineService