Skip to content

AIFACTORY-FEAT-112: Workflow definition: Generate a product

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

The workflow definition generate-product as a published asset: Executes an approved generation recipe: reads the recipe and the design inputs it pins, scaffolds every module from its template in the sandbox, fills the backend and, when the module plan has such modules, the frontend and the database, validates by build and test, records the outputs with provenance and proposes the change set under approval. It has 12 steps, names the agents backend-developer, database-engineer, frontend-developer, microservice-generator and the tools build-and-test, get-approved-recipe, propose-change-set, and is executed by WorkflowEngineService under Run Control.

Delivers —
Stubs —
Realizes workflows: generate-product
adrs: ADR-0014, ADR-0024, ADR-0027
Requirements FR-05, FR-06, FR-08, FR-11, FUX-05, FUX-06, XL-09, XL-10
Depends on —
Sources model/workflows/generate-product.yaml

Scenarios to trace (13, catalog): SCN-generate-product-001 ✓, SCN-generate-product-002 ✓, SCN-generate-product-003 ✓, SCN-generate-product-004 ✓, SCN-generate-product-005 ✓, SCN-generate-product-006 ✓, SCN-generate-product-007 ✓, SCN-generate-product-008 ✓, SCN-generate-product-009 ✓, SCN-generate-product-010 ✓, SCN-generate-product-011 ✓, SCN-generate-product-012 ✓, SCN-generate-product-013 ✓

AIFACTORY-US-015: Generation scaffolds the modules and fills them from the design

behavior · persona requester As a requester, I want the approved recipe to be executed: modules scaffolded from their templates and filled with backend, frontend and database code, so that I receive working code that follows my blueprints.

The integration PBI of the definition generate-product. The run is activated by the approved recipe alone: the one required readiness member recipe is satisfied by RecipeApproved of GenerationRecipeService with approvedBy set, and the readiness correlation of WorkflowEngineService 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 recipe version supersedes an open correlation; a newer blueprint version never does, because the run reads every design input through the versions the recipe pins (ADR-0027, D67). After RunAccepted the engine loads the Draft release through AgentRegistryService and runs twelve steps: the read tool get-approved-recipe, the microservice-generator scaffold, a parallel fill with backend-developer always and frontend-developer and database-engineer only when the module plan needs them (D68), the join, the sandbox tool build-and-test, the condition check-build that returns to the fill at most twice, the shared-write provenance step record-outputs, the human step approve-proposal and the shared-write tool propose-change-set. Until I4 the approval of approve-proposal always runs; from I4 the step carries a policy guard and is recorded Skipped when the policy answers allow (D133). The run outputs are generated-outputs and change-proposal. record-outputs records every generated output through the tool record-generated-output, which calls Recipes.RecordOutput of GenerationRecipeService with the tool executor as its caller: the first call moves the recipe from Approved to Executing, and when the run completes the recipe reaches Generated and GenerationCompleted is published (D133); a failed or cancelled run returns an Executing recipe to Approved. propose-change-set opens the pull request through the connection and records it with Pipelines.RecordProposal of PipelineExecutionService (D135). The run reports exactly one outcome within the declared budget. The step behaviour is specified in AIFACTORY-US-016 and AIFACTORY-US-1155 to AIFACTORY-US-1161; this PBI proves the chain on recorded fixtures with and without a user interface module. The tasks AIFACTORY-TASK-221, AIFACTORY-TASK-222 and AIFACTORY-TASK-223 of this PBI moved to AIFACTORY-US-1155, AIFACTORY-US-1158 and AIFACTORY-US-1159, the PBIs whose behaviour they prove; AIFACTORY-TASK-221 changed to a verification in WorkflowEngineService, because the tool binding it once described belongs to feature tool-adapter-service.

Acceptance criteria

