Skip to content

AIFACTORY-FEAT-107: Workflow definition: Vision to blueprint

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 85 of 185 (Factory code)

The workflow definition vision-to-blueprint as a published asset: Runs the Vision Architect Agent from a prompt and constraints to a validated Vision Blueprint with its artifacts, clarifying assumptions first and revising on validation findings. It has 6 steps, names the agents vision-architect and the tools blueprint-submit-version, blueprint-validate, and is executed by WorkflowEngineService under Run Control.

Delivers —
Stubs —
Realizes workflows: vision-to-blueprint
adrs: ADR-0014, ADR-0024, ADR-0026
Requirements FR-07, FR-08, FUX-06, FUX-11, XL-03
Depends on —
Sources model/workflows/vision-to-blueprint.yaml

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

AIFACTORY-US-073: The Vision to blueprint workflow runs from its published definition

behavior · persona requester As a requester, I want the vision to blueprint workflow to run from its published definition with the agents, tools and gates it declares, so that vision-blueprint, validation-receipt are produced the same way on every run, with evidence.

The integration PBI of the definition vision-to-blueprint. A requester submits a run whose release pins the definition; RunControlService accepts it and publishes RunAccepted with the inputs prompt (run-submission-v1) and constraints (execution-scope-v1). WorkflowEngineService loads the Draft release through AgentRegistryService, opens its projection of the run and marks the six steps ready in the declared order: clarify-intent, draft-vision, submit-version, validate, check-valid and store-artifacts. Agent steps run the vision-architect release with its bound skills; tool steps call blueprint-submit-version and blueprint-validate; the condition reads the recorded receipt and loops back to the draft at most twice. Every agent and tool step declares failure_policy Retry in model/workflows/vision-to-blueprint.yaml and the release copies that value as it stands; the condition check-valid declares none. The one shared-write step, submit-version, also declares idempotency_key documentHash, which is what lets its Retry hold: Run Control retries a Failed attempt only when its failure class is transient and the step is of read or sandbox class, or of shared-write class with a declared idempotency key, and an attempt that fails with any other failure class fails its step without a retry (ADR-0014). A run whose definition, agent release or tool binding cannot be resolved is refused before any step runs. Every step records exactly one attempt outcome under the run envelope, the run reports exactly one outcome to Run Control (ADR-0014) and the run stays within the declared budget. The behaviour of each step pair is specified in AIFACTORY-US-181 to AIFACTORY-US-184; this PBI proves the whole chain on the recorded fixture.

Acceptance criteria

