ADR-0029: The build backlog is a model kind — outcome increments, structural epics, a rolling wave of stories¶
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 D75–D77); amended by D80–D85 (order of increments confirmed, stub register accepted with two changes, Scrum type names, the second increment elaborated, the Draft waiver, three definitions moved into the second increment, no area path); amended by D111 (PBIs, scenario catalog, ratchet) and D138 to D141 (campaign closed,
final: true) - Date: 2026-11-05
- Deciders: Dmitry Khaymov (product owner)
- Tags: backlog, increments, work items, export
Context¶
The owner decided to start development and asked for a backlog of the entire system. The model describes what to build but carried no order of work, and until now this site excluded one on purpose: there is no calendar roadmap, no capacity plan and no staffing here, and that stays true.
A backlog kept in a tracker alone would drift from the architecture model: a story could name a service, an operation or a workflow step that no longer exists, and a service could be left out without anyone noticing. The model, its validator and its generator already solve that problem for every other part of the design.
Decision¶
- The backlog is a model kind (D75). It lives in
model/backlog/, is loaded and validated with the rest of the model, and generates the backlog pages and two draft exports. Nothing here creates a work item in a tracker; importing the draft is a separate, explicit act of the owner. - Two axes over one set of items (D76). Epics follow the structure of the system: one per platform, plus engineering readiness, ecosystem component extensions, Factory assets and outcome verification. Every feature carries the outcome increment whose demonstrable outcome needs it. The increments are ordered by dependency:
- I0 Readiness; I1 Generate a microservice (the first outcome, decision D65, through the API and a command-line client); I2 Deliver it; I3 Studio; I4 Trust and accountability; I5 Knowledge and connections; I6 Full product generation; I7 Operate and commercialise; I8 Expansion.
- I1 and I2 were chosen by the owner; the order of I3 to I8 was derived from the capability dependencies and confirmed by the owner (D80). It can still be changed without changing the model's shape.
- Rolling wave (D77). Epics and features cover the whole system. User stories and tasks exist only for the increments that are next: I0 and I1 at first, and I2 since the owner asked for it (D82). A later increment is elaborated when it becomes next, and the validator refuses stories in an increment that is not elaborated.
- Thin before complete. A service may be delivered thin in an early increment, with a stated scope, and complete in a later one. A service that an increment needs but does not build is declared as a stub with the increment that completes it. The register of stubs is generated per increment for the owner to accept. The owner accepted the register of the first outcome with two changes: AuditService and CostUsageService are delivered complete in I1, so that every run is audited and budget-capped from the start (D80).
- Stories serve people and coding agents. A story has the user statement, two to five testable acceptance criteria and a technical block: the repository, the references into the model (services, aggregates, operations, events, workflow steps, agents, tools, descriptors, decisions) and the verification commands. A task has an expected output.
- No dates, estimates or assignees. An item has a state of
outline,elaborated,ready,supersededordropped. Progress, dates, estimates and people live in the tracker, never here; the validator rejects such fields and date-shaped text. - Stable identifiers. An id such as
AIFACTORY-FEAT-001is assigned once, recorded in a ledger and never renumbered or reused. Sequence numbers and tags are derived at generation. - House convention for work items. Hierarchy Epic, Feature, story, Task; titles prefixed with the bracketed id; six tag families; the Azure DevOps hierarchical import columns. The owner's project uses the Scrum process, so the export names a story a Product Backlog Item (D81); the type names are a setting of
model/backlog/backlog.yaml.
What the validator guarantees¶
- every reference resolves in the model, and every modelled service names the repository of ADR-0028;
- every service is delivered, thin deliveries precede the one complete delivery, and every bounded context, workflow definition, must-priority requirement, UX work area and extended component is placed;
- dependencies between features and between increments are acyclic, and no feature depends on a later increment;
- a service's required dependencies are delivered by its increment or declared as stubs, and a workflow definition is placed no earlier than the services it runs on;
- the elaborated increments have stories or tasks under every feature, each story is complete, and every step, agent and tool of the first outcome's six workflows is referenced by a story.
- template and library work is marked before development, carries the mark on every task, and comes first in its increment (amendment D98).
Consequences¶
- The backlog had 9 increments, 20 epics, 148 features, 31 stories and 344 tasks on 2026-11-05; after the amendment of 2026-11-06 it has 51 stories and 555 tasks. The first outcome builds 29 services and gateways, 11 of them thin. Fifteen identifiers are retired and never reused: items that were done in this repository or replaced by an owner decision.
- A change to the model that removes or renames something a backlog item references fails the build, so the backlog cannot drift silently.
- The words "order of work" leave the list of what this site excludes; the exclusion of dates, capacity and staffing stays.
- Authoring is in YAML and review is in the generated pages; a person who prefers a tracker works from the export after the owner imports it.
Alternatives rejected¶
- Authoring directly in Azure DevOps. Rejected: no validation against the model, and the session that drafted the backlog has no connector to it.
- ClickUp. Rejected: the connected workspace belongs to a client.
- Markdown pages only. Rejected: no validation and no export.
- Stories for every feature now. Rejected by the owner in favour of the rolling wave: several thousand items would be stale before work reached them.
- Epics by outcome only, or by bounded context only. Rejected by the owner in favour of the hybrid.
Revisit triggers¶
- An increment becomes next: it is elaborated into stories and its
elaborationchanges. - The owner reorders I3 to I8 again.
- The tracker becomes the place where items are authored: the model then keeps increments, epics and features, and stories move.
Amendment 2026-11-06: I3 and I4 elaborated (D90)¶
The owner asked for the Studio increment and the Trust and accountability increment to be elaborated now. I0 to I4 are at stories and tasks; I5 to I8 stay at epics and features. The backlog has 9 increments, 20 epics, 148 features, 51 stories and 555 tasks. The Studio front end is built in ConnectSoft.AI.SoftwareFactory.Studio, declared with the shell template, the UI kit and the metering template as other repositories. The rule of the rolling wave is unchanged: a later increment is elaborated when the owner asks for it, and the validator then requires a story or a task under each of its features.
Amendment 2026-11-07: the before-development mark (D98)¶
Template and library work is marked and comes first. A feature whose tasks all change the templates, the UI kit or the Extensions libraries the Factory builds on (the repositories listed under before_development_repositories in backlog.yaml) carries before_development: true; the mark is derived onto every task under it as the tag phase:before-development and the prefix BEFORE DEVELOPMENT in the exports, the marked features are ordered first within their increment, and every increment page opens with them. The validator guarantees the mark (rule 15): a feature that works only in those repositories must carry it, a marked feature names no Factory repository and delivers no Factory service, and a feature that realizes only components and has no task yet states the mark explicitly. A feature that mixes a template with a Factory service is development, not template work.
Amendment 2026-11-08: a derived build order (D106)¶
The owner asked for the features and tasks to be ordered: the templates and libraries the Factory is built from first, then the Factory's own code. The order is derived at generation and never stored. Phase 1 holds every feature with the before-development mark (D98) and every feature that delivers no service and works only in template, estate-library or Factory-package repositories (before_development_repositories and library_repositories in backlog.yaml); phase 2 holds the rest. Inside a phase the order follows the increments, an outcome-verification feature closes its increment, and a feature never precedes a feature it depends on (topological order with phase, increment and epic order as the tie-break). The validator guarantees rule 16: a phase-1 feature never depends on Factory code. The ordinal is carried into the exports (buildOrder and phase in the JSON, a Stack Rank column in the Azure DevOps CSV) and onto the build order page and every feature page. Increments stay the outcome labels; the phase is the sequence.
Amendment 2026-11-08: a story wherever a service is touched (D108)¶
Every feature of an elaborated increment that delivers a service or whose tasks change a service repository carries a user story, and its tasks hang under the story. The stories are derived from the model: the service's endpoints with their scopes, aggregates, stores and events, the workflow's steps, agents, tools and outputs, the gateway's fronted services; their model references are checked by rule 2 and their shape by rule 12. Template and library features of an elaborated increment carry a story as well (D109): the component as the subject, the generated-solution or package gate as the first criterion, each task's expected output as a criterion. The Studio work-area features carry stories derived from the UX model (D110). Only features that touch this documentation or the CLI alone keep Feature → Task.
Amendment 2026-11-10: PBIs, a scenario catalog and a ratchet (D111)¶
The backlog takes the depth and the process of the Config Platform backlog. The story level becomes the Product Backlog Item level: one PBI per behaviour, several per feature, each with a kind (behavior, enabling, evidence), a self-contained narrative, two to five numbered criteria that cite a traced id or a source path, traces to the endpoints, events, workflow steps, scenarios, requirements and ADRs it delivers, dependencies on PBIs of its feature or on features and epics, and typed tasks with at least one verification task. PBIs live one file per feature under model/backlog/pbis/<epic>/<feature>.yaml; a writer owns one file. Every epic states done_when.
A scenario catalog (model/scenarios/) is derived from the model, one scenario per endpoint, event, workflow step, condition outcome and gateway route class, with locked ids; writers enrich the derived given/when/then/failure text and PBIs trace scenarios by id. The ratchet model/backlog/progress.yaml names the epics for which the quality and coverage rules are errors; for the others they warn, so the campaign runs epic by epic: context pack (backlog-context), two writers in parallel on their own files with the no-write linter (lint-pbi), one independent reviewer, central merge and validation, the owner's approval, the epic added to the ratchet. final: true enforces every rule for every epic.
What the validator now guarantees in addition (rules 17 to 27): placement of PBI files, criterion citations, operations traced only from delivered services or declared dependencies, nothing traced from a later increment, kind discipline, acyclic PBI dependencies inside a feature, scenario coverage or an exemption with the increment that completes it, a current and placeholder-free scenario catalog, no links, raw HTML or placeholders in backlog text, import files of at most 1,000 rows with parents first, and a done_when on every epic.
Amendment 2026-11-14: the campaign closed and the ratchet final (D138 to D141)¶
The campaign wrote every epic of I0 to I4 to the PBI level with the frozen process: a context pack per area, writers who own their files and loop lint-pbi until it is clean, one independent reviewer per area, one rework pass, central merge and validation by the orchestrator, and the owner's answers to the gaps of each run, asked in English and Russian. Model appliers applied each batch of owner decisions to the service, tool, workflow and schema models before PBI aligners brought the earlier PBIs in line. An alignment pass applied the decisions of later runs to the earlier PBIs (D138, D139). A completeness critic then read all I0 to I4 epics against the model; its findings were fixed in one pass (D140) and the gaps of that pass decided by the owner (D141).
final: true is set in model/backlog/progress.yaml: every epic is enforced, rules 23 and 24 apply everywhere, and every exemption names an increment after its scenario's increment. On 2026-11-14 the backlog has 185 features, 823 PBIs, 2,886 tasks and 880 scenarios, of which 631 are traced by PBIs and 45 are exempted to the increment that completes them. Model readings the campaign could not settle without the owner are kept in the open items, not in the backlog text.