AC1 Given the Draft release of generate-product (workflow-definition-v1) with its readiness activation, 12 steps, the when guards of fill-frontend and fill-database, mappings, retry policies, timeouts, failure policies and the approval of generate-product/approve-proposal exactly as in model/workflows/generate-product.yaml, when GenerationRecipeService/RecipeApproved arrives, 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 input recipe, when the run executes, then WorkflowEngineService/WorkflowRunStarted is emitted and generate-product/resolve-recipe, generate-product/scaffold-modules, generate-product/fan-out-fill, generate-product/join-fill, generate-product/build-and-test, generate-product/check-build, generate-product/record-outputs, generate-product/approve-proposal and generate-product/propose-change-set follow in that order, with the fill branches between the fan-out and the join (FR-05, FR-06).
AC3 Given every step succeeds and the Reviewer approves, when the run completes, then generated-outputs (change-set-v1) and change-proposal (pull-request-proposal-v1) are the run outputs, PipelineExecutionService/ChangeProposalOpened names the run, WorkflowEngineService/WorkflowRunCompleted is emitted once, RunControlService/RunCompleted follows exactly once, and the recipe reaches Generated with GenerationRecipeService/GenerationCompleted published once for it (D133, ADR-0014, XL-10).
AC4 Given a step fails terminally, check-build reaches its iteration limit or the approval is rejected or expires, when the engine applies the compensation policy of model/workflows/generate-product.yaml, then WorkflowEngineService/WorkflowRunFailed names the step and the failure class, the sandbox outputs stay as evidence and RunControlService/RunFailed is published exactly once, an Executing recipe returns to Approved and GenerationRecipeService/GenerationCompleted is not published; a failed generate-product/propose-change-set withdraws nothing, because a step's own compensation runs only after its effect is confirmed (D133, AIFACTORY-US-1161).
AC5 Given the recorded fixture recipes of model/workflows/generate-product.yaml with and without a shell module, when the fixture runs execute in the pipeline, then their outputs match the recorded ones field by field, every step output validates against its descriptor and each run stays within the declared budget (ADR-0024).
Traces: workflows generate-product
Traces: steps generate-product/resolve-recipe, generate-product/scaffold-modules, generate-product/fan-out-fill, generate-product/fill-backend, generate-product/fill-frontend, generate-product/fill-database, generate-product/join-fill, generate-product/build-and-test, generate-product/check-build, generate-product/record-outputs, generate-product/approve-proposal, generate-product/propose-change-set
Traces: agents microservice-generator, backend-developer, frontend-developer, database-engineer
Traces: tools get-approved-recipe, build-and-test, record-generated-output, propose-change-set
Traces: services WorkflowEngineService, RunControlService, AgentRegistryService, GenerationRecipeService, PipelineExecutionService
Traces: aggregates WorkflowEngineService/ReadinessCorrelation
Traces: apis RunControlService/SubmitRun
Traces: events GenerationRecipeService/RecipeApproved, GenerationRecipeService/GenerationCompleted, PipelineExecutionService/ChangeProposalOpened, WorkflowEngineService/ReadinessRunSubmitted, WorkflowEngineService/WorkflowRunStarted, WorkflowEngineService/WorkflowRunCompleted, WorkflowEngineService/WorkflowRunFailed, RunControlService/RunAccepted, RunControlService/RunCompleted, RunControlService/RunFailed
Traces: descriptors workflow-definition-v1, readiness-bundle-v1, change-set-v1, pull-request-proposal-v1
Traces: adrs ADR-0014, ADR-0024, ADR-0027
Traces: requirements FR-05, FR-06, FR-08, FR-11, FUX-05, FUX-06, XL-09, XL-10
Depends on AIFACTORY-US-016, AIFACTORY-US-1155, AIFACTORY-US-1156, AIFACTORY-US-1157, AIFACTORY-US-1158, AIFACTORY-US-1159, AIFACTORY-US-1160, AIFACTORY-US-1161, feature:workflow-engine-service, feature:run-control-service, feature:agent-registry-service-thin, feature:generation-recipe-service, feature:pipeline-execution-service-thin, feature:wf-module-blueprints, feature:wf-application-design, feature:wf-database-blueprint
Sources model/workflows/generate-product.yaml, model/agents/engineering/microservice-generator.yaml, docs/planes/agent-runtime/workflow-definitions/generate-product.md, docs/architecture/adr/0027-generation-input-contract.md

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-181 Author the release of the workflow definition generate-product from the model implementation A Draft release of generate-product (workflow-definition-v1) with its readiness activation on RecipeApproved, its 12 steps, input mappings, the when guards of fill-frontend and fill-database, retry policies, timeouts, the failure policies (Retry on the agent and tool steps, Fail on approve-proposal, Compensate on propose-change-set), the shared-write class and idempotency_key runId + recipeId + changeSetHash of record-outputs, the approval block and the policy guard from I4 of approve-proposal, the on_false loop of check-build, the compensation of propose-change-set and the budget exactly as in model/workflows/generate-product.yaml; loadable by AgentRegistryService and accepted by ValidateWorkflowDefinition of WorkflowEngineService. ConnectSoft.AI.SoftwareFactory.WorkflowEngineService
AIFACTORY-TASK-182 Author the agent releases backend-developer, database-engineer, frontend-developer, microservice-generator with their prompts and skills implementation Draft releases of microservice-generator, backend-developer, frontend-developer and database-engineer with their instructions, the skills microservice-generator-template-assembly, microservice-generator-record-outputs, backend-developer-use-case-implementation, frontend-developer-fill-frontend and database-engineer-mappings-and-migrations among their bound skills, the tool bindings and the model profiles of their cards; each release passes a smoke evaluation of the suite engineering-core-v1 on the fixture recipe. ConnectSoft.AI.SoftwareFactory.AgentTemplate
AIFACTORY-TASK-183 Fixture run of generate-product against recorded inputs verification The definition runs end to end on two fixture recipes, one with a shell module and one without, from RecipeApproved to RunCompleted with a fixture Reviewer decision; every step output validates against its descriptor and the outputs generated-outputs and change-proposal match the recorded ones field by field (AC1 to AC3 and AC5 of AIFACTORY-US-015). ConnectSoft.AI.SoftwareFactory.WorkflowEngineService
AIFACTORY-TASK-727 Verify generate-and-fill by running the declared command verification Run dotnet test -c Release --filter Category=WorkflowFixture; it passes and proves AC1 to AC5 of AIFACTORY-US-015, including GenerationCompleted once on a completed run and the failure path of AC4 with WorkflowRunFailed and RunFailed exactly once, the recipe back in Approved and no withdrawal after a failed proposal. ConnectSoft.AI.SoftwareFactory.WorkflowEngineService

AIFACTORY-US-1155: The run reads the approved recipe and resolves every design input it pins

behavior · persona requester As a requester, I want the generation run to read my approved recipe and every blueprint and design version it pins, and nothing else, so that the code is generated from exactly the versions that were approved.

The first step of generate-product, the read-class tool get-approved-recipe. When the engine marks resolve-recipe ready it resolves recipe from bundle.recipe, the recipe id and version that satisfied the readiness member, and Run Control dispatches the attempt; ToolAdapterService executes the tool under the run's workload identity and the tool calls Recipes.GetApprovedRecipe of GenerationRecipeService, whose behaviour that feature delivers. The step declares seven outputs recorded once under the run envelope: module-plan with the counts by module kind, among them frontendModules and persistenceModules, and, per module, the pinned module-blueprints, application-designs, domain-model, database-blueprints, frontend-blueprints and ux-blueprint versions, each by id, version and hash. The generation-recipe-service feature reports the gap between them and the call: Recipes.GetApprovedRecipe takes execution-scope-v1, which names no recipe, and answers one artifact-v1 reference to the recipe document, not seven typed outputs, and the model names no component that maps the document onto the seven outputs; this PBI states the outputs the definition declares and reports the mapping component to the owner. That an input the plan does not need, such as the Frontend and UX Blueprints of a plan without a shell or microfrontend module, is recorded empty is an assumption of this PBI, because no model text says how such an output is recorded, and it is reported as well. The read writes nothing and is audited with recipeId, recipeVersion, projectId, modules and pinnedInputs. A recipe that is not Approved or Executing is answered FailedPrecondition and a recipe of another tenant NOT_FOUND like an unknown one; both are permanent and not retried, and the run fails before any sandbox work. The step declares failure_policy Retry, so a Failed attempt of failure class transient is retried under the fixed budget of 2 attempts with backoff 10s; an attempt that exceeds PT2M or exhausts the budget fails the run with evidence and the recipe stays Approved.

Acceptance criteria