AC1 Given the Draft release of vision-to-blueprint is loadable by AgentRegistryService with its 6 steps, input mappings, retry policies, timeouts, the failure_policy each agent and tool step declares (Retry on all five) and the idempotency_key documentHash of vision-to-blueprint/submit-version exactly as in model/workflows/vision-to-blueprint.yaml, when a RunControlService/RunAccepted event arrives for that release with inputs prompt and constraints, then WorkflowEngineService/WorkflowRunStarted is emitted and the steps vision-to-blueprint/clarify-intent, vision-to-blueprint/draft-vision, vision-to-blueprint/submit-version, vision-to-blueprint/validate, vision-to-blueprint/check-valid and vision-to-blueprint/store-artifacts become ready in that order, each agent step on the pinned release of vision-architect.
AC2 Given every step succeeds, when the run completes, then vision-blueprint (blueprint-vision-v1) and validation-receipt (blueprint-validation-receipt-v1) are recorded as the run outputs under the run envelope, WorkflowEngineService/WorkflowRunCompleted is emitted once and RunControlService/RunCompleted follows exactly once (ADR-0014).
AC3 Given an attempt of a step that declares failure_policy Retry settles Failed with failure class transient until the retry budget of the step is exhausted, or settles Failed with any other failure class, which is never retried, or the condition vision-to-blueprint/check-valid reaches its iteration limit, when the engine applies the compensation policy of model/workflows/vision-to-blueprint.yaml, then WorkflowEngineService/WorkflowRunFailed names the failed step and the failure class, the sandbox outputs stay in place as evidence, no blueprint version is submitted for publication and RunControlService/RunFailed is published exactly once (recovery, not replay, ADR-0014).
AC4 Given the project policy gates blueprint drafts, when vision-to-blueprint/submit-version is reached, then the run waits WaitingForApproval on a RunControlService/ApprovalRequested for the gated tool invocation and resumes only on the matching RunControlService/ApprovalDecided, exactly as AIFACTORY-US-182 AC3 specifies the gate (ADR-0026, D64).
AC5 Given the recorded fixture inputs of model/workflows/vision-to-blueprint.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 vision-to-blueprint
Traces: steps vision-to-blueprint/clarify-intent, vision-to-blueprint/draft-vision, vision-to-blueprint/submit-version, vision-to-blueprint/validate, vision-to-blueprint/check-valid, vision-to-blueprint/store-artifacts
Traces: agents vision-architect
Traces: tools blueprint-submit-version, blueprint-validate
Traces: services WorkflowEngineService, RunControlService, AgentRegistryService
Traces: events RunControlService/RunAccepted, RunControlService/RunCompleted, RunControlService/RunFailed, RunControlService/ApprovalRequested, RunControlService/ApprovalDecided, WorkflowEngineService/WorkflowRunStarted, WorkflowEngineService/WorkflowRunCompleted, WorkflowEngineService/WorkflowRunFailed
Traces: descriptors workflow-definition-v1, run-submission-v1, execution-scope-v1, blueprint-vision-v1, blueprint-validation-receipt-v1
Traces: adrs ADR-0014, ADR-0024, ADR-0026
Traces: requirements FR-07, FR-08, FUX-06, FUX-11, XL-03
Depends on AIFACTORY-US-181, AIFACTORY-US-182, AIFACTORY-US-183, AIFACTORY-US-184, feature:workflow-engine-service, feature:run-control-service, feature:agent-registry-service-thin
Sources model/workflows/vision-to-blueprint.yaml, model/agents/vision-planning/vision-architect.yaml, docs/planes/agent-runtime/workflow-definitions/vision-to-blueprint.md

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-166 Author the release of the workflow definition vision-to-blueprint from the model implementation A Draft release of vision-to-blueprint (workflow-definition-v1) with its 6 steps, input mappings, retry policies, timeouts, the on_false loop of check-valid and the compensation policy as in model/workflows/vision-to-blueprint.yaml, and with the failure_policy that each agent and tool step declares there copied as it stands and never derived (Retry on clarify-intent, draft-vision, submit-version, validate and store-artifacts; the condition check-valid declares none), together with the idempotency_key documentHash that the shared-write step submit-version declares and that makes its Retry valid; the release is loadable by AgentRegistryService and accepted by ValidateWorkflowDefinition of WorkflowEngineService, which refuses an agent, tool or human step without a failure policy. ConnectSoft.AI.SoftwareFactory.WorkflowEngineService
AIFACTORY-TASK-167 Author the agent release vision-architect with its prompts and skills implementation A Draft release of vision-architect with its instructions, the six bound skills of model/agents/vision-planning/vision-architect.yaml, the tool bindings and the model profile reasoning-high; the release passes a smoke evaluation of the suite vision-planning-core-v1 on a fixture brief. ConnectSoft.AI.SoftwareFactory.AgentTemplate
AIFACTORY-TASK-168 Fixture run of vision-to-blueprint against recorded inputs verification The definition runs end to end on a fixture project in the acceptance environment from a RunAccepted event to RunCompleted; every step output validates against its descriptor and the outputs vision-blueprint and validation-receipt match the recorded ones field by field (AC1, AC2, AC5 of AIFACTORY-US-073). ConnectSoft.AI.SoftwareFactory.WorkflowEngineService
AIFACTORY-TASK-739 Verify vision-to-blueprint-runs-from-its-definition by running the declared command verification Run dotnet test -c Release --filter Category=WorkflowFixture; it passes and proves AC1 to AC5 of AIFACTORY-US-073, including the failure path of AC3 (WorkflowRunFailed then RunFailed exactly once) and, at chain level, the wait of AC4 (the run waits WaitingForApproval on the gated step and resumes on the matching decision; the gate itself is proven by AIFACTORY-TASK-927). ConnectSoft.AI.SoftwareFactory.WorkflowEngineService

AIFACTORY-US-181: The Vision Architect clarifies the intent and drafts the Vision Blueprint from the prompt

behavior · persona requester As a requester, I want the open questions of my prompt listed with the assumptions taken, and a Vision Blueprint drafted on them, so that I can correct a wrong assumption before the blueprint is validated and stored.

The first two agent steps of vision-to-blueprint. When the engine marks clarify-intent ready it resolves brief from input.prompt and constraints from input.constraints; the vision-architect release runs the skill vision-architect-clarification in read class and writes one artifact listing the open questions of the brief and the assumption taken for each, in a form the requester can correct. When draft-vision becomes ready it receives the same brief and constraints plus assumptions from steps.clarify-intent.assumptions, and on a revision pass the findings of the last validation receipt as feedback; the skill vision-architect-author-the-vision-blueprint-document writes the Vision Blueprint document (problem, goals, scope classes, personas, constraints and success measures) against blueprint-vision-v1 in sandbox class. Neither step touches a shared system, needs an approval or calls a service other than the Factory's own context and artifact stores. Each attempt records exactly one outcome with its evidence; both steps declare failure_policy Retry, and being of read and sandbox class a Failed attempt of failure class transient is retried under the exponential budget of 3 attempts, while an attempt that fails with any other failure class is not retried. A step that exceeds its timeout PT30M, fails with a non-transient failure class or exhausts that retry budget fails the run with the evidence, nothing having been written outside the run envelope.

