ADR-0027: Generation input contract — the approved recipe as the single gate, dedicated design workflows, guarded fill branches, strict contracts for every definition¶
Decision
This page records a decision and its status. A Proposed decision is not binding; an Accepted decision is binding on the Factory until amended or superseded.
- Status: Accepted 2026-11-05 by the product owner (decisions D65–D69); decisions D70 and D71 were derived while applying D69 and were accepted by the owner on 2026-11-05 (D80); the six blueprint kinds without a producer are closed by ADR-0030
- Date: 2026-11-05
- Deciders: Dmitry Khaymov (product owner)
- Tags: workflows, generation, recipe, blueprints, validation
Context¶
The owner selected the first outcome the Factory is built towards: generate a microservice, as the full chain from a submitted vision to a proposed change set, with the upstream workflows, the readiness correlation of ADR-0026 and the four roles of generate-product in scope (D65).
Reading the model for that chain showed that the generation run could not execute as modelled:
generate-productdeclared the recipe, the manifests and the Module Blueprints as inputs and mapped no step input. Its roles required more: the Frontend Developer a Frontend Blueprint and a UX Blueprint, the Database Engineer a Database Blueprint and the domain model, the Backend Developer an application design.- No workflow definition produced a Frontend Blueprint, a Database Blueprint or an application design, although the schemas and the authoring roles existed.
- The readiness bundle of
generate-productwaited for the recipe and the Module Blueprints only, and a newer Module Blueprint version could supersede a run whose recipe pins an older one. - The gap survived validation because step input mapping was opt-in: 21 of the 27 definitions carried no mappings, and 67 required role inputs across them had no declared source.
Decision¶
- Dedicated design workflows (D66). Three readiness-activated definitions produce the missing design inputs, each on the pattern of the existing blueprint workflows:
application-design: the Application Architect turns each validated Module Blueprint into anapplication-design-v1artifact (use cases, ports, adapters, telemetry spans).database-blueprint: the Database Engineer builds the Database Blueprint from the Service Blueprint and the derived domain model, with the submit, validate and check loop. A product without persistence yields a blueprint with no stores, so definitions that await the kind are never starved.frontend-blueprint: the Frontend Developer builds the Frontend Blueprint from the Service and UX Blueprints, with the same loop. It runs only for a product whose UX Blueprint exists.
- The approved recipe is the single gate of a generation run (D67). Every module entry of a recipe pins the design inputs its kind needs by id, version and hash. GenerationRecipeService validates and lets a person approve a recipe only when every pin resolves to a validated version. The readiness bundle of
generate-producthas one member,RecipeApproved. The first step of the run,resolve-recipe, calls the read-class toolget-approved-recipeand records the module plan and the pinned inputs; every later step maps its inputs from that step. A newer blueprint version never supersedes the run; a newer recipe version does. - Guarded fill branches (D68). A step may carry a
whenguard over recorded outputs of its ancestors or over workflow inputs. The step runs only when the guard holds; otherwise the engine records it Skipped, a value theStepStateof RunControlService already names, and its dependants treat it as satisfied.fill-frontendruns when the module plan has a shell or microfrontend module,fill-databasewhen it has a module with persistence. All four roles stay modelled; whether the first product has a user interface is a property of its recipe, not of the architecture. Only a condition step carries acondition; a guard on any other step kind is awhen. - Strict contract for every definition (D69).
contract: strictis required and is the only accepted value. Every agent step maps every required input of its role, every tool step maps its input, and the validator adds four rules:- every definition declares the strict contract;
- a
whenguard readssteps.*of an ancestor orinput.*only; - a required role input is never fed by an optional workflow input, by an optional readiness member, or by a guarded step unless the consuming step carries the same guard;
- blueprint kinds that a readiness bundle awaits but no definition produces are reported, and the coverage page lists them.
- Role contract corrections (D70, derived, accepted by the owner). Applying the strict contract exposed roles whose required inputs did not fit the steps that cast them. Each was corrected at the role or by recasting the step:
- the Database Engineer, the Frontend Developer and the Infrastructure Architect required the blueprint they author; that input became optional and the blueprint became a declared output;
- the Solution Architect drafts the Module Blueprints in
module-blueprints(its contract is the Service Blueprint in and Module Blueprints out), replacing the Backend Developer, whose contract needs module code that does not exist yet; - the Release Manager prepares the release manifest in
delivery-run, replacing the Deployment Orchestrator, whose contract needs that manifest as input; - the DevOps role no longer requires a Pipeline Blueprint, because project bootstrap precedes any; the Security Engineer no longer requires findings, because it also scans;
infrastructure-planvalidates its blueprint through the tool call and receipt of ADR-0026 instead of emitting the event without one;- in
generate-librariesthe Backend Library Blueprint is the design the Backend Developer implements, and ininfrastructure-planthe Infrastructure Blueprint is the proposal the Infrastructure Engineer implements.
- Readiness members added for required role inputs (D71, derived, accepted by the owner). Where a role's required input had no source in a readiness-activated definition, the source became a member of the bundle: the Service and Module Blueprints in
behaviour-simulation; the Vision Blueprint incapability-gap-analysisandsaga-design; the Database and Security Blueprints incompliance-check; the merged change set and the approved recipe indebt-review; the Service Blueprint ingateway-generation; the Infrastructure Blueprint inpreview-environment; the pipeline results inrelease. The person-submitted definitionsmilestone-lifecycleandsprint-executiondeclare the same sources as required inputs.
Consequences¶
- The model carries 30 workflow definitions, all strict; 26 are readiness-activated and four are submitted by a person. The validator reports no errors.
- The chain to the first outcome is explicit:
vision-to-blueprint(submitted by a person),architecture-decomposition,module-blueprints,application-design,database-blueprint, the recipe a person approves, thengenerate-product. A product with a user interface addsux-discovery,requirements-alignment,ux-blueprintandfrontend-blueprint. - GenerationRecipeService gains the pinned design inputs of a module entry, two tracking handlers and a stricter validation rule; ToolAdapterService calls its
GetApprovedRecipefor the new tool. - A definition changed by D71 starts later than before, because it now waits for the inputs its roles need. That is the intended effect.
- Six blueprint kinds are awaited by a bundle and produced by no definition: API Gateway, Backend Library, Documentation, Observability, Pipeline and Security. They were authored by a person through BlueprintService until ADR-0030 added a producing definition for each (D78); the model now carries 36 definitions.
- 15 mappings delivered a typed body into an untyped
artifact-v1role input when this ADR was accepted; they were typed on 2026-11-06 and the validator now refuses such a mapping (see the amendment).
Alternatives rejected¶
- Design inside the generation run. The roles would draft their own blueprints during generation. Rejected: the recipe must pin validated versions before a person approves it.
- Extending
module-blueprintswith the Database Blueprint and the application design. Rejected: one definition would own three document kinds, and the Frontend Blueprint needs its own activation in any case. - Every blueprint as a member of the generation bundle with a consistency rule against the recipe. Rejected: the recipe already pins the versions, and a second gate allows version skew and supersedes approved runs.
- Always running all three fill branches. Rejected: a product may be a pure backend service, and the UX path would become mandatory for every product.
- Strict contracts on the first-outcome chain only. Rejected by the owner: the class of gap is closed for every definition.
- Relaxing required role inputs to optional wherever a source was missing. Rejected as a general rule: it hides the gap. A role input was relaxed only where the requirement was wrong for every cast of the role.
Revisit triggers¶
- The engine design shows that a join or a compensation must tell a Skipped ancestor from a Succeeded one in a way the guard semantics above do not cover.
- A role is curated with typed inputs: the untyped mappings of that role become descriptor checks.
- A role corrected by D70 is curated again and its contract changes.
Amendment 2026-11-06: no typed body in an untyped input (D88)¶
The mappings that delivered a typed body into an untyped artifact-v1 input were typed, and the validator now reports such a mapping as an error.
- The brief of the Vision Architect is the run submission (
run-submission-v1). - The Backend Developer takes the application design (
application-design-v1) and, through a separate input, a library blueprint (blueprint-backend-library-v1); a step maps the one it has. - The Infrastructure Engineer takes the Infrastructure Blueprint through its own input; the reconciliation proposal stays a separate, optional input.
- The tool
blueprint-submit-versiondeclaresinput_family: blueprint-kinds: it accepts the document of any blueprint kind ofmodel/blueprints.yamland refuses any other body. - Every agent step of the definitions of the first two outcomes selects a curated skill whose contract is the mapping of the step (D91).
Amendment 2026-11-08: every template parameter has a Factory binding (D104)¶
The generation input contract names the blueprints a recipe reads; it did not say how a blueprint becomes the parameter values a dotnet new template takes. Every ConnectSoft template now has a parameter snapshot under model/template-parameters/ (written read-only from the template's .template.config by python -I tools/docs_model inventory-templates), and every parameter carries a Factory binding: the source of its value (blueprint field, recipe decision, adr, environment, registry, operator, fixed, unbound), the value the Factory passes and the reason. The module blueprint records the resolved values in template.switches.
- The validator refuses a parameter without a resolved binding, a blueprint reference that is not a field of a kind in
blueprints.yaml, an ADR reference that is not accepted, and afixedorunboundbinding without a reason. - The thirteen templates built on the base template inherit its bindings parameter by parameter and override only where their own value differs; parameter names shared by the small templates (
Framework,buildDefinitionNumber,skipRestore,includeTests, theUse*toggles) are bound once in_shared.yaml. - The computed and generated symbols of each template are recorded with their expressions, because they are what decides which code paths and files the generated solution contains; they are never passed by the recipe.
- The template parameters page is the catalog; each template page carries its own section.