AC1 Given a run accepted for an Approved recipe, when generate-product/resolve-recipe runs get-approved-recipe through GenerationRecipeService/Recipes.GetApprovedRecipe, then module-plan with the counts by module kind and the pinned module-blueprints, application-designs, domain-model, database-blueprints, frontend-blueprints and ux-blueprint are recorded once under the run envelope, each pin naming id, version and hash (SCN-generate-product-001, ADR-0027).
AC2 Given a recipe plan without a shell or microfrontend module, when the step records its outputs, then frontendModules is zero and no blueprint outside the recipe's pins is read; that frontend-blueprints and ux-blueprint are then recorded empty is the assumption of this PBI pending the owner, as is the component that maps the artifact-v1 reply of GenerationRecipeService/Recipes.GetApprovedRecipe onto the seven outputs (SCN-generate-product-001).
AC3 Given a recipe of another tenant, or a GenerationRecipeService/GenerationRecipe that is neither Approved nor Executing, when the tool calls GenerationRecipeService/Recipes.GetApprovedRecipe, then the answer is NOT_FOUND or FailedPrecondition, the attempt takes failure class permanent without a retry and WorkflowEngineService/WorkflowRunFailed names the step before any sandbox work (SCN-generate-product-001, ADR-0015).
AC4 Given an attempt settles Failed with failure class transient until the fixed budget of 2 attempts is spent or exceeds PT2M, when Run Control evaluates the step, then it is retried under that budget, then fails with evidence, and the recipe stays Approved (SCN-generate-product-001, ADR-0014).
Traces: workflows generate-product
Traces: steps generate-product/resolve-recipe
Traces: tools get-approved-recipe
Traces: services GenerationRecipeService, ToolAdapterService, WorkflowEngineService
Traces: aggregates GenerationRecipeService/GenerationRecipe
Traces: apis GenerationRecipeService/Recipes.GetApprovedRecipe
Traces: events WorkflowEngineService/WorkflowRunFailed
Traces: descriptors artifact-v1, blueprint-module-v1, application-design-v1, blueprint-database-v1, blueprint-frontend-v1, blueprint-ux-v1
Traces: scenarios SCN-generate-product-001
Traces: adrs ADR-0014, ADR-0015, ADR-0027
Traces: requirements FR-05
Depends on feature:generation-recipe-service, feature:tool-adapter-service, feature:workflow-engine-service, feature:run-control-service
Sources model/workflows/generate-product.yaml, model/tools/get-approved-recipe.yaml, model/services/template-library/GenerationRecipeService.yaml, model/scenarios/generate-product.yaml

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-221 Verify that resolve-recipe consumes the get-approved-recipe binding of the tool feature verification A check of the release authored by AIFACTORY-TASK-181 proves that the step resolve-recipe calls the get-approved-recipe binding that feature tool-adapter-service delivers, with recipe mapped from bundle.recipe, side_effect_class read, the fixed retry of 2 attempts and timeout PT2M, and records the outputs module-plan, module-blueprints, application-designs, domain-model, database-blueprints, frontend-blueprints and ux-blueprint under the descriptors model/workflows/generate-product.yaml declares; the binding is not re-implemented here and the component that maps the recipe document onto these outputs stays pending the owner. ConnectSoft.AI.SoftwareFactory.WorkflowEngineService
AIFACTORY-TASK-4592 Fixture recipes with and without a user interface module fixture Two fixture Approved recipes, one with a backend module with persistence and a shell module and one with a backend module only, each with its recipe document and the expected seven resolve-recipe outputs, plus a recipe of another tenant and a Draft recipe with their expected refusals, as the oracle of SCN-generate-product-001. ConnectSoft.AI.SoftwareFactory.GenerationRecipeService
AIFACTORY-TASK-4593 Prove the recipe resolution step on the fixture verification A fixture run proves SCN-generate-product-001 (AC1 to AC4 of AIFACTORY-US-1155); the seven outputs match the pins, the plan without a shell records frontendModules zero with empty frontend inputs as assumed pending the owner, NOT_FOUND and FailedPrecondition fail the run without a retry, and the transient path is retried twice and then fails. ConnectSoft.AI.SoftwareFactory.WorkflowEngineService

AIFACTORY-US-1156: The Microservice Generator scaffolds every module from its pinned template version in the sandbox

behavior · persona requester As a requester, I want every module of the plan created from the template version and switches the recipe pins, inside the sandbox, so that the generated solution starts from the same scaffold every time and nothing reaches a shared repository unreviewed.

The sandbox-class agent step scaffold-modules of generate-product. When resolve-recipe succeeded the engine marks it ready and resolves recipe from input.recipe, module-blueprint from steps.resolve-recipe.module-blueprints, module-plan from steps.resolve-recipe.module-plan and manifests from the optional input input.manifests. The microservice-generator release runs the skill microservice-generator-template-assembly with the sandbox tools of its card (shell-sandbox, write-file, apply-patch, build-and-test among them): one module at a time it runs the template id and version the module entry names with the switches and parameters the recipe pins, at the path of the repository layout, and returns scaffold (change-set-v1) with every created file, its change kind and the hash of the change set; nothing is pushed. A module is never scaffolded from another template version than its pin. The step writes nothing outside the isolated workspace and needs no approval. It declares failure_policy Retry: a Failed attempt of failure class transient is retried under the exponential budget of 3 attempts with backoff 30s, another failure class is not retried, and an attempt that exceeds PT30M or exhausts the budget fails the run with evidence; the workspace stays as evidence and the recipe stays Approved, because it leaves Approved only on the first Recipes.RecordOutput of the run, which comes after this step (ADR-0014, recovery not replay).

Acceptance criteria

AC1 Given module-plan and module-blueprints are recorded, when microservice-generator executes generate-product/scaffold-modules with microservice-generator-template-assembly, then every module of the plan is created from its pinned template id and version with the recipe's switches and parameters at its path, and scaffold (change-set-v1) is recorded once under the run envelope (SCN-generate-product-002, FR-05).
AC2 Given the scaffold is recorded, when the change set is inspected, then it lists every created file with its change kind and carries its hash, and no branch was pushed and no shared system was written (SCN-generate-product-002, ADR-0027).
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 compensation policy of model/workflows/generate-product.yaml, then the attempt fails with evidence, WorkflowEngineService/WorkflowRunFailed names the step and the workspace stays as evidence (SCN-generate-product-002, ADR-0014).
Traces: workflows generate-product
Traces: steps generate-product/scaffold-modules
Traces: agents microservice-generator
Traces: tools shell-sandbox, write-file, apply-patch
Traces: services WorkflowEngineService, AgentRuntimeService
Traces: events WorkflowEngineService/StepReady, WorkflowEngineService/WorkflowRunFailed
Traces: descriptors artifact-v1, blueprint-module-v1, change-set-v1
Traces: scenarios SCN-generate-product-002
Traces: adrs ADR-0014, ADR-0027
Traces: requirements FR-05, FR-06
Depends on AIFACTORY-US-1155, feature:agent-runtime-service, feature:workflow-engine-service, feature:run-control-service
Sources model/workflows/generate-product.yaml, model/skills/engineering/microservice-generator-template-assembly.yaml, model/scenarios/generate-product.yaml

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-4594 Verify the template assembly skill binding of the scaffold step verification A check of the microservice-generator release authored by AIFACTORY-TASK-182 and of the step scaffold-modules of the release authored by AIFACTORY-TASK-181 against model/workflows/generate-product.yaml proves the skill microservice-generator-template-assembly with only the sandbox tools of the skill, side_effect_class sandbox, the exponential retry of 3 attempts with backoff 30s, timeout PT30M and the mappings recipe from input.recipe, module-blueprint from steps.resolve-recipe.module-blueprints, module-plan from steps.resolve-recipe.module-plan and manifests from input.manifests; nothing is authored here. ConnectSoft.AI.SoftwareFactory.AgentTemplate
AIFACTORY-TASK-4595 Fixture scaffolds of the fixture recipes fixture The expected scaffold change sets (change-set-v1) of the two fixture recipes, with every created file, its change kind and the change-set hash, as the oracle of SCN-generate-product-002. ConnectSoft.AI.SoftwareFactory.AgentTemplate
AIFACTORY-TASK-4596 Prove the scaffold step on the fixture verification A fixture run proves SCN-generate-product-002 (AC1 to AC3 of AIFACTORY-US-1156); every module is created from its pinned template version with the recipe's switches, nothing is pushed, and the timeout path ends in WorkflowRunFailed with the workspace kept. ConnectSoft.AI.SoftwareFactory.WorkflowEngineService

AIFACTORY-US-1157: The engine runs the fill branches in parallel on the scaffold and joins them, Skipped branches counting as satisfied

