AIFACTORY-FEAT-183: Library template: target frameworks, a manifest and Factory diagnostics for generated libraries¶
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 Ecosystem component extensions · Increment I0 Readiness · State elaborated · Route backend-developer · Phase before development · Build order 20 of 185 (Templates and libraries)
Before development
Template or library work: every task of this feature changes a template or a shared library the Factory builds on, and it lands before the Factory's own repositories of I0 are developed. The mark travels with every task (tag phase:before-development).
The contracts package (FEAT-090), the gateway client packages (FEAT-178) and every Backend Library module of a generated product (blueprint backend-library, workflow generate-libraries) are scaffolded from the library template (connectsoft-library). The template ships a multi-target class library with optional dependency injection, logging, options binding, metrics and an ActivitySource sample, MSTest, central package management, analyzers, an Azure pipeline and a MkDocs layout; its own pages record that the Framework parameter is a documentation moniker that does not change TargetFrameworks, that the pipeline variables live outside the template parameters, and that eighteen existing libraries still await the alignment checklist (analyzers Include, stylecop.json, .slnx, MkDocs) the template defines. A library generated for the Factory needs one parameter that sets its target frameworks, a manifest the template registry imports, samples on the Factory diagnostics names, and a pipeline that publishes to the Factory feed with the pipeline results the quality gates expect. Component: Library template (extend).
| Delivers | — |
| Stubs | — |
| Realizes | components: cmp-library-template adrs: ADR-0001, ADR-0019, ADR-0027, ADR-0028 |
| Requirements | — |
| Depends on | — |
| Sources | model/components.yaml, model/templates.yaml, model/blueprints.yaml, ConnectSoft.LibraryTemplate/docs/Features.md, ConnectSoft.LibraryTemplate/docs/Runbook.md, ConnectSoft.LibraryTemplate/docs/Alignment.md, ConnectSoft.LibraryTemplate/.template.config/template.json |
AIFACTORY-US-214: Library template: one parameter sets the target frameworks of the generated library, its tests and its pipeline¶
enabling · persona asset-maintainer
As an asset maintainer, I want a parameter of the library template that decides which frameworks a generated library targets, so that a library generated for the Factory targets the framework of the Factory backend without a hand edit of its project files.
The template configuration of the library template has a choice named Framework with the values net8.0, net9.0 and net10.0, and its own description says what it does: it is the primary framework moniker for the command line, the editor and the documentation, the generated library always targets all three frameworks, and the parameter does not change the target frameworks. The Features page repeats that statement and the Runbook page explains that the sample pipeline installs three SDK versions so that the three targets build. ADR-0001 standardizes the Factory backend on .NET 10, so the contracts package, the gateway client packages and the backend library modules of a generated product need a library that targets one framework. This PBI adds one parameter that sets the target frameworks. Its values are the multi-target set of today, which stays the default so that existing consumers of the template see no change, and the single framework of ADR-0001. The Factory scaffold passes the single framework as a value of this parameter; the profile symbol UseFactoryProfile of the template does not derive it. The project file of the library, the unit test project and the SDK installation steps of the generated pipeline follow the chosen set, and no file of the generated repository names a framework outside it. The Framework choice keeps its meaning as the primary moniker; the template engine has no constraint between symbols, so a primary moniker that is not a member of the chosen set is replaced by the highest framework of the set through a computed symbol instead of being refused. The name and the semantics of the parameter are recorded on the Features page so that the AI skills library template can adopt the same parameter in its own feature.
Acceptance criteria
| AC1 | Given the library template, when a library is generated with the target-frameworks parameter set to the single framework of ADR-0001, then the project file of the library and of its tests target that framework only, the generated pipeline installs only that SDK, the solution builds and its tests pass, and no generated file names another framework. |
| AC2 | Given the library template, when a library is generated without the parameter, then it targets the same three frameworks as today and the generated repository is unchanged from the output of the current template except for the files of this feature; the parameter with its values appears in model/template-parameters/connectsoft-library.yaml after the next inventory (ADR-0028). |
| AC3 | Given a primary moniker that is not a member of the chosen set, when the library is generated, then the highest framework of the set is used as the primary moniker through a computed symbol and the generation succeeds; the scaffold tests cover the combination, and the Features page states the name and the semantics of the parameter (ADR-0001, model/templates.yaml keeps the targets of the template). |
| Traces: adrs | ADR-0001, ADR-0028 |
| Sources | model/components.yaml, model/templates.yaml, model/template-parameters/connectsoft-library.yaml, docs/architecture/ecosystem-composition.md |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-647 Target frameworks as a parameter of the generated library |
contract | One parameter of the template configuration sets the TargetFrameworks of the generated library, with the multi-target set of today as the default and the single .NET 10 framework as a value; the Framework choice keeps its meaning as the primary moniker, which its description records, and a computed symbol replaces a primary moniker outside the chosen set; the Features page records the name and semantics for the AI skills library template. |
ConnectSoft.LibraryTemplate |
AIFACTORY-TASK-1035 Project files, test project and pipeline SDK steps follow the chosen frameworks |
implementation | The project file of the library, the unit test project and the SDK installation steps of the generated pipeline are generated from the chosen set; with the single framework chosen no generated file names another framework and the pipeline installs one SDK. | ConnectSoft.LibraryTemplate |
AIFACTORY-TASK-1036 Verify the single-framework, the default and the mismatched-moniker generations |
verification | Run the scaffold tests of the template for the single framework, the default set and a primary moniker outside the chosen set; each generated solution builds and passes its tests, which proves AC1 to AC3 of AIFACTORY-US-214 (ADR-0001). | ConnectSoft.LibraryTemplate |
AIFACTORY-US-215: Library template: the generated repository carries a manifest of its generation and the package exports a symbol catalog¶
enabling · persona asset-maintainer
As an asset maintainer, I want every generated library to record the template, the version and the parameter values it was generated with, and the template to publish the list of its symbols, so that the template registry can import the template and a generation recipe can pin it and reproduce a library.
A library generated from the template today keeps no record of how it was generated: nothing in the repository names the template, its version or the values of UseDI, UseLogging, UseOptions, UseMetrics, UseActivitySource and the framework choices, and the symbols of the template can be learned only by reading its configuration file. The generation contract of ADR-0027 lets a recipe pin every input of a module by id, version and hash, and the documentation template feature of this epic names the same need as a manifest and a symbol catalog; the library template is the first template to carry both because the contracts package and the gateway clients are scaffolded from it before any service. This PBI adds a manifest to the generated repository, the file .connectsoft/template-manifest.json. It is written at generation and holds the template id connectsoft-library, the version of the template package and the value of every parameter. It is preserved: a later regeneration of the same library reads it as its input, and a scaffold test fails when the manifest disagrees with the generated project files. The manifest guarantees that a regeneration reproduces the parameter values, not an identical output: the template has a generated symbol currentYear that writes the year of the generation, and that year is outside the reproducibility the manifest guarantees. The template package exports a symbol catalog, the file .template.config/symbol-catalog.json beside the template configuration, produced at pack time from that configuration: every symbol with its type, data type, default, choices and description, in the shape the template inventory of the documentation repository reads into model/template-parameters/connectsoft-library.yaml. A manifest schema, the file .template.config/template-manifest.schema.json, is published with the catalog. The three file names are set here, by the first template that carries them, so that the template registry and the documentation template feature read the same files. The import by the template registry is work of that service in a later increment; this PBI delivers the two files it will read.
Acceptance criteria
| AC1 | Given a library generated from the template, when its repository is inspected, then the manifest .connectsoft/template-manifest.json holds the template id connectsoft-library, the version of the template package and the value of every parameter of the generation, and the scaffold tests read the manifest back and compare it with the generated project files (ADR-0027 decision 2 pins a generation input by id, version and hash). |
| AC2 | Given the packed template, when the package is inspected, then it contains the symbol catalog .template.config/symbol-catalog.json with every symbol, its type, data type, default, choices and description, produced from the template configuration at pack time, and the catalog lists the same symbols as model/template-parameters/connectsoft-library.yaml after the next inventory (ADR-0028). |
| AC3 | Given a generated library whose manifest was edited so that it disagrees with its project files, when the scaffold tests run, then they fail with the differing parameter named; a regeneration that takes the manifest as its input reproduces the same parameter values, the year the currentYear symbol generates being outside that guarantee, and the manifest validates against the published schema .template.config/template-manifest.schema.json (ADR-0027, model/templates.yaml lists the switches the catalog must cover). |
| Traces: adrs | ADR-0027, ADR-0028 |
| Depends on | AIFACTORY-US-214 |
| Sources | model/components.yaml, model/templates.yaml, model/template-parameters/connectsoft-library.yaml, docs/architecture/adr/0027-generation-input-contract.md |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-1037 Manifest schema of a generated library |
contract | The schema file .template.config/template-manifest.schema.json in the template repository defines the manifest of a generated library, the file .connectsoft/template-manifest.json of the generated repository, with the template id, the template package version and one entry per parameter; the schema is packed with the template beside the symbol catalog. |
ConnectSoft.LibraryTemplate |
AIFACTORY-TASK-1038 Manifest written at generation and preserved on regeneration |
implementation | The template writes the manifest .connectsoft/template-manifest.json into the generated repository with the chosen value of every parameter and the version of the template package; a regeneration reads the manifest as its input and reproduces the parameter values; the year the generated symbol currentYear writes is outside that reproducibility, which the Features page states. |
ConnectSoft.LibraryTemplate |
AIFACTORY-TASK-1039 Symbol catalog exported at pack time |
implementation | A pack step reads the template configuration and writes the symbol catalog .template.config/symbol-catalog.json into the package with every symbol, its type, data type, default, choices and description; the pipeline fails when the catalog and the configuration differ. |
ConnectSoft.LibraryTemplate |
AIFACTORY-TASK-1040 Verify the manifest read-back and the symbol catalog |
verification | Run the scaffold tests of the template; the manifest of every generated case is read back and compared with the project files, an edited manifest fails the comparison and the catalog of the package equals the configuration, which proves AC1 to AC3 of AIFACTORY-US-215 (ADR-0027). | ConnectSoft.LibraryTemplate |
AIFACTORY-US-216: Library template: the metrics and ActivitySource samples follow the diagnostics names and the no-payload rule, and UseFactoryProfile adds the scope tags of the Factory¶
enabling · persona asset-maintainer
As an asset maintainer, I want the diagnostics samples of a generated library to start on the names and rules the Factory uses, so that no library generated for the Factory needs a later rename of its meter or its activity source and none records payload in telemetry.
The library template generates a metrics sample when UseMetrics is on and a diagnostics class with an activity source, a sample and tests when UseActivitySource is on; the Features page describes both, and the Runbook page states that a class library hosts no ASP.NET Core endpoints and no health endpoints of its own, although further down the same page shows a section of health check endpoints and a web app slot swap; this PBI removes that contradiction from the page. The activity source of the sample is named after the library. The telemetry conventions of the Factory are fixed for the observability libraries by a later feature of this epic, so the template does not wait for them: it adopts the naming the ConnectSoft libraries already publish, a meter under the connectsoft. prefix in lower case derived from the library name and an activity source named after the library, so that a library generated today is already on the names the convention will confirm. The Factory part of the samples belongs to the Factory profile of the template, which decision D114 and the amendment of ADR-0028 on the Factory profile switch name: the boolean UseFactoryProfile, off by default, with the same name as in the base, worker and gateway templates, passed by the Factory scaffold command. This PBI adds the symbol to the template configuration. With it on, the samples gain the scope tags of the Factory: the activity sample shows how tenant, project, run, step and attempt identity are set as tags from values the caller passes, and the allow list of the tag test holds those names. With it off, the samples carry no scope tag, so a generation outside the Factory does not change in this respect. The symbol derives nothing else: the target frameworks and the feed stay parameters of their own, and the manifest records its value. In both cases the metric sample uses bounded dimensions only and never a run or attempt identifier. The samples follow the telemetry rule of ADR-0019 decision 3: no prompt, response, tool output or message body is written to a tag, a metric dimension or a log message. A unit test in the generated solution checks the tag names of the samples against an allow list, so that a library author who adds a payload tag is told by a failing test. The library still hosts no endpoint.
Acceptance criteria
| AC1 | Given a library generated with UseMetrics and UseActivitySource on, when its diagnostics are inspected, then the meter name is lower case under the connectsoft. prefix derived from the library name and the activity source is named after the library, on every target framework, and the Features page of the template states the two names (ADR-0028, model/template-parameters/connectsoft-library.yaml lists the two switches). |
| AC2 | Given a library generated with UseFactoryProfile and both diagnostics switches on, when an activity is started with a scope passed by the caller, then tenant, project, run, step and attempt identity appear as tags of the activity, while a library generated without UseFactoryProfile, its default, carries no scope tag (ADR-0028 amendment on the Factory profile switch); in both generations the metric sample carries bounded dimensions only, and neither sample writes a prompt, a response, a tool output or a message body to a tag, a dimension or a log message, as ADR-0019 decision 3 requires. |
| AC3 | Given the unit tests of a generated library, when a tag outside the allow list is added to a sample, then the tag test fails with the tag named; the generated library references no ASP.NET Core package and maps no endpoint, as the Runbook page of the template states (ADR-0019, ADR-0028). |
| Traces: adrs | ADR-0019, ADR-0028 |
| Sources | model/components.yaml, model/template-parameters/connectsoft-library.yaml, docs/architecture/ecosystem-composition.md, docs/architecture/adr/0019-data-governance.md |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-648 Samples on the Factory diagnostics conventions |
implementation | The metrics and ActivitySource samples use the meter and activity-source naming the ConnectSoft libraries publish under the connectsoft. prefix and the no-payload rule, and with UseFactoryProfile on the activity sample carries the scope tags, so a library generated for the Factory starts on the conventions without a later rename; the library still hosts no ASP.NET Core endpoints, as the Runbook page states. |
ConnectSoft.LibraryTemplate |
AIFACTORY-TASK-1060 UseFactoryProfile in the configuration of the library template |
contract | The template configuration defines the boolean UseFactoryProfile, off by default, under the name the base, worker and gateway templates use; with it on the activity sample carries the Factory scope tags and the allow list of the tag test holds them, and it changes neither the target frameworks nor the feed; the command line host file exposes the option, the manifest records its value and the Features page documents it. |
ConnectSoft.LibraryTemplate |
AIFACTORY-TASK-1041 Tag allow-list test in the generated unit test project |
fixture | The unit test project of a generated library holds a test that collects the tag and dimension names of the samples and compares them with an allow list, which holds the scope tag names only when UseFactoryProfile is on; a name outside the list fails the test with the name reported; the test is generated only when a diagnostics switch is on. | ConnectSoft.LibraryTemplate |
AIFACTORY-TASK-1042 Features and Runbook pages state the diagnostics names and the no-payload rule |
documentation | The Features page of the template names the meter and activity-source convention and the scope tags the samples carry under UseFactoryProfile; the Runbook page states the no-payload rule and the allow-list test and keeps the statement that a library hosts no endpoints; the health check endpoint section and the web app slot swap and rollback sections of the Runbook page, which contradict that statement, are removed or marked as guidance for the consuming host. |
ConnectSoft.LibraryTemplate |
AIFACTORY-TASK-1043 Verify the names, the scope tags and the allow-list test on generated libraries |
verification | Generate a library with UseFactoryProfile and both diagnostics switches on, one with both switches on and without the profile, and one with both switches off, build and test them; the name, scope tag and allow-list tests pass on the first, the second carries the names and no scope tag, and the third contains no diagnostics file, which proves AC1 to AC3 of AIFACTORY-US-216 (ADR-0019). |
ConnectSoft.LibraryTemplate |
AIFACTORY-US-217: Library template: the generated pipeline publishes to the feed it is given with symbols, an SBOM and the PIPE-001 results, and the alignment checklist is the generated default¶
enabling · persona asset-maintainer
As an asset maintainer, I want a generated library to publish to the ConnectSoft feed with the pipeline results the Factory expects and to need no later alignment pass, so that the contracts package and the gateway clients are published correctly from their first pipeline run.
The Runbook page of the library template states that the pipeline variables of a generated library, such as the coverage threshold and the feed identifiers, live in the pipeline file of the generated repository and are not passed when scaffolding, so a library generated for the Factory starts with a feed and a threshold that someone has to edit. The Alignment page of the template defines a checklist that eighteen existing libraries still await: the analyzers included and not only updated in the build properties, a style configuration file wired as an additional file, the documentation site with its pipeline, central package management kept, a solution file in the new format and the multi-target set kept unless a task documents a single-framework constraint. Rule PIPE-001 of model/blueprints.yaml lists the typed results a pipeline produces: build, tests, coverage, analysis, scan, SBOM, packages, images and attestations. This PBI makes the generated repository correct from the start. The generated pipeline produces the build, tests, coverage, analysis and scan results, the analysis result being the analyzer result of the build and the scan result a dependency vulnerability scan; it packs the library, produces an SBOM with the package and publishes the package and its symbols to the configured feed with a version that is verified against the feed before the push. A library pipeline builds no image and signs no attestation, so those two results of the rule are stated as not produced. The feed and the coverage threshold become template parameters whose defaults are the values the template generates today, so that an existing consumer sees no change. The feed is settled by decision D114: the Factory feed is the Azure Artifacts feed the ConnectSoft libraries already publish to, which is the feed the generated pipeline names today, so the template keeps its feed default and the Factory scaffold passes no other feed. A consumer that publishes elsewhere, or that needs another threshold, passes the value as a parameter, and the manifest of the generated library records both values, so nothing is edited after generation. Every item of the alignment checklist is what the template generates by default, with the single-framework choice of the earlier PBI as the documented constraint the checklist allows. A publication with a version that is already on the feed is refused by the generated pipeline with the reason.
Acceptance criteria
| AC1 | Given a library generated from the template, when its pipeline runs on its publishing branch, then it produces the build, tests, coverage (measured against the generated threshold), analysis (the analyzer result), scan (the dependency vulnerability scan), SBOM and packages results of rule PIPE-001 of model/blueprints.yaml, and publishes the package and its symbols to the configured feed with a version verified against the feed; images and attestations, the two remaining results of the rule, are stated as not produced by a library pipeline (ADR-0028). |
| AC2 | Given the template parameters for the feed and the coverage threshold, when a library is generated without pipeline options, then the generated pipeline holds the values the template generates today, the ConnectSoft feed among them, so that an existing consumer sees no change and the Factory scaffold, which passes no other feed, publishes to that feed; when a scaffold passes another feed or threshold, then the generated pipeline holds the passed values and no pipeline file needs an edit after generation; the manifest records both values in either case, the parameters appear in model/template-parameters/connectsoft-library.yaml after the next inventory, and a version that is already on the feed is refused by the generated pipeline with the reason (ADR-0028). |
| AC3 | Given a library generated with the defaults, when it is compared with the checklist of the Alignment page of the template, then every item holds: the analyzers are included, the style configuration is an additional file, the documentation site and its pipeline exist, central package management is on and the solution file is in the new format, so that no alignment task is opened for a generated library (ADR-0028, docs/architecture/ecosystem-composition.md). |
| Traces: adrs | ADR-0028 |
| Depends on | AIFACTORY-US-214, AIFACTORY-US-215 |
| Sources | model/components.yaml, model/blueprints.yaml, model/template-parameters/connectsoft-library.yaml, docs/architecture/ecosystem-composition.md |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-1044 Feed and coverage threshold as template parameters with the defaults of today |
contract | The template configuration defines parameters for the package feed and the coverage threshold of the generated pipeline; their defaults are the values the template generates today, the feed being the ConnectSoft feed that is also the Factory feed, so the Factory scaffold passes no other feed; the manifest records both values; the generated pipeline file reads them and the Runbook page no longer tells the reader to edit the pipeline after generation. | ConnectSoft.LibraryTemplate |
AIFACTORY-TASK-1045 Package, symbols, SBOM, analysis and scan results with a version check in the generated pipeline |
operations | The generated pipeline builds, tests and measures coverage, publishes the analyzer result of the build as the analysis result, runs a dependency vulnerability scan as the scan result, packs the library, produces an SBOM, checks the version against the feed and publishes the package and its symbols to the configured feed; a version already on the feed is refused with the reason and the run fails; images and attestations are not produced by a library pipeline. | ConnectSoft.LibraryTemplate |
AIFACTORY-TASK-1046 Alignment checklist as the generated default |
implementation | The generated repository includes the analyzers in its build properties, wires the style configuration as an additional file, carries the documentation site with its pipeline, keeps central package management and uses the new solution file format; the Alignment page records that a generated library needs no alignment task. | ConnectSoft.LibraryTemplate |
AIFACTORY-TASK-1047 Verify the generated pipeline results and the checklist on a generated library |
verification | Generate a library with the defaults and one with a test feed and another threshold passed as parameter values; the pipeline file of the first names the ConnectSoft feed, run the pipeline of the second against the test feed and compare both repositories with the checklist of the Alignment page; the build, tests, coverage, analysis, scan, SBOM and packages results of PIPE-001 are produced with the package and its symbols, the passed values are in the pipeline file and in the manifest, a repeated version is refused and every checklist item holds, which proves AC1 to AC3 of AIFACTORY-US-217 (ADR-0028, model/blueprints.yaml). | ConnectSoft.LibraryTemplate |
AIFACTORY-US-218: Library template: the shared template pipeline gates the default generation and one Factory profile case, the scaffold tests cover the parameter matrix, and only then the package publishes¶
evidence · persona asset-maintainer
As an asset maintainer, I want every change of the library template to be gated by the libraries it generates, so that a template package that would generate a library that does not build or test never reaches the feed.
This PBI is the gate of the feature. The amendment of ADR-0028 on the Factory templates scaffolds a Factory repository only from a template package, and the epic is done only when each template publishes a package that passes its generated-solution gate. The estate has one gate mechanism for templates, the shared template pipeline of ConnectSoft.AzurePipelines (template-ci/v1): one packed candidate, the scaffold cases of the manifest build/template-ci.json of the consumer, result validation and publication on the complete reports of every selected case. Its Domain profile declares one case per supported artifact kind, and decision D114 with the amendment of ADR-0028 on the Factory profile switch admits one additional gating case per declared profile while default generations stay gated as today. The library template is not yet a consumer of the shared pipeline: its template pipeline packs and pushes without a generated case, and the rollout ledger of the shared pipeline has no row for it. This PBI makes it one. The template declares one profile, UseFactoryProfile, so the manifest holds two gating cases: the default generation, and the Factory profile case, a library generated with UseFactoryProfile true, the single framework of ADR-0001, dependency injection, options and the activity source sample, which is the shape of the contracts package with the sample that carries the scope tags of the profile. The parameter matrix is not a set of pipeline cases. The template repository already holds a scaffold test project, and the matrix of the five feature switches UseDI, UseLogging, UseOptions, UseMetrics and UseActivitySource, of UseFactoryProfile and of the values of the target-frameworks parameter runs there as tests of the authoring solution, as the scaffold tests run today, reduced to the pairs of values so that the run stays bounded while every pair of options is covered. For each gating case and each output of the matrix the solution is restored and built in Release, the unit tests of the generated library run, the manifest is read back, the tag allow-list test runs where a diagnostics switch is on and the output is scanned for template placeholders that were not replaced. A gating case or an output that fails any stage fails the run with the case or the parameter values and the stage named, and no later stage of it is reported as passed. Publication requires the complete reports of both gating cases and green scaffold tests, pushes the template package with a verified version and refuses a version that is already on the feed. A fixture with a planted defect in the Factory profile case proves the refusal. A final probe installs the published package and generates the Factory profile case, which builds unchanged.
Acceptance criteria
| AC1 | Given a change of the library template, when its pipeline runs the shared installer jobs with build/template-ci.json, then the candidate is packed once and installed, the default generation and exactly one additional gating case, generated with UseFactoryProfile true, the single framework, dependency injection, options and the activity source sample, are restored, built in Release, tested, checked against their manifests and scanned for placeholders, and the scaffold tests of the authoring solution instantiate the template across the pairwise matrix of UseDI, UseLogging, UseOptions, UseMetrics, UseActivitySource, UseFactoryProfile and the target-framework choices (ADR-0028 amendments on the Factory templates and on the Factory profile switch, model/template-parameters/connectsoft-library.yaml). |
| AC2 | Given a gating case or an output of the matrix fails any stage, when the pipeline evaluates the run, then the run fails with the case or the parameter values and the stage named, no later stage of it is reported as passed and publication is not reached; a fixture with a planted defect in the Factory profile case proves the refusal (ADR-0028). |
| AC3 | Given the complete reports of both gating cases and green scaffold tests, when publication runs, then the template package is pushed to the ConnectSoft feed with a verified version, a version that is already on the feed is refused, and an install of the published package followed by the generation of the Factory profile case builds unchanged (ADR-0028, model/backlog/epics.yaml states the gate as the completion of the epic). |
| Traces: adrs | ADR-0028 |
| Depends on | AIFACTORY-US-214, AIFACTORY-US-215, AIFACTORY-US-216, AIFACTORY-US-217 |
| Sources | model/components.yaml, model/backlog/epics.yaml, model/template-parameters/connectsoft-library.yaml, docs/architecture/adr/0028-one-repository-and-deployable-per-service.md |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-1048 Template pipeline manifest with the default and the Factory profile case, and the pairwise matrix in the scaffold tests |
operations | The library template adopts the shared template pipeline: build/template-ci.json names its identity, solution, packaging and tests and declares the default case and one additional gating case that generates with UseFactoryProfile true, the single framework, dependency injection, options and the activity source sample; azure-pipelines-template.yml runs the shared installer jobs on it; the scaffold test project defines the matrix of the five feature switches, UseFactoryProfile and the target-framework choices as a pairwise set of tests, each of which restores, builds, tests, reads the manifest back and scans for placeholders. |
ConnectSoft.LibraryTemplate |
AIFACTORY-TASK-1061 Library template as a consumer of the shared template pipeline |
operations | The rollout ledger of the shared template pipeline, template-ci/rollout-status.md, gains the row of the library template, and the installer self-tests of template-ci/v1 gain a consumer fixture of a class library template: the template artifact kind only, no required service, the default case and one additional gating case of a declared profile; the fixture passes in the Windows and Linux jobs of the shared pipeline. |
ConnectSoft.AzurePipelines |
AIFACTORY-TASK-1049 Planted failing output fixture for the gate |
fixture | A pipeline fixture generates the Factory profile case with a planted compile defect and asserts that the run fails at the build stage with the case named and that publication is not reached. | ConnectSoft.LibraryTemplate |
AIFACTORY-TASK-1050 Publication on the complete reports of both gating cases and green scaffold tests, with the version guard |
operations | Publication of the template pipeline requires the complete reports of the default case and of the Factory profile case, bound to the candidate, and green scaffold tests, pushes the template package to the ConnectSoft feed with a verified version and refuses a version that is already on the feed with the reason; a failed gating case or a failed scaffold test skips publication. | ConnectSoft.LibraryTemplate |
AIFACTORY-TASK-649 ConnectSoft feed publication and a generated-solution gate |
verification | One green run and one planted run of the gate: the shared installer jobs generate the default case and the Factory profile case from the packed template, the scaffold tests instantiate it across the parameter matrix (UseDI, UseLogging, UseOptions, UseMetrics, UseActivitySource, UseFactoryProfile and the target-framework choices), each output is built and tested before the package publishes, and the package reaches the feed only on the green run, which proves AC1 to AC3 of AIFACTORY-US-218 (ADR-0028). | ConnectSoft.LibraryTemplate |
AIFACTORY-US-113: Library template: target frameworks, a manifest and Factory diagnostics for generated libraries is delivered and proven on a generated solution¶
enabling · persona asset-maintainer
As an asset maintainer, I want Library template to carry target frameworks, a manifest and Factory diagnostics for generated libraries, so that it serves the contracts package, the gateway client packages and every Backend Library module of a generated product without later rework.
This is the integration PBI of the feature. An asset maintainer packs the library template with the target-frameworks parameter, the manifest and the symbol catalog, the diagnostics samples on the Factory names, the symbol UseFactoryProfile, the generated pipeline that publishes to the ConnectSoft feed and the alignment checklist as the default; the shared template pipeline installs the package and gates the default generation and one Factory profile case, and the scaffold tests instantiate it across the parameter matrix. Every gating case and every output of the matrix builds and passes its tests before the template package is allowed to publish with a verified version; one that fails any stage fails the run and blocks publication. The implementation lives in the earlier PBIs of this file; this PBI proves them together on the library the Factory generates first. From the published package a library in the shape of the contracts package is generated, with UseFactoryProfile true, the activity source sample on and the single framework passed beside it; its manifest names the template, the version and the parameter values; its pipeline, generated with the feed default of the template and no feed passed, publishes the package, the symbols and an SBOM to the ConnectSoft feed, which is the Factory feed; its samples carry the diagnostics names, the scope tags and no payload; and it meets the alignment checklist without a change. The feature is done when that library is on the feed from its first pipeline run. Repository of the feature: ConnectSoft.LibraryTemplate. The contracts package, the gateway client packages and the backend library modules of a generated product are scaffolded from the package in this and in later increments.
Acceptance criteria
| AC1 | Given the template repository ConnectSoft.LibraryTemplate, when the template is packed, installed and instantiated in its pipeline, then the generated solution of every case builds and its tests pass before the package publishes with a verified version (ADR-0028, model/components.yaml). |
| AC2 | Given the work of AIFACTORY-TASK-647 (target frameworks as a parameter of the generated library) and of the manifest tasks of AIFACTORY-US-215 is done, then one parameter sets the target frameworks of a generated library, the generated repository carries a preserved manifest with the template id, the template version and the chosen parameter values, the package exports a symbol catalog, and the scaffold tests read the manifest back (ADR-0001, ADR-0027, ADR-0028, model/template-parameters/connectsoft-library.yaml). |
| AC3 | Given the work of AIFACTORY-TASK-648 (samples on the Factory diagnostics conventions) is done, then the metrics and ActivitySource samples use the meter and activity-source naming under the connectsoft. prefix, the scope tags under UseFactoryProfile and the no-payload rule, so a library generated for the Factory starts on the conventions without a later rename, and the library hosts no ASP.NET Core endpoints (ADR-0019, ADR-0028, docs/architecture/ecosystem-composition.md). |
| AC4 | Given the work of AIFACTORY-TASK-649 (ConnectSoft feed publication and a generated-solution gate) is done, then the generated pipeline produces the build, tests, coverage, analysis, scan, SBOM and packages results of rule PIPE-001 and publishes the package to the ConnectSoft feed with a verified version and symbols, the alignment checklist of the Alignment page of the template is the generated default, and the shared template pipeline gates the default generation and one Factory profile case while the scaffold tests instantiate the packed template across the parameter matrix and build and test each output before the package publishes (ADR-0028, model/blueprints.yaml). |
| Traces: adrs | ADR-0001, ADR-0019, ADR-0027, ADR-0028 |
| Depends on | AIFACTORY-US-214, AIFACTORY-US-215, AIFACTORY-US-216, AIFACTORY-US-217, AIFACTORY-US-218 |
| Sources | model/components.yaml, model/templates.yaml, model/blueprints.yaml, model/template-parameters/connectsoft-library.yaml |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-1051 Generate the contracts package shape from the published template and publish it to a test feed |
verification | A probe installs the published template package and generates the Factory profile case, a library with UseFactoryProfile true, the single framework, dependency injection, options and the activity source sample, once without a feed parameter and once with a test feed passed for the probe run only; the pipeline file of the first names the ConnectSoft feed, the generated pipeline of the second runs against the test feed, and the probe checks the manifest, the diagnostics names, the scope tags and the alignment checklist; the run proves AC2 to AC4 of AIFACTORY-US-113 (ADR-0028). |
ConnectSoft.LibraryTemplate |
AIFACTORY-TASK-684 Verify library-template-factory-profile-delivered by running the declared command |
verification | Run dotnet build -c Release and dotnet test -c Release --no-build on the authoring solution and on every output of the parameter matrix after the published package is installed; they pass and prove AC1 to AC4 of AIFACTORY-US-113. |
ConnectSoft.LibraryTemplate |