Acceptance criteria

AC1 Given a run accepted with inputs prompt (run-submission-v1) and constraints (execution-scope-v1), when the engine marks vision-to-blueprint/clarify-intent ready and vision-architect executes it, then the output assumptions (artifact-v1) is recorded once under the run envelope, lists every open question with its assumption, and vision-to-blueprint/draft-vision becomes ready (SCN-vision-to-blueprint-001).
AC2 Given steps.clarify-intent.assumptions is recorded, when vision-to-blueprint/draft-vision runs with brief, constraints and assumptions resolved, then the output vision-blueprint-draft validates against blueprint-vision-v1, carries the assumptions it relies on and is recorded once under the run envelope (SCN-vision-to-blueprint-002).
AC3 Given a revision pass after the condition vision-to-blueprint/check-valid took its false branch, when vision-to-blueprint/draft-vision re-runs, then the findings of steps.validate.validation-receipt are present in its context as feedback and the new draft addresses each finding of the receipt by rule id (VIS-001 to VIS-004 or the schema path) (SCN-vision-to-blueprint-002, ADR-0026).
AC4 Given an attempt of vision-to-blueprint/clarify-intent or vision-to-blueprint/draft-vision exceeds its timeout PT30M, settles Failed with a failure class other than transient, or settles Failed with failure class transient until the retry budget of its declared failure_policy Retry (exponential, 3 attempts) is exhausted, when the engine applies the policy of model/workflows/vision-to-blueprint.yaml, then the attempt fails with evidence, the sandbox output stays in place, WorkflowEngineService/WorkflowRunFailed names the step and no shared system is changed (ADR-0014).
Traces: workflows vision-to-blueprint
Traces: steps vision-to-blueprint/clarify-intent, vision-to-blueprint/draft-vision
Traces: agents vision-architect
Traces: services WorkflowEngineService
Traces: events RunControlService/RunAccepted, WorkflowEngineService/StepReady, WorkflowEngineService/WorkflowRunFailed
Traces: descriptors run-submission-v1, execution-scope-v1, artifact-v1, blueprint-vision-v1
Traces: scenarios SCN-vision-to-blueprint-001, SCN-vision-to-blueprint-002
Traces: adrs ADR-0014, ADR-0026
Traces: requirements FR-07
Depends on feature:workflow-engine-service, feature:run-control-service
Sources model/workflows/vision-to-blueprint.yaml, model/agents/vision-planning/vision-architect.yaml, model/scenarios/vision-to-blueprint.yaml

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-921 Recorded fixture for clarify-intent and draft-vision fixture A fixture brief and constraints with the expected assumptions artifact (artifact-v1) and the expected Vision Blueprint draft (blueprint-vision-v1), plus a second fixture carrying a receipt with findings as feedback for the revision pass of SCN-vision-to-blueprint-002. ConnectSoft.AI.SoftwareFactory.AgentTemplate
AIFACTORY-TASK-922 Verify the input mappings and skill selection of the two agent steps in the Draft release verification The steps clarify-intent and draft-vision of the Draft release authored by AIFACTORY-TASK-166 resolve brief, constraints and assumptions exactly as mapped in model/workflows/vision-to-blueprint.yaml and select the skills vision-architect-clarification and vision-architect-author-the-vision-blueprint-document of the vision-architect release; the feedback attachment on the on_false branch is engine behaviour delivered by AIFACTORY-TASK-928 and is not repeated here. ConnectSoft.AI.SoftwareFactory.WorkflowEngineService
AIFACTORY-TASK-923 Prove the clarify and draft steps on the fixture verification A fixture run proves SCN-vision-to-blueprint-001 and SCN-vision-to-blueprint-002 (AC1 to AC3 of AIFACTORY-US-181) and the timeout and retry exhaustion path of AC4 with a WorkflowRunFailed that names the step; the outputs validate against artifact-v1 and blueprint-vision-v1. ConnectSoft.AI.SoftwareFactory.WorkflowEngineService

AIFACTORY-US-182: The draft is stored as a project-scope Draft version and validated with a receipt

behavior · persona requester As a requester, I want the drafted Vision Blueprint stored as a Draft version of my project and validated against its schema and the VIS rules, so that a validation verdict with findings exists for every draft before anything is published.