behavior · persona requester As a requester, I want backend, frontend and database work done in parallel on the scaffold and joined into one result, so that generation is not serialized, and a branch my product does not need does not block it.

The two parallel steps of generate-product, which the engine evaluates without an agent, a tool or a retry. When scaffold-modules succeeded the engine evaluates fan-out-fill and makes the three branches ready on the scaffold: fill-backend, and fill-frontend and fill-database subject to their when guards; a branch whose guard does not hold is recorded Skipped by the engine at that moment, a state the Step of RunControlService names, and dispatches no attempt (ADR-0027, D68). The fan-out completes with exactly one outcome within PT1M. On a pass back from check-build the fan-out runs again with steps.build-and-test.validation-results as feedback for the branches that run. When join-fill becomes ready it waits for every branch that ran; a Skipped branch counts as satisfied. When every branch that ran succeeded the join completes with one outcome and build-and-test becomes ready; when one branch failed the join fails the run with that branch's evidence while the change sets of the other branches stay recorded as artifacts under the run envelope. 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 scaffold is recorded and the module plan has frontend and persistence modules, when the engine evaluates generate-product/fan-out-fill, then generate-product/fill-backend, generate-product/fill-frontend and generate-product/fill-database become ready in parallel and the fan-out records exactly one outcome (SCN-generate-product-003, ADR-0027).
AC2 Given the plan has no frontend module, when the engine evaluates generate-product/fan-out-fill, then generate-product/fill-frontend is recorded Skipped without an attempt and the other branches run (SCN-generate-product-003).
AC3 Given every branch that ran succeeded and the others are Skipped, when the engine evaluates generate-product/join-fill, then the join completes with one outcome and generate-product/build-and-test becomes ready (SCN-generate-product-007).
AC4 Given one branch failed, or the fan-out or the join exceeds PT1M, when generate-product/join-fill is reached, then WorkflowEngineService/WorkflowRunFailed names the failed step, the change sets of the other branches stay recorded and no step is retried (SCN-generate-product-007, ADR-0014).
Traces: workflows generate-product
Traces: steps generate-product/fan-out-fill, generate-product/join-fill, generate-product/fill-backend, generate-product/fill-frontend, generate-product/fill-database
Traces: services WorkflowEngineService, RunControlService
Traces: aggregates WorkflowEngineService/WorkflowRun, RunControlService/Step
Traces: events WorkflowEngineService/StepReady, WorkflowEngineService/StepRunStateChanged, WorkflowEngineService/WorkflowRunFailed
Traces: descriptors change-set-v1
Traces: scenarios SCN-generate-product-003, SCN-generate-product-007
Traces: adrs ADR-0014, ADR-0027
Traces: requirements FR-06
Depends on AIFACTORY-US-1156, feature:workflow-engine-service, feature:run-control-service
Sources model/workflows/generate-product.yaml, model/services/agent-mesh/WorkflowEngineService.yaml, docs/architecture/adr/0027-generation-input-contract.md, model/scenarios/generate-product.yaml

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-4597 Verify the fill fan-out, the join and the guards of the Draft release against the definition verification A check of the release authored by AIFACTORY-TASK-181 against model/workflows/generate-product.yaml proves that fan-out-fill and join-fill carry kind parallel, side_effect_class sandbox, timeout PT1M and no retry, that fill-backend, fill-frontend and fill-database depend on fan-out-fill and join-fill on all three, and that fill-frontend carries the when guard steps.resolve-recipe.module-plan.frontendModules > 0 and fill-database steps.resolve-recipe.module-plan.persistenceModules > 0; recording a guarded branch Skipped is engine behaviour of feature workflow-engine-service and nothing is authored here. ConnectSoft.AI.SoftwareFactory.WorkflowEngineService
AIFACTORY-TASK-4598 Fixture branch outcomes for the join fixture Recorded branch outcomes (all three succeeded; frontend Skipped; database branch failed) with the expected join outcome and the change sets that stay recorded, as the oracle of SCN-generate-product-003 and SCN-generate-product-007. ConnectSoft.AI.SoftwareFactory.WorkflowEngineService
AIFACTORY-TASK-4599 Prove the fan-out and the join on the fixture verification A fixture run proves SCN-generate-product-003 and SCN-generate-product-007 (AC1 to AC4 of AIFACTORY-US-1157); parallel branches, a Skipped branch counted as satisfied, and one failed branch failing the run with the other change sets kept. ConnectSoft.AI.SoftwareFactory.WorkflowEngineService

AIFACTORY-US-1158: The Backend Developer fills handlers, DTOs, validation, authorization and tenant enforcement from the application design

behavior · persona requester As a requester, I want the backend of every module filled with one handler per use case of its application design, with validation, authorization and tenant enforcement, so that the generated service does what its design says and nothing the design does not name.

The unguarded fill branch fill-backend of generate-product. When the fan-out makes it ready the engine resolves application-design from steps.resolve-recipe.application-designs, module-code from steps.scaffold-modules.scaffold and module-blueprint from steps.resolve-recipe.module-blueprints; on a pass back from check-build the validation results are attached as feedback. The backend-developer release runs the skill backend-developer-use-case-implementation in sandbox class with the tools of its card: for every use case of the pinned application design it implements the handler on its input port, the DTOs, the validation, the authorization the use case names and the tenant enforcement of a tenant-scoped use case, wires the output ports to the adapters the design names, and returns backend-change-set (change-set-v1) over the scaffold. A use case without a handler or a handler without a use case is an error of the output; on a feedback pass the change set addresses every failing build or test of the results. The step writes only inside the isolated workspace and needs no approval. It declares failure_policy Retry: a Failed attempt of failure class transient is retried under the exponential budget of 3 attempts with backoff 30s, another failure class is not retried, and an attempt that exceeds PT30M or exhausts the budget fails its branch with evidence, which join-fill turns into a failed run.

Acceptance criteria

AC1 Given the pinned application design and the scaffold are recorded, when backend-developer executes generate-product/fill-backend, then backend-change-set (change-set-v1) holds one handler per use case of the application-design-v1 body with its DTOs, validation, authorization and tenant enforcement, and is recorded once under the run envelope (SCN-generate-product-004, FR-06).
AC2 Given a pass back from generate-product/check-build, when the step re-runs, then the validation results are in its context as feedback and the new change set addresses each failing build or test they name (SCN-generate-product-004).
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/generate-product.yaml, then the branch fails with evidence, the workspace stays as evidence and no shared system is changed (SCN-generate-product-004, ADR-0014).
Traces: workflows generate-product
Traces: steps generate-product/fill-backend
Traces: agents backend-developer
Traces: services WorkflowEngineService
Traces: descriptors application-design-v1, blueprint-module-v1, change-set-v1
Traces: scenarios SCN-generate-product-004
Traces: adrs ADR-0014, ADR-0027
Traces: requirements FR-06
Depends on AIFACTORY-US-1157, feature:workflow-engine-service, feature:run-control-service, feature:agent-runtime-service
Sources model/workflows/generate-product.yaml, model/skills/engineering/backend-developer-use-case-implementation.yaml, docs/reference/schemas/application-design.schema.json, model/scenarios/generate-product.yaml

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-222 Backend developer release bound to the fill-backend step implementation The step fill-backend of the release authored by AIFACTORY-TASK-181 runs backend-developer-use-case-implementation with application-design, module-code and module-blueprint mapped as in model/workflows/generate-product.yaml; on the fixture recipe the release produces a backend change set with one handler per use case of the pinned application design. ConnectSoft.AI.SoftwareFactory.AgentTemplate
AIFACTORY-TASK-4600 Fixture backend change set and a feedback pass fixture The expected backend-change-set (change-set-v1) for the fixture application design, and a feedback fixture whose validation results name a failing test together with the change set that fixes it, as the oracle of SCN-generate-product-004. ConnectSoft.AI.SoftwareFactory.AgentTemplate
AIFACTORY-TASK-4601 Prove the backend fill on the fixture verification A fixture run proves SCN-generate-product-004 (AC1 to AC3 of AIFACTORY-US-1158); one handler per use case, the feedback pass fixing the named test, and the timeout path failing the branch with the workspace kept. ConnectSoft.AI.SoftwareFactory.WorkflowEngineService

