Skip to content

ADR-0026: Requirements-to-UX handoff — typed input bundle, Reviewer-approved alignment memo, readiness activation in the Workflow Engine

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-10-23 by the product owner (decisions D58–D62); amended 2026-10-26 (decisions D63–D64, below)
  • Date: 2026-10-23
  • Deciders: Dmitry Khaymov (product owner)
  • Tags: workflows, UX, requirements, approvals, readiness, validation

Context

A read-only review on 2026-10-23 (HEAD b7564eeb) established that the target model promised a handoff of aligned requirements into UX and did not define it. The narrative said Business Analyst → Stakeholder Alignment → "Aligned Requirements & User Stories" → UX → Architecture. The Stakeholder Alignment role declared only decisions → decision-memo; the UX Designer role required Vision, Service Blueprint and personas but no requirements or alignment evidence; the ux-personas definition started on any BlueprintValidated without a predicate, took only the Vision input, emitted BlueprintValidated itself, dropped the handoff pack the role required, and validated through a Condition step although the engine invariant says a Condition reads recorded outputs only. The same Condition defect existed in four more definitions. RunControlService was listed as a consumer of BlueprintValidated without a handler, and the Workflow Engine heard no blueprint event, so starts_on was an intent with no route to an accepted run. Eight legacy event names survived only on 2025 pages. Step retries said max, worker retries said attempts, neither defined.

The UX Blueprint depends on the Vision and Service blueprints (rule UX-002 names read models and commands from the Service Blueprint), while the narrative placed UX before architecture: the two are compatible only as two passes.