The two tool steps of vision-to-blueprint. When submit-version becomes ready the engine resolves document from steps.draft-vision.vision-blueprint-draft and emits StepReady with actionClass shared-write; its part ends there, because the engine never owns run authority and runs no gate itself. Run Control dispatches the attempt and the tool blueprint-submit-version goes through the fixed pipeline of ToolAdapterService: schema validation, agent permission, tenant policy, side-effect classification and approval if required. Draft versions are autonomous by default; when the project policy (BC-20) gates blueprint drafts the pipeline moves the invocation to AwaitingApproval and requests the approval through RunControl.RequestApproval, bound to the invocation's request hash (which covers the document hash) and the exact tool version, with proposalKind tool-invocation; Run Control publishes ApprovalRequested and the run waits WaitingForApproval (D64). Only with an approving decision bound to that hash does the invocation reach Blueprints.SubmitDraftVersion of BlueprintService under the run's workload identity: the document is stored as a project-scope Draft BlueprintVersion of kind Vision, idempotent on its document hash, so the same document returns the same version. The step declares that hash as its idempotency_key documentHash in model/workflows/vision-to-blueprint.yaml, which is why Run Control may retry a Failed attempt of failure class transient although the step is shared-write; a Failed attempt of any other failure class is not retried. A rejected or expired decision denies the invocation (ToolInvocationDenied) and the attempt fails policy-denied. When validate becomes ready the tool blueprint-validate calls Blueprints.Validate with the version reference: BlueprintService validates the version against the blueprint-vision-v1 JSON Schema and the rules VIS-001 to VIS-004 and returns a receipt that carries the verdict, the document hash and the findings (a rule id or the schema path, severity and path). The call stays sandbox class and writes only the receipt; the tool never changes the state of the version. BlueprintService itself moves the version from Draft to Validated when it records ValidationPassed for that exact document hash and leaves it Draft when the receipt fails, and it emits BlueprintValidated with passed true or false and the document hash. A version reference that belongs to another tenant is answered with the gRPC status NOT_FOUND, the same answer as for a version that does not exist, so nothing confirms that it exists; the attempt that receives it takes the failure class permanent and is not retried (ADR-0015). A receipt with passed false is a successful step output, not a failure; both tool steps declare failure_policy Retry, which applies to a Failed attempt of failure class transient, and the validate step fails only on timeout PT5M, on a non-transient failure such as that NOT_FOUND, or on exhausted retries. The submit call is audited with blueprintId, version, kind and documentHash and the validate call with blueprintId, version, documentHash, kind, passed, validationReportRef and receiptHash, as the tool cards declare; the submit writes nothing beyond the Draft version and the validate call nothing beyond the receipt (ADR-0026). A submit attempt whose effect cannot be confirmed settles as Uncertain and, the step being shared-write, is never retried automatically, idempotency key or not: an operator settles it through ConfirmToolEffect before the run fails or continues.

Acceptance criteria