AIFACTORY-US-1159: The frontend and database branches fill the modules only when the module plan has such modules, otherwise they are Skipped

behavior · persona requester As a requester, I want screens and clients generated only when my product has a shell or microfrontend, and mappings and migrations only when it has persistence, so that a backend-only product is generated without inventing a user interface or a database.

The two guarded fill branches of generate-product (ADR-0027, D68). fill-frontend carries the guard steps.resolve-recipe.module-plan.frontendModules > 0: when it holds the engine resolves ux-blueprint, frontend-blueprint from steps.resolve-recipe.frontend-blueprints and module-code from the scaffold, and the frontend-developer release runs frontend-developer-fill-frontend, producing the screens, components and API clients from the UX Blueprint and the API contracts as frontend-change-set (change-set-v1). fill-database carries the guard steps.resolve-recipe.module-plan.persistenceModules > 0: when it holds the engine resolves domain-model, database-blueprint from steps.resolve-recipe.database-blueprints and module-code, and the database-engineer release runs database-engineer-mappings-and-migrations, producing the mappings, migrations and seeds from the domain model and the Database Blueprint, with TenantId on every tenant table, as database-change-set (change-set-v1). When a guard does not hold the engine records the step Skipped, dispatches no attempt and records no change set, and the join counts it as satisfied. Both steps are sandbox class, write only inside the isolated workspace and need no approval; each declares failure_policy Retry with the exponential budget of 3 attempts and backoff 30s for a Failed attempt of failure class transient, and an attempt that exceeds PT30M, fails with another failure class or exhausts the budget fails its branch with evidence.

Acceptance criteria

AC1 Given the module plan has a shell or microfrontend module, when frontend-developer executes generate-product/fill-frontend, then frontend-change-set (change-set-v1) holds the screens, components and clients the pinned UX and Frontend Blueprints name and is recorded once (SCN-generate-product-005, FUX-05, FUX-06).
AC2 Given the module plan has a module with persistence, when database-engineer executes generate-product/fill-database, then database-change-set (change-set-v1) holds the mappings, migrations and seeds of the pinned Database Blueprint and domain model with TenantId on every tenant table, and is recorded once (SCN-generate-product-006).
AC3 Given the module plan has no frontend module or no persistence module, when the fan-out reaches generate-product/fill-frontend or generate-product/fill-database, then that step is recorded Skipped without an attempt or a change set and WorkflowEngineService/StepRunStateChanged shows Skipped (SCN-generate-product-005, SCN-generate-product-006, ADR-0027).
AC4 Given an attempt of either step 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/generate-product.yaml, then the branch fails with evidence and no shared system is changed (SCN-generate-product-005, SCN-generate-product-006, ADR-0014).
Traces: workflows generate-product
Traces: steps generate-product/fill-frontend, generate-product/fill-database
Traces: agents frontend-developer, database-engineer
Traces: services WorkflowEngineService
Traces: events WorkflowEngineService/StepRunStateChanged
Traces: descriptors blueprint-ux-v1, blueprint-frontend-v1, blueprint-database-v1, artifact-v1, change-set-v1
Traces: scenarios SCN-generate-product-005, SCN-generate-product-006
Traces: adrs ADR-0014, ADR-0027
Traces: requirements FR-06, FUX-05, FUX-06
Depends on AIFACTORY-US-1157, feature:workflow-engine-service, feature:run-control-service, feature:agent-runtime-service
Sources model/workflows/generate-product.yaml, model/skills/engineering/frontend-developer-fill-frontend.yaml, model/skills/engineering/database-engineer-mappings-and-migrations.yaml, model/scenarios/generate-product.yaml

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-4602 Verify the frontend and database skill bindings of the guarded steps verification A check of the frontend-developer and database-engineer releases authored by AIFACTORY-TASK-182 and of the steps fill-frontend and fill-database of the release authored by AIFACTORY-TASK-181 against model/workflows/generate-product.yaml proves the skills frontend-developer-fill-frontend and database-engineer-mappings-and-migrations, side_effect_class sandbox, the exponential retry of 3 attempts with backoff 30s, timeout PT30M and the mappings of ux-blueprint, frontend-blueprint, domain-model, database-blueprint and module-code; nothing is authored here. ConnectSoft.AI.SoftwareFactory.AgentTemplate
AIFACTORY-TASK-4603 Fixture frontend and database change sets fixture The expected frontend-change-set and database-change-set (change-set-v1) for the fixture recipe with a shell module and persistence, as the oracle of SCN-generate-product-005 and SCN-generate-product-006. ConnectSoft.AI.SoftwareFactory.AgentTemplate
AIFACTORY-TASK-223 Fixture runs with and without a user interface module verification Both fixture recipes end the fill stage and prove SCN-generate-product-005 and SCN-generate-product-006 (AC1 to AC4 of AIFACTORY-US-1159); the first produces frontend and database change sets, the second records fill-frontend Skipped without an attempt and the join continues. ConnectSoft.AI.SoftwareFactory.WorkflowEngineService

AIFACTORY-US-016: Generated code is built, tested and recorded with provenance

behavior · persona requester As a requester, I want the generated modules to be built and tested in the sandbox and their provenance recorded, so that I only ever review code that compiles and passes its tests.

