AIFACTORY-FEAT-138: Demonstrate I0: Readiness¶
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 Outcome verification · Increment I0 Readiness · State elaborated · Route qa-engineer · Build order 50 of 185 (Factory code)
The outcome of increment I0 is demonstrated end to end and the evidence is recorded: Every repository of the first outcome scaffolds from its template and builds, and one call chain carries a trusted tenant and project scope from the edge to a service. Demonstrations: Each first-outcome repository exists, builds and runs its template tests in its pipeline. A request with a token of the Identity Platform reaches a service with tenant and project scope, and a request without scope is refused. The contracts package is published and consumed by two services.
| Delivers | — |
| Stubs | — |
| Realizes | — |
| Requirements | — |
| Depends on | — |
| Sources | model/backlog/increments.yaml |
AIFACTORY-US-1336: Readiness proof: every repository of the first outcome is scaffolded from the template of its kind and passes its template tests in its own pipeline¶
evidence · persona operator
As an operator, I want a recorded run in which every repository of the first outcome is created, scaffolded and built by its own pipeline, so that the first outcome starts from repositories that are known to build and test before any Factory code is written.
This PBI proves the first demonstration of increment I0: each first-outcome repository exists, builds and runs its template tests in its pipeline. An operator takes the list of first-outcome repositories from the services the increment page docs/backlog/increments/generate-a-microservice.md names, one repository and one deployable per service as ADR-0028 decision 1 requires, and checks each one against the checklist of the feature repository-and-pipeline-conventions: the name ConnectSoft.AI.SoftwareFactory.<ServiceId>, the template of its kind scaffolded with the Factory profile switch of that template, the branch policy, and a pipeline built from the shared pipeline templates that builds, tests and packs with no script of its own. The run is recorded, not asserted: each repository has the identifier of one green pipeline run on its default branch, the version of the template it was scaffolded from and the result of the conformance check that reports every name, template, pipeline and feed deviation. A repository that is missing, does not build or deviates is recorded by name with the failing check; it blocks the readiness proof and is never waived by this feature. The proof exercises only the I0 work it depends on and adds no repository of its own. Every repository of the list is created in I0 by feature repository-and-pipeline-conventions (D140): RunControlService by AIFACTORY-TASK-190, ControlPlaneApi by AIFACTORY-TASK-1514, AgentRuntimeService by AIFACTORY-TASK-146 of the durable execution spike, and the thirty repositories of the I1 features by the tasks of AIFACTORY-US-1596 to AIFACTORY-US-1601, grouped by plane and with their identifiers kept; none of them waits for its I1 feature, so the demonstration can pass in I0, and a first-outcome repository that a task of an I1 feature would still have to create is a gap that blocks this proof.
Acceptance criteria
| AC1 | Given the services the increment page docs/backlog/increments/generate-a-microservice.md lists for the first outcome, when the operator compares them with the repositories of the organisation, then each service has exactly one repository named after it and scaffolded from the template of its kind with the Factory profile switch, and the list with the template version of each repository is recorded (ADR-0028 decision 1). |
| AC2 | Given each repository of that list, when its pipeline runs on the default branch, then it restores from the ConnectSoft feed, builds in Release and passes the tests the template generated, and the identifier of the green run is recorded beside the repository (ADR-0028). |
| AC3 | Given the conformance check of the feature repository-and-pipeline-conventions, when it runs over every repository of the list, then it reports no deviation of name, template, pipeline or feed, and a repository with a deviation is recorded by name and blocks the readiness proof instead of being waived (ADR-0028, docs/architecture/adr/0028-one-repository-and-deployable-per-service.md). |
| AC4 | Given the repository list, when each row is compared with the task that created it, then every first-outcome repository was created in I0 by a task of feature repository-and-pipeline-conventions, AIFACTORY-TASK-190, AIFACTORY-TASK-1514, AIFACTORY-TASK-146 or a task of AIFACTORY-US-1596 to AIFACTORY-US-1601, and none is left to an I1 feature (ADR-0028 decision 1, D140, model/backlog/pbis/engineering-readiness/repository-and-pipeline-conventions.yaml). |
| Traces: adrs | ADR-0028 |
| Depends on | feature:repository-and-pipeline-conventions, feature:durable-execution-spike |
| Sources | model/backlog/increments.yaml, model/backlog/pbis/engineering-readiness/repository-and-pipeline-conventions.yaml, docs/backlog/increments/generate-a-microservice.md, docs/architecture/adr/0028-one-repository-and-deployable-per-service.md |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-5381 Repository list of the first outcome with template versions |
documentation | A recorded list of every first-outcome repository with the service it holds, the template of its kind, the template version, the Factory profile switch it was scaffolded with and the I0 task of feature repository-and-pipeline-conventions that created it (AIFACTORY-TASK-190, AIFACTORY-TASK-1514, AIFACTORY-TASK-146 or a task of AIFACTORY-US-1596 to AIFACTORY-US-1601, D140), taken from docs/backlog/increments/generate-a-microservice.md and checked against the repositories of the organisation. |
ConnectSoft.AI.SoftwareFactory.Documentation |
AIFACTORY-TASK-5382 Green pipeline run and conformance result per first-outcome repository |
operations | For every repository of the list one green pipeline run on the default branch that restores from the ConnectSoft feed, builds in Release and runs the template tests, and one run of the conformance check of the feature repository-and-pipeline-conventions with no deviation; each run identifier is recorded beside its repository. |
ConnectSoft.AI.SoftwareFactory.Documentation |
AIFACTORY-TASK-5383 Verify the repository proof against its criteria |
verification | The recorded list, the run identifiers and the conformance results are compared with AC1 to AC4 of AIFACTORY-US-1336: every service of docs/backlog/increments/generate-a-microservice.md has a repository created by an I0 task of feature repository-and-pipeline-conventions, a green run and no deviation, and python -I tools/docs_model check passes on the evidence page. |
ConnectSoft.AI.SoftwareFactory.Documentation |
AIFACTORY-US-1337: Readiness proof: a token of the Identity Platform carries tenant and project scope through the control plane gateway to a service, and a call without scope is refused¶
evidence · persona operator
As an operator, I want a recorded call chain in which a scoped call reaches a service with the scope its token grants and every unscoped call is refused, so that no Factory service of the first outcome is built on a scope a caller merely claims.
This PBI proves the second demonstration of increment I0: a request with a token of the Identity Platform reaches a service with tenant and project scope, and a request without scope is refused. A member of a project signs in with the command-line client against the Factory instance of the Identity Platform, by the authorization code flow with PKCE, and calls the control plane gateway in the acceptance environment. The gateway establishes tenant and project once from the validated token and forwards them together with the unchanged user token to the probe service it fronts, which reads them from the scope accessor of the pinned Factory abstractions package (ADR-0015 decision 2, descriptor execution-scope-v1). The refusals are those ADR-0015 and its amendments decide: a call without a token or with the token of another audience is answered 401 by the gateway, a token without the scope or project the operation names is answered 403, and a resource of another tenant is answered 404, never 403, so the answer does not confirm that the resource exists. That last refusal has two cases: a route that addresses another tenant by its tenant identifier is answered 404 by the gateway, NOT_FOUND over gRPC, and nothing is forwarded; a resource identifier of another tenant is forwarded under the tenant of the caller and answered 404 by the tenant row filter of the probe service. A typed tenant or project header changes nothing. The proof records the trace identifier of each call, the answer and what the probe service logged; it relies on the refusal matrix of the feature trusted-scope-chain and does not restate it.
Acceptance criteria
| AC1 | Given a member signed in with the command-line client against the Factory instance of the Identity Platform, when the member calls the control plane gateway for a project the token grants, then the probe service reads from the scope accessor the tenant of the token and the project of the route, both equal what the token grants, and the trace identifier of the call is recorded (ADR-0015 decision 2, FR-01, descriptor execution-scope-v1). |
| AC2 | Given the same gateway, when a call arrives without a token, with the token of another audience or for a project the token does not grant, then the gateway answers 401 or 403, the probe service records no call, and each refusal is recorded with its trace identifier (ADR-0015 decision 3, FR-01). |
| AC3 | Given two tenants with one resource each in the probe service, when a member of the first tenant addresses the second tenant by its tenant identifier in a route, then the gateway answers 404, NOT_FOUND over gRPC, and the probe service records no call; and when the member requests the resource identifier of the second tenant, then the call is forwarded under the tenant of the caller and the probe service answers 404 with the body of an unknown identifier, never 403, and a typed tenant or project header changes nothing (ADR-0015 amendment on a resource of another tenant; docs/architecture/adr/0015-factory-tenancy-under-canonical-adr-0100.md). |
| Traces: descriptors | execution-scope-v1 |
| Traces: adrs | ADR-0015 |
| Traces: requirements | FR-01 |
| Depends on | feature:trusted-scope-chain, feature:command-line-client, feature:local-development-environment |
| Sources | model/backlog/increments.yaml, docs/architecture/adr/0015-factory-tenancy-under-canonical-adr-0100.md |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-5384 Scoped and unscoped calls through the running gateway in the acceptance environment |
operations | A replayable sequence of calls in the acceptance environment: a sign-in of a project member with the command-line client, a scoped call through the control plane gateway, a call without a token, a call with the token of another audience, a call for an ungranted project, a route that addresses another tenant by its tenant identifier (answered 404 by the gateway, NOT_FOUND over gRPC, with no call on the probe service) and a call for the resource identifier of another tenant, each with its trace identifier, answer and the log line of the probe service. | ConnectSoft.AI.SoftwareFactory.Documentation |
AIFACTORY-TASK-5385 Two-tenant fixture of the scope demonstration |
fixture | Two tenants of the Factory instance of the Identity Platform, one member each with a role in one project, and one resource per tenant in the probe service, created from documented steps so that the scope demonstration can be replayed on a fresh acceptance environment. | ConnectSoft.AI.SoftwareFactory.Documentation |
AIFACTORY-TASK-5386 Verify the scope proof against its criteria |
verification | The recorded answers and probe-service logs are compared with AC1 to AC3 of AIFACTORY-US-1337: the scoped call carries the granted scope, the 401 and 403 refusals leave no call on the probe service, a route naming another tenant is answered 404 by the gateway with no call on the probe service, and the resource identifier of another tenant is answered 404 under the tenant of the caller (ADR-0015, FR-01). | ConnectSoft.AI.SoftwareFactory.Documentation |
AIFACTORY-US-1338: Readiness proof: the contracts package is on the ConnectSoft feed and two services build against the same version and exchange one run event envelope¶
evidence · persona operator
As an operator, I want a recorded proof that two services pin the same published version of the contracts package and read each other's envelope, so that no Factory service of the first outcome copies a contract.
This PBI proves the third demonstration of increment I0: the contracts package is published and consumed by two services. The feature contracts-package publishes the package to the ConnectSoft feed and records its version on docs/reference/schemas/index.md, and its probe consumer restores it from the feed alone; the feature leaves the demonstration with two consuming services to this proof. The two services are the probe service behind the control plane gateway and the second service of the scope chain of the feature trusted-scope-chain, whose handler reads the scope from the envelope. The operator records the version each service pins, the restore of each from the ConnectSoft feed with no project reference, and one event that the first service writes in the run event envelope run-event-envelope-v1 of the package and the second handles with the same tenant and project. A service that pins another version, restores the package from a local source or defines a contract type of its own fails the proof and is recorded by name. The proof adds no type to the package and changes neither service.
Acceptance criteria
| AC1 | Given the version of the contracts package recorded on docs/reference/schemas/index.md, when the pins of the probe service and of the handler service are read, then both pin that version, both restore it from the ConnectSoft feed with no project reference, and neither defines a contract type the package holds (ADR-0028, ADR-0014). |
| AC2 | Given a scoped call that reaches the probe service, when it publishes an event in the run event envelope run-event-envelope-v1 of the package, then the handler service reads the same tenant and project from the envelope through its scope accessor, and the event identifier and both build run identifiers are recorded (ADR-0014 decision 1). |
| AC3 | Given a planted pin of another version in one of the two services, when the proof is replayed, then the comparison fails and names the service and the version, which shows that the proof would catch a drift (ADR-0028). |
| Traces: descriptors | run-event-envelope-v1 |
| Traces: adrs | ADR-0014, ADR-0028 |
| Depends on | feature:contracts-package, feature:trusted-scope-chain |
| Sources | model/backlog/increments.yaml, docs/reference/schemas/index.md, docs/architecture/adr/0014-run-and-lifecycle-envelopes.md |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-5387 Pins, restores and one exchanged envelope of the two consuming services |
operations | The recorded pins of the contracts package in the probe service and the handler service, the build run of each that restored it from the ConnectSoft feed alone, and one event written by the probe service in run-event-envelope-v1 and handled by the handler service with the same tenant and project, each with its identifier. |
ConnectSoft.AI.SoftwareFactory.Documentation |
AIFACTORY-TASK-5388 Verify the consumer proof against its criteria |
verification | The recorded pins, restores and envelope are compared with AC1 to AC3 of AIFACTORY-US-1338 and with the version on docs/reference/schemas/index.md; a replay with a planted pin of another version fails and names the service. | ConnectSoft.AI.SoftwareFactory.Documentation |
AIFACTORY-US-004: Readiness is demonstrated with evidence¶
evidence · persona operator
As an operator, I want to see the three readiness demonstrations pass and their evidence recorded, so that the first outcome starts from a foundation that is known to work.
This is the integration PBI of the feature and the closing proof of increment I0. Increment I0 is finished when this proof passes, not when its features are accepted one by one: every repository of the first outcome scaffolds from its template and builds, and one call chain carries a trusted tenant and project scope from the edge to a service, as model/backlog/increments.yaml states the outcome. An operator replays the three demonstrations of AIFACTORY-US-1336, AIFACTORY-US-1337 and AIFACTORY-US-1338 in one recorded acceptance run on the acceptance environment, so that the evidence of each comes from the same estate, and records an evidence pack: the repository list with its pipeline run identifiers, every repository of it created in I0 by feature repository-and-pipeline-conventions, the thirty of the I1 features by AIFACTORY-US-1596 to AIFACTORY-US-1601 (D140), the trace identifiers of the scoped and refused calls, and the package version with the pins of the two consuming services. The pack is the evidence the epic outcome-verification names in its done_when for I0, and the done_when of the epic engineering-readiness, which closes on the readiness demonstration, reads it. A demonstration that fails is recorded with its failing step and the increment stays open; nothing is waived.
Acceptance criteria
| AC1 | Given the first-outcome repositories, all created in I0 by feature repository-and-pipeline-conventions (D140), when each pipeline runs in the recorded acceptance run, then every one is green and the list with its run identifiers and the I0 task that created each repository is in the evidence pack, as AIFACTORY-US-1336 proves it (ADR-0028). |
| AC2 | Given a token of the Identity Platform, when a scoped call and an unscoped call are made in the same run, then the first reaches the service with the granted scope, the second is refused, and both trace identifiers are in the evidence pack, as AIFACTORY-US-1337 proves it (ADR-0015). |
| AC3 | Given the contracts package, when the two consuming services are built in the same run, then both build against the same published version and exchange one run event envelope, and the version and pins are in the evidence pack, as AIFACTORY-US-1338 proves it (ADR-0014). |
| AC4 | Given the evidence pack, when it is reviewed against the outcome of I0 in model/backlog/increments.yaml and the done_when of the epics outcome-verification and engineering-readiness in model/backlog/epics.yaml, then every demonstration has its evidence and a failed one is recorded with its failing step instead of being waived (ADR-0029). |
| Traces: adrs | ADR-0014, ADR-0015, ADR-0028, ADR-0029 |
| Depends on | AIFACTORY-US-1336, AIFACTORY-US-1337, AIFACTORY-US-1338 |
| Sources | model/backlog/increments.yaml, model/backlog/epics.yaml |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-193 Run the three demonstrations and record the evidence |
documentation | An evidence page with pipeline run identifiers, trace identifiers and package versions from one recorded acceptance run of the three demonstrations of AIFACTORY-US-1336, AIFACTORY-US-1337 and AIFACTORY-US-1338. | ConnectSoft.AI.SoftwareFactory.Documentation |
AIFACTORY-TASK-184 Evidence pack for increment I0 |
documentation | A recorded run of every demonstration below with its run identifiers, artifacts and logs: Each first-outcome repository exists, builds and runs its template tests in its pipeline. A request with a token of the Identity Platform reaches a service with tenant and project scope, and a request without scope is refused. The contracts package is published and consumed by two services. | ConnectSoft.AI.SoftwareFactory.Documentation |
AIFACTORY-TASK-777 Verify readiness-demonstrated against the recorded acceptance run |
verification | The evidence pack is compared with AC1 to AC4 of AIFACTORY-US-004 and with the outcome of I0 in model/backlog/increments.yaml; every demonstration has its run identifiers, and python -I tools/docs_model validate passes with the evidence page in place. |
ConnectSoft.AI.SoftwareFactory.Documentation |