AC1 Given steps.draft-vision.vision-blueprint-draft is recorded and the project policy does not gate blueprint drafts, when vision-to-blueprint/submit-version runs blueprint-submit-version through BlueprintService/Blueprints.SubmitDraftVersion, then a Draft BlueprintVersion of kind Vision exists in project scope, the output version-ref (blueprint-version-ref-v1) with blueprint id, version, kind, document hash and state Draft is recorded once under the run envelope and no approval is requested (SCN-vision-to-blueprint-003, D64).
AC2 Given the same document is submitted again in the same project (a retry or a repeated run), when BlueprintService/Blueprints.SubmitDraftVersion is called with the same document hash, then the same version reference is returned, no second Draft version is created and the audit record carries blueprintId, version, kind and documentHash (SCN-vision-to-blueprint-003).
AC3 Given the project policy gates blueprint drafts, when vision-to-blueprint/submit-version is reached, then WorkflowEngineService/StepReady carries actionClass shared-write, the pipeline of ToolAdapterService/ToolInvocation classifies the blueprint-submit-version invocation shared-write, moves it to AwaitingApproval and requests the approval through RunControlService/RunControl.RequestApproval bound to the invocation request hash (which covers the document hash) with proposalKind tool-invocation; a RunControlService/ApprovalRequested is published before any write, the run waits WaitingForApproval, and BlueprintService/Blueprints.SubmitDraftVersion is called only on an approving RunControlService/ApprovalDecided for that hash; a rejected or expired decision denies the invocation with ToolAdapterService/ToolInvocationDenied and the attempt fails policy-denied without a Draft version (SCN-vision-to-blueprint-003, ADR-0026, D64).
AC4 Given steps.submit-version.version-ref is recorded, when vision-to-blueprint/validate runs blueprint-validate through BlueprintService/Blueprints.Validate, then the call writes only the receipt, whose findings carry a rule id (VIS-001 to VIS-004) or the schema path with severity and path, the output validation-receipt (blueprint-validation-receipt-v1) is recorded once under the run envelope whether it passed or not, BlueprintService/BlueprintValidated is emitted with passed true or false and the document hash, and BlueprintService itself moves the BlueprintService/BlueprintVersion from Draft to Validated with validationReportRef set when it records ValidationPassed for that exact document hash and leaves it Draft when the receipt fails; a version reference of another tenant is answered with the gRPC status NOT_FOUND like an unknown version, with no receipt and no state change, and the attempt takes the failure class permanent and is not retried (SCN-vision-to-blueprint-004, ADR-0015).
AC5 Given an attempt of vision-to-blueprint/submit-version settles Failed with failure class transient (BlueprintService was unreachable before any effect), when Run Control evaluates the step, then the attempt is retried under the fixed budget (2 attempts, backoff 10s) of its declared failure_policy Retry, which holds for this shared-write step because it declares idempotency_key documentHash, and on exhaustion the attempt fails with evidence, a Draft version already stored stays a Draft and is never promoted, and the run follows the compensation policy of model/workflows/vision-to-blueprint.yaml; given the attempt settles Failed with any other failure class (BlueprintService refused the document), then it is not retried and the step fails the same way; given instead the attempt settles Uncertain (timeout PT2M after the call was dispatched, no receipt), then it is never retried automatically because the step is shared-write (RunControlService/Attempt invariant), the attempt stays Uncertain with ToolAdapterService/ToolEffectUncertain until an operator settles it through ToolAdapterService/ConfirmToolEffect, after which the run fails or continues, and the idempotency on documentHash guarantees that a confirmed effect is never duplicated; an attempt of vision-to-blueprint/validate that exceeds its timeout PT5M or settles Failed with failure class transient (sandbox class, failure_policy Retry, fixed, 2 attempts) is retried until exhausted and then fails with evidence (SCN-vision-to-blueprint-003, SCN-vision-to-blueprint-004, ADR-0014).
Traces: workflows vision-to-blueprint
Traces: steps vision-to-blueprint/submit-version, vision-to-blueprint/validate
Traces: tools blueprint-submit-version, blueprint-validate
Traces: services BlueprintService, WorkflowEngineService, ToolAdapterService, RunControlService
Traces: aggregates BlueprintService/BlueprintVersion, ToolAdapterService/ToolInvocation, RunControlService/Attempt
Traces: apis BlueprintService/Blueprints.SubmitDraftVersion, BlueprintService/Blueprints.Validate, RunControlService/RunControl.RequestApproval, ToolAdapterService/ConfirmToolEffect
Traces: events BlueprintService/BlueprintValidated, WorkflowEngineService/StepReady, RunControlService/ApprovalRequested, RunControlService/ApprovalDecided, ToolAdapterService/ToolInvocationDenied, ToolAdapterService/ToolEffectUncertain
Traces: descriptors blueprint-vision-v1, blueprint-version-ref-v1, blueprint-validation-receipt-v1
Traces: scenarios SCN-vision-to-blueprint-003, SCN-vision-to-blueprint-004
Traces: adrs ADR-0014, ADR-0015, ADR-0026
Traces: requirements FR-08, FUX-06
Depends on AIFACTORY-US-181, feature:blueprint-service, feature:workflow-engine-service, feature:run-control-service, feature:tool-adapter-service
Sources model/workflows/vision-to-blueprint.yaml, model/tools/blueprint-submit-version.yaml, model/tools/blueprint-validate.yaml, model/services/template-library/BlueprintService.yaml, model/services/tools-mcp/ToolAdapterService.yaml, model/services/control-plane/RunControlService.yaml, model/scenarios/vision-to-blueprint.yaml

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-924 Bind the blueprint tools to the BlueprintService gRPC methods with their audit fields contract The tool bindings of blueprint-submit-version and blueprint-validate call Blueprints.SubmitDraftVersion and Blueprints.Validate with artifact-v1 and blueprint-version-ref-v1 requests, return blueprint-version-ref-v1 and blueprint-validation-receipt-v1, and write the audit fields of model/tools/blueprint-submit-version.yaml and model/tools/blueprint-validate.yaml; the Validate binding stays sandbox class and writes only the receipt, the move of the version from Draft to Validated being the act of BlueprintService itself when it records ValidationPassed for that exact document hash. ConnectSoft.AI.SoftwareFactory.BlueprintService
AIFACTORY-TASK-925 Gate the blueprint-submit-version invocation on the project policy with an approval bound to its request hash implementation The blueprint-submit-version invocation is classified shared-write, gated by the project policy (BC-20), and executes only with an approval bound to its request hash (which covers the document hash) requested through RunControl.RequestApproval with proposalKind tool-invocation; rejected or expired decisions deny the invocation (ToolInvocationDenied) and the attempt fails policy-denied; without a gating policy the Draft version is written autonomously (D64, ADR-0026). ConnectSoft.AI.SoftwareFactory.ToolAdapterService
AIFACTORY-TASK-926 Fixture Vision Blueprint documents with their expected receipts fixture One fixture document that passes VIS-001 to VIS-004 and one that fails VIS-002, each with its expected blueprint-version-ref-v1 and blueprint-validation-receipt-v1 (passed, findings with rule id, severity and path, documentHash) and the expected version state after the verdict (Validated or Draft), plus a version reference that belongs to another tenant with the expected gRPC status NOT_FOUND, no receipt and an attempt of failure class permanent that is not retried. ConnectSoft.AI.SoftwareFactory.BlueprintService
AIFACTORY-TASK-927 Prove the submit and validate steps on the fixture verification A fixture run proves SCN-vision-to-blueprint-003 and SCN-vision-to-blueprint-004 (AC1 to AC5 of AIFACTORY-US-182), including the idempotent resubmission of the same document hash, the gated path (invocation AwaitingApproval, ApprovalRequested bound to the request hash, write only on the approving decision, ToolInvocationDenied and a policy-denied attempt on rejection or expiry), the Failed path of submit-version with failure class transient retried to exhaustion under its idempotency key documentHash, a Failed attempt of any other failure class not retried, the Uncertain path of submit-version (ToolEffectUncertain, no automatic retry, settled through ConfirmToolEffect, no duplicate version after confirmation), the Validate call writing only the receipt while BlueprintService itself moves the version to Validated when it records ValidationPassed for that exact document hash and leaves it Draft on a failed receipt, a version reference of another tenant answered with the gRPC status NOT_FOUND with no receipt and no state change, the attempt taking failure class permanent without a retry, and a BlueprintValidated with passed false whose receipt is still recorded as a step output. ConnectSoft.AI.SoftwareFactory.WorkflowEngineService