The validation and provenance steps of generate-product. When the join succeeded the engine marks build-and-test ready and resolves the backend, frontend and database change sets of the branches that ran; a Skipped branch contributes no change set. ToolAdapterService executes the sandbox-class tool build-and-test, which restores, compiles and runs the generated tests in the sandbox and returns validation-results (artifact-v1) with passed and the result per module, audited with workspace, command, exitCode and reportRef. A failing build or test is a successful step output with passed false, not a step failure. The step declares failure_policy Retry under the fixed budget of 3 attempts with backoff 10s and PT45M. The condition check-build evaluates steps.build-and-test.validation-results.passed == true without a service call or a retry; when it does not hold the engine returns to fan-out-fill with the results as feedback, at most 2 times, and then fails the run with the evidence and failure class validation. When it holds, record-outputs runs in shared-write class on the microservice-generator release with microservice-generator-record-outputs: from the change sets of the branches that ran and the validation results it assembles generated-outputs (change-set-v1) and provenance (artifact-v1), every generated module with its recipe version, template version, manifest hash, run, attempt, agent release and file hashes, and both are recorded once under the run envelope. The skill records them through the tool record-generated-output: ToolAdapterService, the tool executor, calls Recipes.RecordOutput of GenerationRecipeService with its workload identity and the scope factory.recipes.write, so one GeneratedOutput and one GeneratedOutputRecorded exist per module, the first call of the run moves the recipe from Approved to Executing, and when the run completes the recipe reaches Generated and GenerationCompleted is published (D133). The step declares idempotency_key runId + recipeId + changeSetHash and the call is idempotent on the same three values, so its failure_policy Retry with the exponential budget of 3 attempts, backoff 30s and PT30M holds for a shared-write step (D114) and a retried attempt records nothing twice; an Uncertain attempt is never retried automatically and waits for an operator decision of the project (D119). A run that fails after a recorded output keeps the recorded provenance as evidence and returns the Executing recipe to Approved. The tasks AIFACTORY-TASK-224 and AIFACTORY-TASK-225 of this PBI are verifications in WorkflowEngineService of the step mappings; the build-and-test and record-generated-output bindings themselves belong to feature tool-adapter-service and the RecordOutput handler to feature generation-recipe-service.

Acceptance criteria

AC1 Given the change sets of the branches that ran, when generate-product/build-and-test runs build-and-test, then validation-results with passed and the result per module is recorded once whether the build passed or not, and a Skipped branch contributes no change set (SCN-generate-product-008).
AC2 Given passed true, when the engine evaluates generate-product/check-build, then it completes with one outcome and generate-product/record-outputs becomes ready; given passed false and fewer than 2 iterations, then the engine returns to generate-product/fan-out-fill with the results as feedback and counts the iteration (SCN-generate-product-009, SCN-generate-product-010).
AC3 Given passed is still false after the second iteration, or the results are missing, when the engine evaluates generate-product/check-build, then WorkflowEngineService/WorkflowRunFailed names check-build with the evidence, RunControlService/RunFailed is published once and nothing leaves the sandbox (SCN-generate-product-010, ADR-0014).
AC4 Given the build passed, when microservice-generator executes generate-product/record-outputs with microservice-generator-record-outputs, then generated-outputs (change-set-v1) and provenance (artifact-v1) are recorded once under the run envelope, listing every generated module with its hash, template version, recipe version and run; the tool record-generated-output calls GenerationRecipeService/Recipes.RecordOutput, one GenerationRecipeService/GeneratedOutput and one GenerationRecipeService/GeneratedOutputRecorded exist per module and the GenerationRecipeService/GenerationRecipe moves from Approved to Executing (SCN-generate-product-011, D133, XL-10).
AC5 Given an attempt of generate-product/record-outputs settles Failed with failure class transient, when Run Control evaluates it, then it is retried under its budget because the step declares its idempotency key, and a repeated GenerationRecipeService/Recipes.RecordOutput for the same run, recipe and change-set hash records nothing new; given an attempt of generate-product/build-and-test or generate-product/record-outputs exceeds its timeout or exhausts its retry budget, then the step fails with evidence, the run ends Failed with the sandbox outputs and any recorded provenance kept, the recipe returns to Approved, nothing is proposed and GenerationRecipeService/GenerationCompleted is never published for the run (SCN-generate-product-008, SCN-generate-product-011, D114).
Traces: workflows generate-product
Traces: steps generate-product/build-and-test, generate-product/check-build, generate-product/fan-out-fill, generate-product/record-outputs
Traces: tools build-and-test, record-generated-output
Traces: agents microservice-generator
Traces: services GenerationRecipeService, ToolAdapterService, WorkflowEngineService
Traces: aggregates GenerationRecipeService/GeneratedOutput, GenerationRecipeService/GenerationRecipe
Traces: apis GenerationRecipeService/Recipes.RecordOutput
Traces: events GenerationRecipeService/GeneratedOutputRecorded, GenerationRecipeService/GenerationCompleted, WorkflowEngineService/WorkflowRunFailed, RunControlService/RunFailed
Traces: descriptors change-set-v1, artifact-v1
Traces: scenarios SCN-generate-product-008, SCN-generate-product-009, SCN-generate-product-010, SCN-generate-product-011
Traces: adrs ADR-0014, ADR-0027
Traces: requirements FR-08, XL-10
Depends on AIFACTORY-US-1157, AIFACTORY-US-1158, AIFACTORY-US-1159, feature:generation-recipe-service, feature:tool-adapter-service, feature:workflow-engine-service, feature:run-control-service
Sources model/workflows/generate-product.yaml, model/tools/build-and-test.yaml, model/tools/record-generated-output.yaml, model/skills/engineering/microservice-generator-record-outputs.yaml, model/services/template-library/GenerationRecipeService.yaml, model/scenarios/generate-product.yaml

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-224 Verify that build-and-test consumes the binding of the tool feature verification A check of the release authored by AIFACTORY-TASK-181 proves that the step build-and-test calls the build-and-test binding that feature tool-adapter-service delivers, with backend-change-set, frontend-change-set and database-change-set mapped from steps.fill-backend, steps.fill-frontend and steps.fill-database and a Skipped branch mapping no change set, side_effect_class sandbox, the fixed retry of 3 attempts with backoff 10s and timeout PT45M, and records validation-results (artifact-v1) once; a fixture with a failing test shows passed false on a succeeded step (SCN-generate-product-008). The binding is not re-implemented here. ConnectSoft.AI.SoftwareFactory.WorkflowEngineService
AIFACTORY-TASK-225 Verify the mappings and outputs of the record-outputs step verification A check of the release authored by AIFACTORY-TASK-181 against model/workflows/generate-product.yaml proves that the step record-outputs runs microservice-generator-record-outputs on microservice-generator in side_effect_class shared-write with idempotency_key runId + recipeId + changeSetHash and recipe, module-blueprint, backend-change-set, frontend-change-set, database-change-set and validation-results mapped as declared, records generated-outputs (change-set-v1) and provenance (artifact-v1) once under the run envelope, and reaches Recipes.RecordOutput only through the record-generated-output binding of feature tool-adapter-service, one call per module and none repeated on a retry (SCN-generate-product-011). ConnectSoft.AI.SoftwareFactory.WorkflowEngineService
AIFACTORY-TASK-4604 Fixture validation results for the pass, loop and limit paths of check-build fixture Recorded validation results (passed; failed then passed; failed three times) that drive check-build through the pass, a return to fan-out-fill with feedback and the iteration limit, each with the expected run outcome, as the oracle of SCN-generate-product-009 and SCN-generate-product-010. ConnectSoft.AI.SoftwareFactory.WorkflowEngineService
AIFACTORY-TASK-728 Verify build-test-record by running the declared command verification Run dotnet test -c Release --filter Category=WorkflowFixture; it passes and proves AC1 to AC5 of AIFACTORY-US-016 and SCN-generate-product-008 to SCN-generate-product-011, including the loop back to the fill with the results as feedback, the failed run after the second iteration, one GeneratedOutputRecorded per module with the recipe in Executing, and a retried record-outputs attempt that records nothing twice. ConnectSoft.AI.SoftwareFactory.WorkflowEngineService

