AIFACTORY-FEAT-141: Demonstrate I3: Studio¶
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 I3 Studio · State elaborated · Route qa-engineer · Build order 123 of 185 (Factory code)
The outcome of increment I3 is demonstrated end to end and the evidence is recorded: The same chain is submitted, watched and decided in Factory Studio. Demonstrations: A requester submits a run and follows it live in the Studio. A reviewer decides approvals from the approval inbox. Every work area renders from the platform read models through the backend-for-frontend.
| Delivers | — |
| Stubs | — |
| Realizes | — |
| Requirements | — |
| Depends on | — |
| Sources | model/backlog/increments.yaml |
AIFACTORY-US-1345: Studio proof: a requester submits the vision of the first outcome in the Studio and follows the run live to its change proposal¶
evidence · persona requester
As a requester, I want to submit the vision of the first outcome from the Studio and watch the run progress without reloading, so that the Studio replaces the command-line client for the chain of the first outcome.
This PBI proves the first demonstration of increment I3: a requester submits a run and follows it live in the Studio. The requester signs in to the Studio, chooses the project in the scope switcher and submits the fixture vision brief of the proof of I1 on the screen run-submit of the Workspace work area. The Studio front end calls only the backend-for-frontend: StudioBff forwards the submission through ForwardCommand with the user token of the requester to SubmitRun of RunControlService, and the scope of the call is the scope of the token, never a value the page typed. The screen run-detail then follows the run live: it subscribes through Realtime.Subscribe of StudioRealtimeGateway, and the state changes that RunControlService records reach the open page without a reload through the stream bridge of StudioRealtimeGateway, until the chain of six workflows ends with the open change proposal. The gateway does not consume RunStateChanged itself; StudioBff does, and the proof compares the states the page showed with the RunStateChanged records of RunControlService. A dropped realtime connection is resumed and the page catches up from the screen model of StudioBff without losing a state. The proof records the run identifier, the sequence of states the page showed beside the states RunControlService recorded, and the reference of the change proposal.
Acceptance criteria
| AC1 | Given a requester signed in to the Studio with the project chosen, when the requester submits the fixture vision brief on the screen run-submit, then StudioBff forwards it with the user token of the requester and RunControlService accepts the run in the scope of that token, and the run identifier is recorded (StudioBff/ForwardCommand, RunControlService/SubmitRun, FR-12). |
| AC2 | Given the screen run-detail open on that run, when RunControlService records each state change of the chain of six workflows, then the change reaches the page without a reload through the stream bridge of StudioRealtimeGateway and its realtime subscription, and the states the page showed equal the RunStateChanged records of RunControlService (StudioRealtimeGateway/Realtime.Subscribe, RunControlService/RunStateChanged). |
| AC3 | Given the realtime connection is dropped while the run is in progress, when it is resumed, then the page catches up from the screen model of StudioBff and shows no gap in the states, and the run ends on the screen with the reference of its open change proposal (StudioBff/GetScreenModel). |
| Traces: services | StudioBff, StudioRealtimeGateway, RunControlService |
| Traces: apis | StudioBff/ForwardCommand, StudioBff/GetScreenModel, StudioRealtimeGateway/Realtime.Subscribe, RunControlService/SubmitRun |
| Traces: events | RunControlService/RunStateChanged |
| Traces: requirements | FR-12 |
| Relates: screens | run-submit, run-detail |
| Depends on | feature:verify-generate-a-microservice, feature:studio-bff, feature:studio-realtime-gateway, feature:studio-workspace, feature:component-blazor-shell-template-studio, feature:run-control-service |
| Sources | model/backlog/increments.yaml, model/services/factory-studio/StudioBff.yaml, model/services/factory-studio/StudioRealtimeGateway.yaml |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-5404 Submission and live follow of one run in the Studio |
operations | One recorded session in the Studio on the acceptance environment: the submission of the fixture vision brief on run-submit, the run identifier, the states shown on run-detail beside the states RunControlService recorded, one dropped and resumed realtime connection and the reference of the change proposal at the end. |
ConnectSoft.AI.SoftwareFactory.Documentation |
AIFACTORY-TASK-5405 Verify the submit and follow proof against its criteria |
verification | The recorded session is compared with AC1 to AC3 of AIFACTORY-US-1345 (StudioBff/ForwardCommand, StudioRealtimeGateway/Realtime.Subscribe, RunControlService/RunStateChanged); a state recorded by RunControlService that the page did not show fails the check. | ConnectSoft.AI.SoftwareFactory.Documentation |
AIFACTORY-US-1346: Studio proof: a reviewer is notified and decides the approvals of the run from the approval inbox, each decision bound to the exact proposal version¶
evidence · persona reviewer
As a reviewer, I want to decide the approvals of a run from the inbox of the Studio on the exact version I was shown, so that no decision of mine applies to a proposal I did not see.
This PBI proves the second demonstration of increment I3: a reviewer decides approvals from the approval inbox. When the run of AIFACTORY-US-1345 reaches the step that approves the change set, RunControlService opens an approval request bound to the proposal hash with the role Reviewer in project scope as approver rule. StudioNotificationService notifies the eligible reviewer, which NotificationCreated records, and the request appears on the screen approvals-list of the Workspace work area. The reviewer opens it on approval-card, sees the proposal version and its evidence, and decides; StudioBff forwards the decision through ForwardCommand with the user token of the reviewer to DecideApproval, quoting the request version, and RunControlService records it, which ApprovalDecided carries. The refusals are the decided ones: a decision by the requester of the run is answered 403, and a decision on a request that went Stale because the proposal was regenerated, or that another decision already settled, is answered 409; in each case the request keeps its state and the Studio shows the answer. The proof records each decision with the proposal hash it names.
Acceptance criteria
| AC1 | Given the approval request of the run, when it is opened, then the eligible reviewer is notified and the request is listed on the screen approvals-list with its proposal version (StudioNotificationService/NotificationCreated, RunControlService/ApprovalRequested). |
| AC2 | Given the reviewer opens the request on approval-card, when the reviewer approves it, then StudioBff forwards the decision with the request version, RunControlService records it bound to the proposal hash the card showed, and the run continues (StudioBff/ForwardCommand, RunControlService/DecideApproval, RunControlService/ApprovalDecided, FR-06). |
| AC3 | Given the requester of the run, or a request that went Stale or was already decided, when a decision is sent from the Studio, then RunControlService answers 403 for the requester and 409 for the stale or settled request, the request keeps its state and the Studio shows the answer (RunControlService/DecideApproval, ADR-0015). |
| Traces: services | StudioBff, StudioNotificationService, RunControlService |
| Traces: apis | StudioBff/ForwardCommand, RunControlService/DecideApproval |
| Traces: events | StudioNotificationService/NotificationCreated, RunControlService/ApprovalRequested, RunControlService/ApprovalDecided |
| Traces: adrs | ADR-0015 |
| Traces: requirements | FR-06 |
| Relates: screens | approvals-list, approval-card |
| Depends on | AIFACTORY-US-1345, feature:studio-bff, feature:studio-notification-service, feature:studio-workspace, feature:run-control-service |
| Sources | model/backlog/increments.yaml, model/services/control-plane/RunControlService.yaml, model/services/factory-studio/StudioNotificationService.yaml |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-5406 Inbox decisions and refusals of the run approvals in the Studio |
operations | One recorded reviewer session on the acceptance environment: the notification, the request on approvals-list, the approving decision on approval-card with the proposal hash it names, and the refused decisions of the requester (403) and on a stale request (409) with the answer the Studio showed. |
ConnectSoft.AI.SoftwareFactory.Documentation |
AIFACTORY-TASK-5407 Verify the inbox proof against its criteria |
verification | The recorded decisions and refusals are compared with AC1 to AC3 of AIFACTORY-US-1346 (StudioNotificationService/NotificationCreated, RunControlService/DecideApproval, RunControlService/ApprovalDecided); a decision bound to another hash than the one shown fails the check. | ConnectSoft.AI.SoftwareFactory.Documentation |
AIFACTORY-US-1347: Studio proof: every screen of the seven work areas renders from the platform read models through the backend-for-frontend for every Factory role¶
evidence · persona observer
As an observer, I want every work area of the Studio to render from the read models of the platform for my role, so that the Studio shows the state of the Factory and never a mock or a direct call around the backend-for-frontend.
This PBI proves the third demonstration of increment I3: every work area renders from the platform read models through the backend-for-frontend. The Studio has seven work areas: Workspace, Software Factory, Assets, Intelligence, Quality & releases, Operations & usage, and Governance & administration, with the screens model/ux/screens.yaml lists. A render check signs in once with each of the seven Factory roles. Each screen of model/ux/screens.yaml has its own roles list, so for each role the check opens the screens whose list names that role and asserts that they render, and for each screen whose list does not name the role it asserts that the screen is not offered and that GetScreenModel refuses it with 403; run-submit, for example, is offered to a Requester only. For each screen that renders it asserts that the page renders from the screen model GetScreenModel of StudioBff, that the browser called no address other than StudioBff and StudioRealtimeGateway, that the screen shows the state families of model/ux/states.yaml from real read models and never from a mock, and that the actions a role may not take are not offered to it, as the observer persona of model/ux/personas.yaml asks. A screen whose source is not yet delivered in I3 shows that source as degraded or unknown in the freshness family, never hidden, and is listed by name. The record of the check, per role and per screen, is the evidence; a screen that fails to render or calls a service directly fails the proof.
Acceptance criteria
| AC1 | Given the screens of model/ux/screens.yaml with their roles lists, when the render check signs in with each of the seven Factory roles, then every screen whose list names the role renders from the screen model of StudioBff, every screen whose list does not name it is not offered and GetScreenModel refuses it with 403, and the record holds one line per role and screen with the expected and the observed result (StudioBff/GetScreenModel, FR-12). |
| AC2 | Given the network log of the render check, when it is read, then the browser called no address other than StudioBff and StudioRealtimeGateway, and no screen rendered from a mock or a static fallback (StudioBff/GetScreenModel, StudioRealtimeGateway/Realtime.Subscribe). |
| AC3 | Given a role without the right to an action of a screen, when the screen renders for that role, then the action is not offered, and a screen whose source is not delivered in I3 shows that source as degraded or unknown in the freshness family of model/ux/states.yaml and is listed by name (StudioBff/GetStudioSession, FR-12). |
| Traces: services | StudioBff, StudioRealtimeGateway |
| Traces: apis | StudioBff/GetScreenModel, StudioBff/GetStudioSession, StudioRealtimeGateway/Realtime.Subscribe |
| Traces: requirements | FR-12 |
| Depends on | feature:studio-bff, feature:studio-realtime-gateway, feature:studio-workspace, feature:studio-software-factory, feature:studio-assets, feature:studio-intelligence, feature:studio-quality-releases, feature:studio-operations-usage, feature:studio-governance-administration, feature:component-blazor-shell-template-studio |
| Sources | model/backlog/increments.yaml, model/ux/screens.yaml, model/services/factory-studio/StudioBff.yaml |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-5408 Render check over every screen and role |
fixture | A browser-driven render check in the Studio repository that signs in with each of the seven Factory roles, opens the screens of model/ux/screens.yaml whose roles list names the role and records the state each rendered, the screen model it read, the addresses the browser called and the actions it showed, asserts for every other screen that it is not offered and that GetScreenModel answers 403, and fails on a direct service call, a mock, or a screen rendered for a role its list does not name. |
ConnectSoft.AI.SoftwareFactory.Studio |
AIFACTORY-TASK-5409 Render check run on the acceptance environment |
operations | One run of the render check against the acceptance environment with its record per role and screen, the network log and the list of screens that showed a degraded or unknown source, kept with the evidence of increment I3. | ConnectSoft.AI.SoftwareFactory.Documentation |
AIFACTORY-TASK-5410 Verify the render proof against its criteria |
verification | The record of the render check is compared with AC1 to AC3 of AIFACTORY-US-1347 and with the screens of model/ux/screens.yaml; every screen has a line for every role with its expected result, rendered where the roles list names the role and refused with 403 where it does not, and no line names a direct service call or a mock (StudioBff/GetScreenModel). |
ConnectSoft.AI.SoftwareFactory.Documentation |
AIFACTORY-US-040: The Studio outcome is demonstrated with evidence¶
evidence · persona operator
As an operator, I want to see the chain of the first outcome submitted, followed and decided in the Studio, with the evidence recorded, so that the third outcome is accepted on facts.
This is the integration PBI of the feature and the closing proof of increment I3. The outcome of I3, as model/backlog/increments.yaml states it, is that the same chain as the first outcome is submitted, watched and decided in Factory Studio. The increment is finished when this proof passes, not when the Studio is deployed. An operator replays the three demonstrations in one recorded acceptance run: the requester submits the fixture vision brief and follows the run live of AIFACTORY-US-1345, the reviewer decides its approvals from the inbox of AIFACTORY-US-1346, and the render check of every work area for every role of AIFACTORY-US-1347 runs on the same estate. The evidence pack holds the run identifier, the states shown and recorded, the decisions with the proposal hashes they name, and the record of the render check. The done_when of the epic factory-studio reads this proof as the outcome verification of I3, together with the epics agent-mesh and template-library whose done_when name I3. A demonstration that fails is recorded with its failing step and the increment stays open; nothing is waived.
Acceptance criteria
| AC1 | Given a requester in the Studio, when they submit a vision in the recorded acceptance run, then the run is followed live to its change proposal and the run identifier is in the evidence, as AIFACTORY-US-1345 proves it (StudioBff, StudioRealtimeGateway, RunControlService). |
| AC2 | Given the approvals of that run, when a reviewer decides them from the inbox, then each decision names the exact proposal version, as AIFACTORY-US-1346 proves it (StudioNotificationService, RunControlService). |
| AC3 | Given the seven work areas, when the render check runs with every role, then its record is part of the evidence, as AIFACTORY-US-1347 proves it (StudioBff). |
| AC4 | Given the evidence pack, when it is reviewed against the outcome of I3 in model/backlog/increments.yaml and the done_when of the epic outcome-verification in model/backlog/epics.yaml, then every demonstration has its evidence or its recorded failure (ADR-0029). |
| Traces: services | StudioBff, StudioRealtimeGateway, StudioNotificationService, RunControlService |
| Traces: workflows | vision-to-blueprint, generate-product |
| Traces: adrs | ADR-0029 |
| Depends on | AIFACTORY-US-1345, AIFACTORY-US-1346, AIFACTORY-US-1347 |
| Sources | model/backlog/increments.yaml, model/backlog/epics.yaml |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-536 Run the three demonstrations and record the evidence |
documentation | An evidence page with the run identifiers, the approval decisions with their proposal hashes and the render record, from one recorded acceptance run of AIFACTORY-US-1345, AIFACTORY-US-1346 and AIFACTORY-US-1347. | ConnectSoft.AI.SoftwareFactory.Documentation |
AIFACTORY-TASK-507 Evidence pack for increment I3 |
documentation | A recorded run of every demonstration below with its run identifiers, artifacts and logs: A requester submits a run and follows it live in the Studio. A reviewer decides approvals from the approval inbox. Every work area renders from the platform read models through the backend-for-frontend. | ConnectSoft.AI.SoftwareFactory.Documentation |
AIFACTORY-TASK-778 Verify studio-demonstrated against the recorded acceptance run |
verification | The evidence pack is compared with AC1 to AC4 of AIFACTORY-US-040 and with the outcome of I3 in model/backlog/increments.yaml; every demonstration has its evidence, and python -I tools/docs_model validate passes with the evidence page in place. |
ConnectSoft.AI.SoftwareFactory.Documentation |