AIFACTORY-US-183: The engine checks the validation receipt and sends findings back to the draft at most twice

behavior · persona requester As a requester, I want a failed validation to send its findings back to the draft a bounded number of times and then fail the run with the report, so that the blueprint improves on real findings without looping forever or hiding the verdict.

The condition step of vision-to-blueprint. When check-valid becomes ready the engine evaluates steps.validate.validation-receipt.passed == true over the recorded receipt; a condition step never retries, never calls a service and completes within PT1M. When the receipt passed, the condition completes with one outcome and store-artifacts becomes ready. When it did not, the engine takes the on_false branch to draft-vision with steps.validate.validation-receipt as feedback: the draft, submit and validate steps re-run in order, the revised document gets its own Draft version and its own receipt, and the iteration count of the run rises by one. The branch is taken at most 2 times; when the receipt is still failed after the last iteration the run fails with the validation report as its evidence, WorkflowRunFailed names check-valid with the failure class validation, Run Control records Failed exactly once and every Draft version created on the way stays a Draft. A missing or unreadable receipt fails the condition with evidence instead of being read as passed (ADR-0026, D61).

Acceptance criteria

AC1 Given steps.validate.validation-receipt is recorded with passed true, when the engine evaluates vision-to-blueprint/check-valid, then the condition completes with exactly one outcome under the run envelope, no service is called and vision-to-blueprint/store-artifacts becomes ready (SCN-vision-to-blueprint-005).
AC2 Given the recorded receipt has passed false and fewer than 2 iterations were counted on the run, when the engine evaluates vision-to-blueprint/check-valid, then it takes the false branch to vision-to-blueprint/draft-vision with the receipt as feedback, the steps vision-to-blueprint/submit-version and vision-to-blueprint/validate re-run on the revised draft, and the iteration count rises by one (SCN-vision-to-blueprint-006).
AC3 Given the receipt is still passed false after the second iteration, when the engine evaluates vision-to-blueprint/check-valid, then the run fails with the validation report as evidence, WorkflowEngineService/WorkflowRunFailed carries check-valid as the failed step with failure class validation, RunControlService/RunFailed is published exactly once and no Draft version is promoted (SCN-vision-to-blueprint-006, ADR-0014).
AC4 Given the receipt is missing, unreadable or the evaluation exceeds its timeout PT1M, when the engine evaluates vision-to-blueprint/check-valid, then the condition is not retried (none, 0 attempts), the step fails with evidence and the run follows the compensation policy of model/workflows/vision-to-blueprint.yaml (SCN-vision-to-blueprint-005, ADR-0026).
Traces: workflows vision-to-blueprint
Traces: steps vision-to-blueprint/check-valid, vision-to-blueprint/draft-vision
Traces: services WorkflowEngineService
Traces: events WorkflowEngineService/StepReady, WorkflowEngineService/WorkflowRunFailed, RunControlService/RunFailed
Traces: descriptors blueprint-validation-receipt-v1
Traces: scenarios SCN-vision-to-blueprint-005, SCN-vision-to-blueprint-006
Traces: adrs ADR-0014, ADR-0026
Traces: requirements FR-08
Depends on AIFACTORY-US-182, feature:workflow-engine-service, feature:run-control-service
Sources model/workflows/vision-to-blueprint.yaml, model/services/agent-mesh/WorkflowEngineService.yaml, model/scenarios/vision-to-blueprint.yaml

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-928 Evaluate check-valid over the recorded receipt and drive the bounded on_false loop implementation The engine evaluates steps.validate.validation-receipt.passed == true from the recorded output without a service call, takes the on_false branch to draft-vision with the receipt as feedback at most 2 times while counting iterations on the run, and fails the run with the report and failure class validation after the limit, exactly as model/workflows/vision-to-blueprint.yaml declares. ConnectSoft.AI.SoftwareFactory.WorkflowEngineService
AIFACTORY-TASK-929 Fixture receipt sequences for the pass, loop and limit paths fixture Recorded receipt sequences (passed true; passed false then true; passed false three times) that drive check-valid through the pass, the single loop and the iteration limit, each with the expected run outcome and iteration count. ConnectSoft.AI.SoftwareFactory.WorkflowEngineService
AIFACTORY-TASK-930 Prove the condition and the bounded loop on the fixture verification A fixture run proves SCN-vision-to-blueprint-005 and SCN-vision-to-blueprint-006 (AC1 to AC4 of AIFACTORY-US-183); one outcome on pass, a loop back with feedback and iteration count on a failed receipt, and WorkflowRunFailed naming check-valid with failure class validation after the second iteration. ConnectSoft.AI.SoftwareFactory.WorkflowEngineService