AIFACTORY-US-1160: A Reviewer approves the exact generated change set of the run before anything is proposed

behavior · persona reviewer As a reviewer, I want to approve the exact generated change set of a run before it becomes a pull request in the system of record, so that nothing generated reaches a shared repository without a decision bound to what I saw.

The Human step approve-proposal of generate-product. When record-outputs succeeded the engine marks it ready; it has no task contract, and Run Control opens an ApprovalRequest of kind approval whose subject is the run and the step approve-proposal, with action class shared-write, proposal kind diff and the proposal hash of steps.record-outputs.generated-outputs, and publishes ApprovalRequested; the run waits WaitingForApproval and the engine's projection WaitingForHuman. Eligibility is role Reviewer in project scope and the requester of the run never decides (D18). A decision authorizes exactly that hash; a regenerated change set makes the pending request Stale, which never advances the run. An approving ApprovalDecided resumes the run and propose-change-set becomes ready (AIFACTORY-US-1161). The step has timeout P7D and failure_policy Fail: a rejected request, or an expired one, which fails while no approval rule is supplied (D115), fails the run with failure class policy-denied and nothing is proposed. A request still Pending when the run is cancelled or fails ends Cancelled, as RunControlService states, and nothing is proposed. Until I4 the approval always runs, whatever the project policy says about autonomous proposals (D133). From I4 the step carries a policy guard of action kind tool-invocation and class shared-write over steps.record-outputs.generated-outputs: the engine asks PolicyEngineService before it emits StepReady, and an answer allow records the step run Skipped and opens no approval, any other answer opens the request as above. The release carries that guard from the start; evaluating it is engine behaviour of I4 and is not proven by this I1 feature. One branch is not settled by the model: a ChangesRequested decision returns the run to the lease holder with the reason of the reviewer, but a Human step has no lease holder, so what regenerates the change set stays open.

Acceptance criteria

AC1 Given steps.record-outputs.generated-outputs is recorded, when the engine marks generate-product/approve-proposal ready, then a RunControlService/ApprovalRequest of kind approval names the run and the step, carries action class shared-write, proposal kind diff and the change-set hash, RunControlService/ApprovalRequested is published and the run waits WaitingForApproval (SCN-generate-product-012, ADR-0015).
AC2 Given an eligible Reviewer who is not the requester of the run decides through RunControlService/DecideApproval, when the decision approves the pending hash, then RunControlService/ApprovalDecided resumes the run and generate-product/propose-change-set becomes ready; a decision by the requester is refused and a decision on a Stale request never advances the run (SCN-generate-product-012).
AC3 Given the request is rejected or expires after P7D, when Run Control applies the decision, then the run fails with failure class policy-denied, WorkflowEngineService/WorkflowRunFailed names approve-proposal and nothing is proposed; given the run is cancelled or fails while the request is Pending, the RunControlService/ApprovalRequest ends Cancelled and nothing is proposed (SCN-generate-product-012, ADR-0014).
AC4 Given an eligible Reviewer decides ChangesRequested with a reason through RunControlService/DecideApproval, when Run Control records it, then RunControlService/ApprovalDecided carries ChangesRequested and the reason and the run does not reach generate-product/propose-change-set; which step regenerates the change set is pending the owner and not asserted, because RunControlService returns such a run to the lease holder and a Human step has none (SCN-generate-product-012).
AC5 Given a project policy that would allow autonomous change proposals, when a run of this increment reaches generate-product/approve-proposal, then the request of AC1 is opened all the same, because until I4 the approval always runs, and the Draft release carries the policy_guard of model/workflows/generate-product.yaml with from_increment I4 unchanged for the engine to evaluate from I4 (SCN-generate-product-012, D133).
Traces: workflows generate-product
Traces: steps generate-product/approve-proposal
Traces: services RunControlService, WorkflowEngineService
Traces: aggregates RunControlService/ApprovalRequest, RunControlService/Run, WorkflowEngineService/WorkflowRun
Traces: apis RunControlService/DecideApproval
Traces: events RunControlService/ApprovalRequested, RunControlService/ApprovalDecided, WorkflowEngineService/WorkflowRunFailed
Traces: descriptors change-set-v1
Traces: scenarios SCN-generate-product-012
Traces: adrs ADR-0014, ADR-0015
Traces: requirements FR-08
Depends on AIFACTORY-US-016, feature:run-control-service, feature:workflow-engine-service
Sources model/workflows/generate-product.yaml, model/services/control-plane/RunControlService.yaml, model/scenarios/generate-product.yaml

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-4605 Verify the approval block of approve-proposal in the Draft release against the definition verification A check of the release authored by AIFACTORY-TASK-181 against model/workflows/generate-product.yaml proves that the step approve-proposal carries kind human, gate approval, side_effect_class shared-write, timeout P7D, failure_policy Fail, no when guard, the approval block with action_class shared-write, proposal_kind diff, proposal_from steps.record-outputs.generated-outputs, the approver rule and the stale rule, and the policy_guard with from_increment I4, action_kind tool-invocation and skip_when allow; nothing is authored here. ConnectSoft.AI.SoftwareFactory.WorkflowEngineService
AIFACTORY-TASK-4606 Fixture decisions on the change-set approval fixture Recorded decisions on the request of approve-proposal (approve by an eligible Reviewer, decision by the requester refused, reject, expiry after P7D, Stale after a regenerated hash, Cancelled when the run is cancelled) with the expected run outcome, and a ChangesRequested decision with its expected ApprovalDecided only, as the oracle of SCN-generate-product-012. ConnectSoft.AI.SoftwareFactory.WorkflowEngineService
AIFACTORY-TASK-4607 Prove the change-set approval on the fixture verification A fixture run proves SCN-generate-product-012 (AC1 to AC5 of AIFACTORY-US-1160); the approval request names the run and the step and the change-set hash, only an eligible Reviewer advances the run, rejection and expiry fail it policy-denied, a Pending request ends Cancelled with the run, a ChangesRequested decision does not reach propose-change-set, and under a policy that would allow autonomous proposals the request is still opened, because until I4 the approval always runs (D133). ConnectSoft.AI.SoftwareFactory.WorkflowEngineService

AIFACTORY-US-1161: The approved change set is proposed as a pull request under the approval bound to its request hash

behavior · persona reviewer As a reviewer, I want the pull request opened only for the change set I approved, under my approval and nothing else, so that a changed change set or another tool version can never reach the system of record under my decision.