Decision

  1. Alignment authority. The Stakeholder Alignment Agent writes an alignment-memo-v1 whose agreedVersions names the exact ids, versions and hashes of the Vision Blueprint, requirements, backlog and personas it agrees on, with decisions, options, consequences and stakeholder positions. A human holding the Reviewer role approves that memo version by its artifact hash through Run Control's approval, publication class (D21); the requester of the run and the memo's author are never eligible (ADR-0015). An agent's "aligned" is a claim; the decision is the evidence. The Business Analyst keeps authorship of requirements and rules, the Product Owner of backlog and acceptance criteria; the memo refers to them, it never copies them.
  2. Readiness activation in the Workflow Engine. WorkflowEngineService (BC-38) owns a ReadinessCorrelation aggregate and a ReadinessCorrelator worker. They consume BlueprintValidated, ArtifactStored and ApprovalDecided, satisfy the members of a definition's activation block by predicate (passed and kind for blueprints, descriptor for artifacts, Approved with the memo's proposal hash for approvals), check that the memo's agreed versions equal the other members, compute the bundle fingerprint, and submit exactly one run through Run Control's SubmitRun with Idempotency-Key = {scope}:{operation}:{workflowReleaseId}:{bundleFingerprint}. A newer member version opens a new correlation and supersedes the open one. Run Control stays the single writer of run truth (ADR-0014); the engine never creates run state. Nothing starts on a raw event.
  3. Two UX passes. ux-discovery runs on a validated Vision Blueprint (research synthesis, actors, personas, journey seeds, hypotheses as typed artifacts). ux-blueprint runs on the ux-input-bundle-v1 and produces the validated UX Blueprint version, the coverage matrix and the handoff pack. ux-personas is retired; the coordinator persona-extractor realizes ux-discovery and two coordinators are added for requirements-alignment and ux-blueprint.
  4. Typed bodies. ux-input-bundle-v1, alignment-memo-v1, requirements-v1, backlog-v1, research-insights-v1, personas-v1, journey-seeds-v1, ux-hypotheses-v1, ux-coverage-matrix-v1, ux-handoff-pack-v1, blueprint-version-ref-v1 and blueprint-validation-receipt-v1 are registered descriptors with schemas. artifact-v1 gains an optional descriptor, approval-request-v1 an optional proposal.descriptor; ArtifactStored, ApprovalDecided and BlueprintValidated carry the fields the correlation matches on. Personas project into the closed blueprint-common Persona shape by id, name, role, goals and pain points.
  5. Validation is an operation with a receipt. Blueprint drafts are submitted with the blueprint-submit-version tool and validated with the blueprint-validate tool (blueprint-validate is sandbox class; blueprint-submit-version is shared-write under the project's policy since the amendment of 2026-10-26, D64). The tool returns a blueprint-validation-receipt-v1; a Condition step reads the recorded receipt and loops back to the draft through a bounded on_false, at most twice. Condition steps never retry and never call a service. The five definitions that validated through a Condition were rewritten; every definition that starts on BlueprintValidated constrains passed and kind.
  6. Step contracts and retry vocabulary. Steps may declare object-form input mappings (input.*, steps.*, bundle.*) and typed outputs; where they do, the validator checks that every required input of the agent is mapped and that descriptors agree. A definition with contract: strict requires the mappings on every agent and tool step (amendment of 2026-10-26). Human steps declare their approval binding (action class, proposal kind and source, approver rule). Retries say attempts (total tries) with a backoff; max is retired.
  7. Legacy pages. The 2025 sections that named StakeholderAlignmentReady, StakeholderAlignmentConfirmed, UserInsightsReady, UserResearchInsightsReady, PersonasReady and JourneyMapsReady are rewritten to the modelled contract; the example envelope of the UX Designer page follows run-event-envelope-v1; the three template workflow files are annotated as dialects.

Consequences

  • Positive: the handoff is verifiable by the model's validator (mappings, descriptors, predicates, consumer symmetry, approval binding); readiness is deterministic and idempotent; one agent-free decision point (the Reviewer) makes alignment evidence; the early pass keeps UX feedback flowing into architecture.
  • Negative: the Workflow Engine gains a correlation store and a submission path to Run Control; two more workflow definitions and twelve schemas to curate; the five rewritten definitions carry three validation steps instead of one.
  • Neutral: 510 producer-listed consumers without a declared handler remain an informational count; the broader site-wide symmetry is an open item, not a rule.

Alternatives rejected

  • An agent-emitted "requirements aligned" event: agents do not emit integration events; services do, under the envelope.
  • Readiness inside Run Control: it is the authority of record, not an orchestrator; joining signals there would mix readiness logic into run truth.
  • Readiness inside BlueprintService: BC-02 owns blueprint truth only and knows nothing of memos or backlogs.
  • A single UX pass after the Service Blueprint: loses the early UX feedback the architecture needs.
  • Approving the UX run instead of the memo: an approval binds an exact proposal hash (D21); the memo is the proposal, the run is not.

Revisit triggers

A second readiness-activated workflow with different join semantics; evidence that the Reviewer's memo approval is too slow for a project's cadence; the policy engine reclassifying blueprint writes under a run; a product whose descriptor family needs more than one correlation per project.

Amendment 2026-10-26 (D63, D64)

An independent review of the accepted decision (Codex, 2026-10-24) found that the readiness activation applied only to ux-blueprint while the other definitions still started on raw events, that the memo could name versions that no member pinned, and that the sandbox class of the blueprint tools contradicted the shared-write class of the same operation for people. The product owner decided as follows.

  1. Every definition not started by a person's submission is readiness-activated (D63). starts_on is RunAccepted with payload.workflowId == '<id>' for every definition except the four a person submits (plan-run, vision-to-blueprint, milestone-lifecycle, sprint-execution); 23 of the 27 definitions carry an activation block; the former raw starters (BlueprintValidated, ArtifactStored, ApprovalDecided, RecipeApproved, GenerationCompleted, PipelineRunCompleted, ChangeProposalOpened, ChangeProposalMerged, ReleaseReady, ProjectCreated, ContextMapDerived, DomainModelDerived) become members of an activation block. The members are typed: blueprint (passed and kind), artifact (descriptor), approval (Approved with the proposal descriptor) and signal (a producer event with ref, version_ref and hash_ref payload fields). The ReadinessCorrelator consumes all twelve events; the release is pinned when the correlation opens (release_pinning: resolved-at-open), never when it submits. Every required workflow input is an activation member slot of the same name and descriptor.
  2. Alignment waits for discovery; one memo; personas required (D63). requirements-alignment is activated by the validated Vision Blueprint and the personas-v1 artifact of ux-discovery (research insights optional). The memo's agreedVersions requires personas; there is one memo per bundle and its agreed versions must equal the members the correlation pinned. The option RequireMemoConsistency is removed: consistency is an invariant of ReadinessCorrelation, not a setting.
  3. Blueprint tools under the project's policy (D64). blueprint-submit-version is shared-write under the project's policy (D21): a run-authored Draft version is project scope like a human-authored one, visible to the project's readers and promoted by SubmitBlueprint; the policy engine (BC-20) may gate it per tenant, by default it is autonomous for Draft versions. blueprint-validate stays sandbox: it writes only the receipt. The gRPC SubmitDraftVersion carries the same class as the REST CreateBlueprintVersion.
  4. Strict contracts and selected-skill contracts. contract: strict on ux-blueprint, ux-discovery, requirements-alignment, vision-to-blueprint, architecture-decomposition and test-plan requires explicit mappings on every agent and tool step. A step that names a skill maps every required input of that skill and may not redeclare one of its outputs with another descriptor. Agent contracts were corrected where the modelled steps deliver other inputs than the role card assumed (Domain Modeler, Test Generator).
  5. Coverage gate and immutable release identity. ux-blueprint adds the condition check-coverage (summary.unresolvedGaps == 0, with deferrals[] naming an authority for each accepted gap) before the handoff pack; UX-005 and UX-006 are rules of the UX kind. The run's workflowReleaseId is immutable once the correlation is open and is part of the idempotency key.
  6. Validator hardening. K2-4 checks predicate semantics (passed == true, the member's kind, state == 'Approved', the member's descriptor), K2-5 the reverse direction of the bundle schema's required members and the signal ref fields, K2-13 the inputs-to-members symmetry and the strict contracts; a definition that does not start from RunAccepted without an activation block is an error. The probes of the review are persisted as tools/docs_model/tests/test_k2_regressions.py and run in the documentation pipeline before the strict build.

Consequence for the open items: the sandbox-class item is closed; the handler-less consumer count (510) remains informational until per-consumer decisions are taken.