AIFACTORY-US-184: The validated blueprint is stored with lineage to the assumptions and the prompt and the run completes

behavior · persona requester As a requester, I want the validated Vision Blueprint stored as an artifact with lineage to my prompt and to the assumptions it rests on, so that every later blueprint can be traced back to the brief, the assumptions and the validation that approved it.

The last agent step of vision-to-blueprint. When check-valid held, the engine marks store-artifacts ready and resolves brief from input.prompt, constraints from input.constraints, assumptions from steps.clarify-intent.assumptions, version-ref from steps.submit-version.version-ref and validation-receipt from steps.validate.validation-receipt. The vision-architect release runs the skill vision-architect-store-artifacts in sandbox class with the tools its card allows (knowledge-search, graph-query, list-files, read-range, write-file): it writes the validated blueprint document with write-file inside the isolated workspace, declaring the lineage it rests on (the prompt, the assumptions artifact and the validation receipt) and the validation of the version it was validated as, and returns vision-blueprint as its step output. The skill calls no gRPC method; AgentRuntimeService records that output under the run envelope through Artifacts.Store of ArtifactService with the producer run, attempt and agent and the declared lineage edges, ArtifactService being the one writer of artifacts. The link from the stored blueprint to the validated version is the field validationRef of the Artifact, which references the validation of steps.submit-version.version-ref by the validationReportRef of the validation receipt; no lineage edge is written for the version reference. The step stores the blueprint only, so exactly one new ArtifactStored results (descriptor blueprint-vision-v1): the assumptions artifact that clarify-intent recorded is linked by a lineage edge (inputKind artifact, relation derived-from) and is not stored again, and the prompt, the submission input of the run, is linked by a lineage edge of inputKind run-input (relation derived-from), which the LineageEdge of ArtifactService allows. The run then completes with vision-blueprint and validation-receipt as its outputs and Run Control records exactly one Completed outcome. The step does not submit the validated version for publication and requests no approval. The step declares failure_policy Retry and is of sandbox class, so a Failed attempt of failure class transient is retried under the exponential budget of 3 attempts; an attempt that exceeds its timeout PT30M, fails with any other failure class or exhausts that budget fails with evidence; the validated version and the receipt stay as they are and the run ends Failed with the evidence, recovery not replay (ADR-0014).

Acceptance criteria