The last step of generate-product, the shared-write tool propose-change-set. When approve-proposal was approved the engine marks it ready and resolves change-set from steps.record-outputs.generated-outputs, provenance from steps.record-outputs.provenance and validation-results from steps.build-and-test.validation-results. Run Control dispatches the attempt and ToolAdapterService executes the tool under the run's workload identity through its fixed pipeline, whose behaviour feature tool-adapter-service delivers (AIFACTORY-US-604): Policy.Decide answers for the tool-invocation, and under allow-with-approval, the answer for this tool unless the project policy allows autonomous proposals, the call executes only with the approvalId of the approve-proposal request, which ToolAdapterService validates before anything is brokered: same tenant and run, state Approved, proposal hash equal to the request hash of the invocation, which covers the tool id, the exact tool version and the arguments. Whether the proposal hash of that request, the hash of generated-outputs, equals the request hash the executor computes is the open point AIFACTORY-US-604 reports; this PBI cites it and does not resolve it. Under allow the call executes with no approvalId. The tool pushes the branch and opens the pull request through the connection of the project, with the credential IntegrationService resolves through the Secret Broker, the provenance and the validation results attached; it then records the proposal with Pipelines.RecordProposal of PipelineExecutionService under the scope factory.delivery.propose, sending change-proposal-record-v1 with the change set, the run, the attempt, the agent release, the pull-request reference and the tool receipt (D135). The proposal is recorded in PullRequestOpen, ChangeProposalOpened names the run and change-proposal (pull-request-proposal-v1) is recorded once; OpenChangeProposal stays the route of a person and is not called. The step declares failure_policy Compensate, a fixed retry of 2 attempts and no idempotency_key, so a Failed attempt is not retried (ADR-0014): the run ends Failed with the evidence and the sandbox outputs stay recorded. A step's own compensation runs only after its effect is confirmed (D133), so a Failed attempt, which opened nothing, withdraws nothing, and no succeeded step before it declares a compensation. The declared withdrawal applies only to an effect an operator confirms and then chooses to compensate, and no operation of PipelineExecutionService implements a withdrawal yet, which stays an open point. An Uncertain attempt raises ToolEffectUncertain and waits for an operator through ConfirmToolEffect.

Acceptance criteria

AC1 Given approve-proposal was approved and Policy.Decide answers allow-with-approval, when generate-product/propose-change-set calls propose-change-set, then the ToolAdapterService/ToolInvocation carries the approvalId of the approve-proposal request and ToolAdapterService validates it against the request hash and the exact tool version before anything is brokered, an approval that does not bind leaving the invocation AwaitingApproval; given the answer allow, the call executes without an approvalId; the correspondence of the change-set hash with the request hash stays the open point of AIFACTORY-US-604 (SCN-generate-product-013).
AC2 Given the invocation executes, when the tool has opened the pull request through the connection and records it through PipelineExecutionService/Pipelines.RecordProposal with change-proposal-record-v1, then the pull request carries exactly the approved change set with the provenance and the validation results, the PipelineExecutionService/ChangeProposal is recorded in PullRequestOpen with the run, attempt, agent release, pull-request reference and tool receipt, PipelineExecutionService/ChangeProposalOpened names the run and change-proposal (pull-request-proposal-v1) is recorded once under the run envelope (SCN-generate-product-013, D135, XL-10).
AC3 Given an attempt of generate-product/propose-change-set settles Failed, when Run Control evaluates it, then it is not retried, because the shared-write step declares no idempotency key, WorkflowEngineService/WorkflowRunFailed names the step and the run ends Failed with the evidence and the sandbox outputs kept; nothing is withdrawn, because a step's own compensation runs only after its effect is confirmed and the Failed attempt opened nothing (SCN-generate-product-013, D133, ADR-0014).
AC4 Given an attempt settles Uncertain, the PT30M timeout passing after the call was dispatched with no answer, when Run Control records it, then ToolAdapterService/ToolEffectUncertain is raised, no automatic retry follows and the attempt stays Uncertain until an operator settles it through ToolAdapterService/ConfirmToolEffect (SCN-generate-product-013, ADR-0014).
Traces: workflows generate-product
Traces: steps generate-product/propose-change-set
Traces: tools propose-change-set
Traces: services ToolAdapterService, PipelineExecutionService, RunControlService, WorkflowEngineService
Traces: aggregates ToolAdapterService/ToolInvocation, PipelineExecutionService/ChangeProposal
Traces: apis PipelineExecutionService/Pipelines.RecordProposal, ToolAdapterService/ConfirmToolEffect
Traces: events PipelineExecutionService/ChangeProposalOpened, ToolAdapterService/ToolEffectUncertain, WorkflowEngineService/WorkflowRunFailed
Traces: descriptors change-set-v1, artifact-v1, pull-request-proposal-v1, change-proposal-record-v1
Traces: scenarios SCN-generate-product-013
Traces: adrs ADR-0014, ADR-0015
Traces: requirements FR-08, XL-10
Depends on AIFACTORY-US-1160, feature:tool-adapter-service, feature:pipeline-execution-service-thin, feature:integration-service-thin, feature:secret-broker-service, feature:run-control-service, feature:workflow-engine-service
Sources model/workflows/generate-product.yaml, model/tools/propose-change-set.yaml, model/services/tools-mcp/ToolAdapterService.yaml, model/services/devops-gitops/PipelineExecutionService.yaml, model/scenarios/generate-product.yaml

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-4608 Verify the propose-change-set step of the Draft release against the definition verification A check of the release authored by AIFACTORY-TASK-181 against model/workflows/generate-product.yaml proves that the step propose-change-set names the tool propose-change-set, carries side_effect_class shared-write, failure_policy Compensate, no idempotency_key, the fixed retry of 2 attempts with backoff 10s, timeout PT30M, the compensation text as declared and the mappings change-set from steps.record-outputs.generated-outputs, provenance from steps.record-outputs.provenance and validation-results from steps.build-and-test.validation-results; the tool binding is consumed from feature tool-adapter-service and nothing is authored here. ConnectSoft.AI.SoftwareFactory.WorkflowEngineService
AIFACTORY-TASK-4609 Fixture proposal outcomes for the bound, allowed, failed and uncertain paths fixture Recorded outcomes of propose-change-set (opened under a bound approvalId and recorded through Pipelines.RecordProposal with its change-proposal-record-v1 request, an approval of another hash leaving the invocation AwaitingApproval, opened without approvalId under a policy answer allow, Failed without a retry or a withdrawal, Uncertain until ConfirmToolEffect) with the expected run outcome, as the oracle of SCN-generate-product-013. ConnectSoft.AI.SoftwareFactory.WorkflowEngineService
AIFACTORY-TASK-4610 Prove the change-set proposal on the fixture verification A fixture run proves SCN-generate-product-013 (AC1 to AC4 of AIFACTORY-US-1161); the call executes only under a bound approvalId or a policy answer allow, the opened pull request carries the approved change set and is recorded through Pipelines.RecordProposal in PullRequestOpen with ChangeProposalOpened, a Failed attempt is not retried and fails the run with the sandbox outputs kept and nothing withdrawn, and an Uncertain attempt waits for ConfirmToolEffect. ConnectSoft.AI.SoftwareFactory.WorkflowEngineService