AIFACTORY-FEAT-118: Workflow definition: Technical debt review¶
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 Factory assets: workflow definitions, agents and skills · Increment I4 Trust and accountability · State elaborated · Route solution-architect · Build order 137 of 185 (Factory code)
The workflow definition debt-review as a published asset: Collects reviewer comments and analyzer results of a pipeline run, classifies the shortcuts as debt with owners and severity, and raises them as findings. It has 3 steps, names the agents code-reviewer, tech-lead and the tools none, and is executed by WorkflowEngineService under Run Control.
| Delivers | — |
| Stubs | — |
| Realizes | workflows: debt-review adrs: ADR-0014, ADR-0024, ADR-0027 |
| Requirements | FR-08, XL-15 |
| Depends on | AIFACTORY-FEAT-189 AgentRegistryService: the publication path of releases from I2 |
| Sources | model/workflows/debt-review.yaml |
Scenarios to trace (3, catalog): SCN-debt-review-001 ✓, SCN-debt-review-002 ✓, SCN-debt-review-003 ✓
AIFACTORY-US-090: The Technical debt review workflow runs from its published definition¶
behavior · persona reviewer
As a reviewer, I want the technical debt review workflow to run from its published definition with the agents, tools and gates it declares, so that debt-findings are produced the same way on every run, with evidence.
The integration PBI of the definition debt-review. The definition is readiness-activated with three required members of one project: the analysis results of a pipeline run (PipelineRunCompleted of PipelineExecutionService in the state Succeeded, PartiallySucceeded or Failed), the merged change (ChangeProposalMerged) and the approved recipe (RecipeApproved of GenerationRecipeService). The optional input review-comments has no member slot, so a run the correlation submits carries no review comments and the review reads the analyzer results alone. When every member is satisfied the ReadinessCorrelator of WorkflowEngineService submits exactly one run through SubmitRun of RunControlService with its service token naming the project and the bundle idempotency key; a newer member version supersedes the open correlation. On RunAccepted the engine loads the Published release the run pinned through AgentRegistryService and marks the three agent steps ready in order: collect-signals on the code-reviewer release, then classify-debt and raise-findings on the tech-lead release. Every step declares failure_policy Retry, applied by Run Control only to a Failed attempt of failure class transient, the first two steps being of read and sandbox class and raise-findings of shared-write class with idempotency_key finding id (D133). No step declares a compensation (ADR-0014). The run reports exactly one outcome within its budget. Before any run, the definition release and the agent releases of code-reviewer and tech-lead, with any skill, tool or model profile release they need that is not yet Published, are submitted through SubmitRelease and published through PublishRelease of AgentRegistryService (feature agent-registry-service-publication); each publication is approved by a Reviewer who is not the submitter, a Platform admin for a model profile release. In I4 the evaluation gate of the complete delivery applies: where an evaluation suite exists for the asset kind, a release is published only with a passed evaluation record (ADR-0021), and an agent release published before I4 without one is resubmitted through the gate as a new version; the runs pin the Published release, never a Draft one (D140). The step behaviour is specified in AIFACTORY-US-1234 and AIFACTORY-US-1235; this PBI proves the chain on the recorded fixture.
Acceptance criteria
| AC1 | Given the Published release of debt-review, submitted through AgentRegistryService/SubmitRelease and published through AgentRegistryService/PublishRelease after an approval by a Reviewer who is not the submitter and with a passed evaluation record where an evaluation suite exists for its asset kind (ADR-0021, D140), carries the activation block, the 3 steps, input mappings, retry policies, timeouts and the failure_policy Retry of every step exactly as in model/workflows/debt-review.yaml, when the last required member of an open WorkflowEngineService/ReadinessCorrelation of the project is satisfied, then WorkflowEngineService/ReadinessSatisfied is published, one run is submitted through RunControlService/SubmitRun with the service token of the engine naming the project and the bundle idempotency key and WorkflowEngineService/ReadinessRunSubmitted names the returned run; a repeated submission with the same key and body returns the same run; the same key with a different body is answered 409 by RunControlService/SubmitRun and the correlation becomes Superseded with reason conflict, publishing WorkflowEngineService/ReadinessSuperseded and no run; and a newer member version publishes WorkflowEngineService/ReadinessSuperseded instead of a second run (ADR-0014). |
| AC2 | Given RunControlService/RunAccepted for that release with the inputs analysis-results, change-set and recipe, when the engine opens its projection, then WorkflowEngineService/WorkflowRunStarted is emitted and debt-review/collect-signals, debt-review/classify-debt and debt-review/raise-findings become ready in that order on the pinned Published releases of code-reviewer and tech-lead, and no Draft release is loaded (D140). |
| AC3 | Given every step succeeds, when the run completes, then debt-findings (findings-v1) is recorded as the run output under the run envelope, WorkflowEngineService/WorkflowRunCompleted is emitted once and RunControlService/RunCompleted follows exactly once (ADR-0014). |
| AC4 | Given a step is settled Failed with its retry budget spent or with a failure class other than transient, when the engine applies the compensation policy of model/workflows/debt-review.yaml, then WorkflowEngineService/WorkflowRunFailed names the step and the failure class, the outputs already recorded stay in place as evidence and RunControlService/RunFailed is published exactly once (recovery, not replay, ADR-0014). |
| AC5 | Given the recorded fixture inputs of model/workflows/debt-review.yaml, when the fixture run executes in the pipeline, then its outputs match the recorded ones field by field, every step output validates against its descriptor and the run stays within the declared budget (ADR-0024). |
| Traces: workflows | debt-review |
| Traces: steps | debt-review/collect-signals, debt-review/classify-debt, debt-review/raise-findings |
| Traces: agents | code-reviewer, tech-lead |
| Traces: services | WorkflowEngineService, RunControlService, AgentRegistryService |
| Traces: aggregates | WorkflowEngineService/ReadinessCorrelation |
| Traces: apis | RunControlService/SubmitRun, AgentRegistryService/SubmitRelease, AgentRegistryService/PublishRelease |
| Traces: events | AgentRegistryService/AssetReleasePublished, WorkflowEngineService/ReadinessSatisfied, WorkflowEngineService/ReadinessRunSubmitted, WorkflowEngineService/ReadinessSuperseded, RunControlService/RunAccepted, RunControlService/RunCompleted, RunControlService/RunFailed, WorkflowEngineService/WorkflowRunStarted, WorkflowEngineService/WorkflowRunCompleted, WorkflowEngineService/WorkflowRunFailed |
| Traces: descriptors | workflow-definition-v1, readiness-bundle-v1, artifact-v1, change-set-v1, findings-v1 |
| Traces: adrs | ADR-0014, ADR-0021, ADR-0024, ADR-0027 |
| Traces: requirements | FR-08, XL-15 |
| Depends on | AIFACTORY-US-1234, AIFACTORY-US-1235, feature:workflow-engine-service, feature:run-control-service, feature:agent-registry-service-complete, feature:agent-registry-service-publication |
| Sources | model/workflows/debt-review.yaml, model/agents/engineering/code-reviewer.yaml, model/agents/engineering/tech-lead.yaml, docs/planes/agent-runtime/workflow-definitions/debt-review.md |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-398 Author, submit and publish the release of the workflow definition debt-review with its agent releases |
implementation | The release of debt-review (workflow-definition-v1) authored with its activation block of three required members, its 3 steps, input mappings, retry policies, timeouts and compensation policy as in model/workflows/debt-review.yaml, the failure_policy Retry of every step copied as it stands, and accepted by ValidateWorkflowDefinition of WorkflowEngineService; it is submitted through SubmitRelease of AgentRegistryService together with the agent releases code-reviewer and tech-lead of AIFACTORY-TASK-399 and any skill, tool or model profile release of their closure that is not yet Published, each publication is approved, through the approval that RunControlService opens with the subject kind asset-release, by a Reviewer who is not the submitter (a Platform admin for a model profile release), and each release is published through PublishRelease with the alias latest moved to it (feature agent-registry-service-publication, D140); the evaluation gate of the complete delivery applies, so a release of an asset kind with an evaluation suite is published only with a passed evaluation record, and the Published release ids are recorded for the fixture run, which pins them. | ConnectSoft.AI.SoftwareFactory.WorkflowEngineService |
AIFACTORY-TASK-399 Author the agent releases code-reviewer and tech-lead with their prompts and skills |
implementation | Draft releases of code-reviewer (the fourteen bound skills of model/agents/engineering/code-reviewer.yaml, model profile code-agent-strong) and tech-lead (the three bound skills of model/agents/engineering/tech-lead.yaml, model profile reasoning-high) with their instructions and tool bindings; each is evaluated with the suite engineering-core-v1 and carries a passed evaluation record before AIFACTORY-TASK-398 submits it for publication, and a release of either agent published before I4 without an evaluation record is resubmitted through the evaluation gate as a new version (D140). | ConnectSoft.AI.SoftwareFactory.AgentTemplate |
AIFACTORY-TASK-400 Fixture run of debt-review against recorded inputs |
verification | The definition runs end to end on a fixture project in the acceptance environment from a satisfied readiness bundle to RunCompleted on the Published releases of AIFACTORY-TASK-398; every step output validates against its descriptor and debt-findings matches the recorded one field by field (AC1, AC2, AC3 and AC5 of AIFACTORY-US-090). | ConnectSoft.AI.SoftwareFactory.WorkflowEngineService |
AIFACTORY-TASK-725 Verify debt-review-runs-from-its-definition by running the declared command |
verification | Run dotnet test -c Release --filter Category=WorkflowFixture; it passes and proves AC1 to AC5 of AIFACTORY-US-090, including the same-key replay, the 409 conflict with the correlation Superseded with reason conflict and no run, and the failure path of AC4 (WorkflowRunFailed then RunFailed exactly once); the output names the Published release ids of debt-review, code-reviewer and tech-lead that the run pinned, as AgentRegistryService/GetRelease reports them with their approval by a Reviewer who is not the submitter and their evaluation record (D140). |
ConnectSoft.AI.SoftwareFactory.WorkflowEngineService |
AIFACTORY-US-1234: The reviewer collects the debt signals of a pipeline run and the tech lead classifies them as debt items¶
behavior · persona reviewer
As a reviewer, I want the shortcuts and deferred work named by analyzers and reviews gathered and classified with category, severity, owner and remedy, so that debt is visible as items someone owns instead of comments nobody follows up.
The first two steps of debt-review. When the engine marks collect-signals ready it resolves change-set, analysis-results and, when the run carries it, review-comments from the run inputs. The code-reviewer release runs in read class with the tools its card allows for reading (list-files, search-text, read-range, get-git-diff, knowledge-search) and skills such as code-reviewer-architecture-violation-detector and code-reviewer-refactor-strategy-advisor: it gathers every analyzer result and review comment of the merged change that names a shortcut or deferred work and writes signals, citing each source. When classify-debt becomes ready it receives recipe and review-findings from steps.collect-signals.signals; the tech-lead release, read class, with the skill tech-lead-escalation-decisions, gives each item a category, a severity, an owner and a suggested remedy, weighing the template and library versions the recipe pins, and writes debt-items. Neither step changes the change set or the recipe or needs an approval. Both declare failure_policy Retry, exponential, 3 attempts, backoff 30s; a Failed attempt of failure class transient is retried, any other failure class is not, and a step that exceeds PT30M or spends its budget fails the run with the evidence.
Acceptance criteria
| AC1 | Given a run accepted with analysis-results (artifact-v1), change-set (change-set-v1) and recipe, when code-reviewer executes debt-review/collect-signals, then the output signals (artifact-v1) is recorded once under the run envelope, lists every analyzer result and review comment that names a shortcut or deferred work with its source, and an absent review-comments input yields signals from the analyzer results alone (SCN-debt-review-001). |
| AC2 | Given steps.collect-signals.signals is recorded, when tech-lead executes debt-review/classify-debt with recipe and review-findings, then the output debt-items (artifact-v1) is recorded once and every item carries a category, a severity, an owner and a suggested remedy and cites the signal it comes from (SCN-debt-review-002). |
| AC3 | Given an attempt of debt-review/collect-signals or debt-review/classify-debt exceeds its timeout PT30M, settles Failed with a failure class other than transient, or settles Failed with failure class transient until the exponential budget of 3 attempts is spent, when the engine applies the policy of model/workflows/debt-review.yaml, then WorkflowEngineService/WorkflowRunFailed names the step and no shared system is changed (SCN-debt-review-001, SCN-debt-review-002, ADR-0014). |
| Traces: workflows | debt-review |
| Traces: steps | debt-review/collect-signals, debt-review/classify-debt |
| Traces: agents | code-reviewer, tech-lead |
| Traces: services | WorkflowEngineService |
| Traces: events | WorkflowEngineService/StepReady, WorkflowEngineService/WorkflowRunFailed |
| Traces: descriptors | artifact-v1, change-set-v1 |
| Traces: scenarios | SCN-debt-review-001, SCN-debt-review-002 |
| Traces: adrs | ADR-0014 |
| Traces: requirements | FR-08, XL-15 |
| Depends on | feature:workflow-engine-service, feature:run-control-service |
| Sources | model/workflows/debt-review.yaml, model/agents/engineering/code-reviewer.yaml, model/agents/engineering/tech-lead.yaml, model/scenarios/debt-review.yaml |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-4930 Recorded fixture of a merged change with debt signals |
fixture | A fixture merged change set, its analyzer results with two suppressed warnings and one deferred-work marker, an approved recipe, the expected signals artifact and the expected debt-items artifact with category, severity, owner and remedy per item, as the oracle of SCN-debt-review-001 and SCN-debt-review-002. | ConnectSoft.AI.SoftwareFactory.AgentTemplate |
AIFACTORY-TASK-4931 Verify the input mappings of collect-signals and classify-debt in the Draft release |
verification | The steps collect-signals and classify-debt of the Draft release authored by AIFACTORY-TASK-398 resolve change-set, analysis-results, the optional review-comments, recipe and review-findings exactly as mapped in model/workflows/debt-review.yaml, are announced with actionClass read, and an absent optional input resolves to nothing rather than failing the step. | ConnectSoft.AI.SoftwareFactory.WorkflowEngineService |
AIFACTORY-TASK-4932 Prove the collection and the classification on the fixture |
verification | A fixture run proves SCN-debt-review-001 and SCN-debt-review-002 (AC1 to AC3 of AIFACTORY-US-1234), including a run without review-comments and the retry exhaustion path ending in a WorkflowRunFailed that names the step. | ConnectSoft.AI.SoftwareFactory.WorkflowEngineService |
AIFACTORY-US-1235: The tech lead raises the classified debt items as findings with evidence and the run completes¶
behavior · persona reviewer
As a reviewer, I want the classified debt items recorded as findings with their evidence, so that the debt of a pipeline run can be followed up from one recorded output.
The last step of debt-review. When classify-debt succeeded the engine marks raise-findings ready and resolves recipe from the run input, review-findings from steps.collect-signals.signals and debt-items from steps.classify-debt.debt-items. The tech-lead release runs in shared-write class and turns every debt item into a finding with its id, category, severity, owner, evidence references (the signal that justifies it) and a redacted summary carrying the remedy, returned as debt-findings (findings-v1) with the member critical, the count of the findings of severity critical, and recorded once under the run envelope (D133). The findings are raised through Audit.RaiseFindings of AuditService (scope factory.audit.write), which records each finding as an open finding with one audit entry for the call and publishes FindingRaised once per recorded finding; the step declares idempotency_key finding id, so a retried attempt raises no finding twice, and a document whose critical count differs from the findings of severity critical it lists is refused with nothing recorded. The step binds no tool that reaches Audit.RaiseFindings, which is reported as an open question. The run then completes with debt-findings as its output and Run Control records exactly one Completed outcome. The step declares failure_policy Retry, exponential, 3 attempts, backoff 30s: a Failed attempt of failure class transient is retried, which holds for this shared-write step because it declares an idempotency key (D114), any other failure class is not, and a step that exceeds PT30M or spends its budget fails the run with the evidence while the signals and the debt items stay in place.
Acceptance criteria
| AC1 | Given debt-review/classify-debt succeeded, when tech-lead executes debt-review/raise-findings with recipe, review-findings and debt-items, then the output debt-findings (findings-v1) is recorded once under the run envelope with exactly one attempt outcome, every debt item carries its id, category, severity, owner, evidence references and summary, and critical equals the count of the findings of severity critical (SCN-debt-review-003, ADR-0027, D133). |
| AC2 | Given the output is recorded, when the findings are raised through AuditService/Audit.RaiseFindings and the step completes, then each finding is recorded once as an open finding of AuditService/Finding, AuditService/FindingRaised is published once per recorded finding, a retried attempt under idempotency_key finding id raises no finding twice, WorkflowEngineService/WorkflowRunCompleted is emitted once with debt-findings as the run output and RunControlService/RunCompleted follows exactly once (SCN-debt-review-003, ADR-0014, D133). |
| AC3 | Given an attempt of debt-review/raise-findings exceeds its timeout PT30M, settles Failed with a failure class other than transient, or settles Failed with failure class transient until the exponential budget of 3 attempts is spent, when the engine applies the policy of model/workflows/debt-review.yaml, then WorkflowEngineService/WorkflowRunFailed names the step, signals and debt-items stay in place as evidence and RunControlService/RunFailed is published exactly once (SCN-debt-review-003, ADR-0014). |
| Traces: workflows | debt-review |
| Traces: steps | debt-review/raise-findings |
| Traces: agents | tech-lead |
| Traces: services | WorkflowEngineService, AuditService |
| Traces: aggregates | AuditService/Finding |
| Traces: apis | AuditService/Audit.RaiseFindings |
| Traces: events | AuditService/FindingRaised, WorkflowEngineService/WorkflowRunCompleted, WorkflowEngineService/WorkflowRunFailed, RunControlService/RunCompleted, RunControlService/RunFailed |
| Traces: descriptors | artifact-v1, findings-v1 |
| Traces: scenarios | SCN-debt-review-003 |
| Traces: adrs | ADR-0014, ADR-0027 |
| Traces: requirements | FR-08, XL-15 |
| Depends on | AIFACTORY-US-1234, feature:workflow-engine-service, feature:run-control-service, feature:audit-service-complete |
| Sources | model/workflows/debt-review.yaml, model/agents/engineering/tech-lead.yaml, model/services/governance/AuditService.yaml, docs/reference/schemas/findings.schema.json, model/scenarios/debt-review.yaml |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-4933 Fixture expected debt findings of the recorded debt items |
fixture | The expected debt-findings output of the fixture debt items of AIFACTORY-TASK-4930 valid against findings-v1, with the id, category, severity, owner, evidence references and summary of each item, its critical count and the expected FindingRaised per finding, as the oracle of SCN-debt-review-003. | ConnectSoft.AI.SoftwareFactory.AgentTemplate |
AIFACTORY-TASK-4934 Map the raise-findings output to the run output of the Draft release |
implementation | The step raise-findings of the Draft release maps recipe, review-findings and debt-items as declared in model/workflows/debt-review.yaml with side-effect class shared-write and idempotency_key finding id, its recorded output debt-findings (findings-v1) is raised through Audit.RaiseFindings and set as the run output debt-findings when the run completes. | ConnectSoft.AI.SoftwareFactory.WorkflowEngineService |
AIFACTORY-TASK-4935 Prove the raised debt findings and the run completion on the fixture |
verification | A fixture run proves SCN-debt-review-003 (AC1 to AC3 of AIFACTORY-US-1235); one FindingRaised per finding with none raised twice under a retried attempt, WorkflowRunCompleted and RunCompleted exactly once on success, and the retry exhaustion path ending in WorkflowRunFailed and RunFailed once with the earlier outputs kept. | ConnectSoft.AI.SoftwareFactory.WorkflowEngineService |