AC1 Given vision-to-blueprint/check-valid held, when the engine marks vision-to-blueprint/store-artifacts ready, then brief, constraints, assumptions, version-ref and validation-receipt are resolved from the mappings of model/workflows/vision-to-blueprint.yaml and vision-architect executes the step on its pinned release (SCN-vision-to-blueprint-007).
AC2 Given the step runs, when the skill vision-architect-store-artifacts writes the validated blueprint document with write-file in the workspace and returns it as the step output vision-blueprint, then AgentRuntimeService records that output through ArtifactService/Artifacts.Store with the producer run, attempt and agent, exactly one new ArtifactService/ArtifactStored is emitted (descriptor blueprint-vision-v1, with the producer run and the content hash), the lineage of the blueprint carries edges to the prompt (inputKind run-input, relation derived-from), to the assumptions artifact recorded by vision-to-blueprint/clarify-intent (inputKind artifact, relation derived-from, not stored again) and to the validation receipt (inputKind receipt, relation validated-by), and the field validationRef of the stored ArtifactService/Artifact references the validation of the validated version steps.submit-version.version-ref by the validationReportRef of the receipt, with no lineage edge for the version reference (SCN-vision-to-blueprint-007, FR-08).
AC3 Given the blueprint artifact is stored, when the step completes, then the output vision-blueprint is recorded once under the run envelope, the run outputs vision-blueprint and validation-receipt are set, WorkflowEngineService/WorkflowRunCompleted is emitted once and RunControlService/RunCompleted follows exactly once (ADR-0014).
AC4 Given an attempt of vision-to-blueprint/store-artifacts exceeds its timeout PT30M, settles Failed with a failure class other than transient, or settles Failed with failure class transient until the retry budget of its declared failure_policy Retry (exponential, 3 attempts) is exhausted, when the engine applies the compensation policy of model/workflows/vision-to-blueprint.yaml, then the attempt fails with evidence, the validated version and the receipt stay unchanged, WorkflowEngineService/WorkflowRunFailed names the step and no artifact is written twice on recovery, ArtifactService/Artifacts.Store being idempotent on tenant and hash (SCN-vision-to-blueprint-007, ADR-0014).
Traces: workflows vision-to-blueprint
Traces: steps vision-to-blueprint/store-artifacts, vision-to-blueprint/clarify-intent
Traces: agents vision-architect
Traces: services WorkflowEngineService, AgentRuntimeService, ArtifactService
Traces: aggregates ArtifactService/Artifact
Traces: apis ArtifactService/Artifacts.Store
Traces: events ArtifactService/ArtifactStored, WorkflowEngineService/WorkflowRunCompleted, WorkflowEngineService/WorkflowRunFailed, RunControlService/RunCompleted
Traces: descriptors artifact-v1, blueprint-vision-v1, blueprint-validation-receipt-v1
Traces: scenarios SCN-vision-to-blueprint-007
Traces: adrs ADR-0014
Traces: requirements FR-08, FUX-06
Depends on AIFACTORY-US-183, feature:artifact-service, feature:agent-runtime-service, feature:workflow-engine-service, feature:run-control-service
Sources model/workflows/vision-to-blueprint.yaml, model/agents/vision-planning/vision-architect.yaml, model/skills/vision-planning/vision-architect-store-artifacts.yaml, model/services/knowledge/ArtifactService.yaml, model/services/agent-mesh/AgentRuntimeService.yaml, model/scenarios/vision-to-blueprint.yaml

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-931 Bind the store-artifacts skill and map its output and the run outputs implementation The step store-artifacts of the Draft release runs vision-architect-store-artifacts with the five inputs mapped as in model/workflows/vision-to-blueprint.yaml; the skill writes the validated blueprint document with write-file in the workspace, declares its lineage (the prompt as a run-input edge, the assumptions artifact recorded by clarify-intent as a derived-from edge and the validation receipt as a validated-by edge) and the validation of the validated version for the validationRef field of the artifact, with no lineage edge for the version reference, and returns vision-blueprint (blueprint-vision-v1) as the only step output, the assumptions artifact not being stored again; the run outputs vision-blueprint and validation-receipt are set from the recorded step outputs. ConnectSoft.AI.SoftwareFactory.AgentTemplate
AIFACTORY-TASK-934 Record the store-artifacts step output through Artifacts.Store with its lineage edges implementation The existing runtime path that records step outputs under the run envelope is reused and verified for store-artifacts; the vision-blueprint output is stored through Artifacts.Store with producer run, attempt and agent and the lineage edges the skill declared (prompt as inputKind run-input relation derived-from, assumptions artifact as inputKind artifact relation derived-from, validation receipt as inputKind receipt relation validated-by) and with the validationRef field of the Artifact referencing the validation of the validated version by the validationReportRef of the receipt, no lineage edge being written for the version reference, yielding exactly one new ArtifactStored and no second store of the unchanged assumptions artifact. ConnectSoft.AI.SoftwareFactory.AgentRuntimeService
AIFACTORY-TASK-932 Fixture expected blueprint artifact with its lineage fixture The expected vision-blueprint artifact of the fixture run with its descriptor blueprint-vision-v1, content hash, producer run and lineage edges (the prompt as inputKind run-input, the assumptions artifact recorded by clarify-intent as inputKind artifact relation derived-from, the validation receipt as inputKind receipt relation validated-by), its validationRef referencing the validation of the validated version by the validationReportRef of the receipt, and the expectation of exactly one new ArtifactStored, as the oracle of SCN-vision-to-blueprint-007. ConnectSoft.AI.SoftwareFactory.AgentTemplate
AIFACTORY-TASK-933 Prove the store step and the run completion on the fixture verification A fixture run proves SCN-vision-to-blueprint-007 (AC1 to AC4 of AIFACTORY-US-184); exactly one new ArtifactStored (the blueprint) with the producer run and the lineage edges, the prompt linked by an edge of inputKind run-input, the assumptions artifact linked by a derived-from edge and not stored again, the validation receipt linked by a validated-by edge, the validationRef of the artifact referencing the validation of the validated version with no lineage edge for the version reference, the run outputs vision-blueprint and validation-receipt set, WorkflowRunCompleted and RunCompleted exactly once, and the timeout path ending Failed without a second write on recovery. ConnectSoft.AI.SoftwareFactory.WorkflowEngineService