[SC-17022] Document risk tiering workflow integration

site/guide/_sidebar.yaml

@@ -109,6 +109,7 @@ website:
                 - guide/risk-tiering/manage-risk-tier-templates.qmd
                 - guide/risk-tiering/configure-risk-tier-calculation.qmd
                 - guide/risk-tiering/manage-risk-tier-assessments.qmd
+                - guide/risk-tiering/set-up-risk-tiering-workflows.qmd
         - text: "---"
         - section: "Documents & templates"
           contents:

site/guide/risk-tiering/manage-risk-tier-assessments.qmd

@@ -90,6 +90,8 @@ The **Calculated Tier** section shows the final tier determination for this asse
 The sidebar on the assessment detail page shows:
 
 - **Status** — Draft, Active, or Archived.
+- **Assessment Stage** — the assessment's current governance stage, shown when risk tiering workflows are in use. The stage tracks review progress separately from the status and updates live as a workflow advances. See [Set up risk tiering workflows](set-up-risk-tiering-workflows.qmd).
+- **Active Workflows** — the workflow runs governing this assessment, shown when risk tiering workflows are in use. Click **See All Workflows** to start a manually triggered workflow or inspect a run.
 - **Assessment Version** — a dropdown showing the current version (for example: "13 (Latest)"). Use this to navigate to any previous version of the assessment.
 - **Risk Tier Template** — the template name and version this assessment is linked to, with a badge showing the calculation method (Scorecard or Risk Matrix).
 - **Published / Published By** — the publication date and the user who published it (shown once the assessment has been published).
@@ -108,6 +110,8 @@ When you are satisfied with the factor scores and the calculated tier:
 
 Only one assessment can be Active per record at a time.
 
+If a [risk tiering workflow](set-up-risk-tiering-workflows.qmd) is configured to start on publish for this record type, publishing also starts a governance review of the published version. Publishing a new version ends any still-running review of the previous version and starts a fresh one.
+
 :::{.callout-note}
 An assessment can only be published against an **Active** template version. If the template linked to your assessment has since been archived, you must migrate to the current template before publishing (see [Migrate a stale assessment](#migrate-a-stale-assessment)).
 :::
@@ -177,3 +181,4 @@ Only **Draft** assessments can be deleted. Active and Archived assessments are p
 - [Working with risk tiering](working-with-risk-tiering.qmd) — concepts, lifecycle overview, and roles.
 - [Manage risk tier templates](manage-risk-tier-templates.qmd) — how templates are configured and published.
 - [Configure risk tier calculation](configure-risk-tier-calculation.qmd) — how factors, scoring rules, and override rules work.
+- [Set up risk tiering workflows](set-up-risk-tiering-workflows.qmd) — govern assessments with stages, approvals, and tier-based routing.

site/guide/risk-tiering/manage-risk-tier-templates.qmd

@@ -67,6 +67,8 @@ To publish:
 Published templates are immutable. To make changes, create a new version.
 :::
 
+If a [risk tiering workflow](set-up-risk-tiering-workflows.qmd) is configured to start on publish for this template, publishing also starts a governance review of the published version. The template's detail page then shows its current governance stage and active workflow runs.
+
 ## Create a new version
 
 Use a new version to update a published template without disrupting in-progress assessments.
@@ -126,3 +128,4 @@ Every template's detail page shows its full version history — all published ve
 
 - [Configure risk tier calculation](configure-risk-tier-calculation.qmd) — set up scoring levels, factors, components, thresholds, and override rules.
 - [Manage risk tier assessments](manage-risk-tier-assessments.qmd) — create and publish assessments for your records against a published template.
+- [Set up risk tiering workflows](set-up-risk-tiering-workflows.qmd) — govern templates and assessments with stages, approvals, and tier-based routing.

site/guide/risk-tiering/set-up-risk-tiering-workflows.qmd

@@ -0,0 +1,151 @@
+---
+# Copyright © 2023-2026 ValidMind Inc. All rights reserved.
+# Refer to the LICENSE file in the root of this repository for details.
+# SPDX-License-Identifier: AGPL-3.0 AND ValidMind Commercial
+title: "Set up risk tiering workflows"
+date: last-modified
+description: "Govern risk tier assessments and templates through workflows — define governance stages, trigger reviews on publish, advance stages with dedicated steps, and branch on the assessed risk tier."
+---
+
+Risk tiering workflows let you govern risk tier assessments and templates with the same workflow engine you use for records and artifacts. A review can start automatically when an assessment or template is published, advance a governance stage as it runs, require approvals, and route differently based on the assessed risk tier.
+
+## Prerequisites
+
+- Active {{< var vm.product >}} login
+- Customer Admin role or equivalent permissions to manage workflows
+- Governance Admin or Validator role with `manage_risk_tier_template` permission to define governance stages
+- An active risk tier template published for at least one record type[^1]
+- Risk tiering enabled for your organization
+
+## About risk tiering workflows
+
+A risk tiering workflow applies to one of two subjects:
+
+- **Risk tier assessment workflows** govern a record type's risk tier assessments. The workflow is scoped to an inventory record type, and its stages and branch conditions come from that record type's currently active risk tier template.
+- **Risk tier template workflows** govern a specific risk tier template across the organization — for example, requiring a review before a new methodology version takes effect.
+
+Both kinds of workflow can move a **governance stage** as they run. Governance stages — for example: *In Development → In Review → Approved / Changes Requested* — track review progress and are separate from the Draft → Active → Archived lifecycle status.[^2] Publishing still moves the status; a workflow moves the stage.
+
+## Define governance stages
+
+Governance stages are defined per template, in two independent sets — one for the template itself, one for assessments made against it. Each set feeds a different workflow step:
+
+| Stage set | Applies to | Used by workflow step |
+|---|---|---|
+| **Risk Tier Template Stages** | The template itself | **{{< fa flag >}} Risk Tier Template Stage Change** |
+| **Risk Assessment Stages** | Assessments made against the template | **{{< fa flag >}} Risk Assessment Stage Change** |
+: Governance stage sets {.hover tbl-colwidths="[30,30,40]"}
+
+To define stages:
+
+1. In the left sidebar, click **{{< fa gear >}} Settings**.
+
+2. Under {{< fa shield >}} Governance, select **Risk Tier Stages**.
+
+3. Select the template to define stages for.
+
+4. Select the **Risk Tier Template Stages** or **Risk Assessment Stages** tab, depending on which stage set you want to define.
+
+5. Click **{{< fa plus >}} Add Stage**, then enter a **Name** and select a **Color**.
+
+6. Drag and drop to reorder stages into the order your review moves through them.
+
+::: {.callout title="Add stages to the set that matches your workflow's subject"}
+The two tabs are separate stage sets — a stage-change step only offers stages from its matching set. If the stage drop-down in a workflow step is empty, the step names the tab that feeds it so you can tell which set still needs stages.
+:::
+
+::: {.callout-important title="Deleting a stage does not check workflow steps."}
+A stage cannot be deleted while an assessment or template is currently in that stage. Deleting a stage that a workflow step still references is allowed, and silently breaks that step — the run stops advancing with no error shown. Update or remove the stage-change step before deleting its stage.
+:::
+
+## Add a risk tiering workflow
+
+1. In the left sidebar, click **{{< fa gear >}} Settings**.
+
+2. Under {{< fa shield >}} Governance, select **Workflows**.
+
+3. Select the **Risk Tiering Workflows** tab.
+
+4. Click **{{< fa plus >}} Add Risk Tiering Workflow**.
+
+5. Enter a **Title** and a **Description** for the workflow.
+
+6. Under **Applies to**, select the workflow's subject:
+
+    - **Risk Tier Assessment** — Govern a record type's risk tier assessments.
+    - **Risk Tier Template** — Govern a risk tier template across the organization.
+
+7. Select the workflow's scope:
+
+    - For assessment workflows, select the **Inventory Record Type**. Only record types with an active risk tier template are available. Stages and branch conditions in the workflow use the configuration of that record type's active template.
+    - For template workflows, select the **Risk Tier Template** to govern. Stages in the workflow use that template's configuration.
+
+8. Under **Workflow Start**, select when the workflow should be initiated:
+
+    - **Manually** — Start this workflow on demand from the assessment or template page.
+    - **On Risk Assessment Published** — Start this workflow automatically each time an assessment is published. (Assessment workflows only.)
+    - **On Risk Tier Template Published** — Start this workflow automatically each time a version of the template is published. (Template workflows only.)
+
+9. Click **Save Draft** to save your workflow, and then configure your workflow steps.[^3]
+
+::: {.callout-note}
+The subject and scope are structural and cannot be changed after the workflow is created.
+
+Only one workflow starting on publish is allowed per inventory record type (for assessments) or per template (for templates), so publishing fires exactly one governance workflow. Manually started workflows are not limited this way — you can create as many as you need.
+:::
+
+## Configure risk tiering steps
+
+Risk tiering workflows use the same workflow canvas and step types as record and artifact workflows,[^4] with these subject-specific capabilities:
+
+**Move the governance stage.** Add a **{{< fa flag >}} Risk Assessment Stage Change** step (assessment workflows) or a **{{< fa flag >}} Risk Tier Template Stage Change** step (template workflows) to move the subject's governance stage as the review runs — for example, set *In Review* when the review starts, and *Approved* or *Changes Requested* on the outcome of an **{{< fa users >}} Approval** step.[^5]
+
+**Branch on the assessed risk tier.** In an assessment workflow, a **{{< fa maximize >}} Condition Branch** can route on **Risk Assessment Field: Assessed Risk Tier** — the tier level of the assessment the workflow is running against. Use it to send high-tier models through a stricter review path than low-tier ones. The available tier values come from the record type's active template.
+
+**Require approvals.** Connect an **{{< fa users >}} Approval** step's rejection and approval paths to stage-change steps, so a vote moves the assessment or template into the matching governance stage.
+
+When your steps are configured, publish the workflow to put it into effect.[^6] A draft workflow never runs — it cannot be started manually, and a publish-triggered draft does not fire when an assessment or template is published.
+
+## Track governance on the assessment or template
+
+On the assessment detail page[^7] and the template detail page:[^8]
+
+- The [assessment stage]{.smallcaps} or [template stage]{.smallcaps} badge in the sidebar shows the current governance stage. The badge can also be set directly by users with edit access to the assessment or template.
+- The [active workflows]{.smallcaps} section lists the workflow runs for that assessment or template. Click **See All Workflows** to review available workflows, start a manually triggered workflow, or inspect a run.
+
+The stage badge and workflow list update live as a workflow advances — including right after an approval vote — without reloading the page.
+
+## How governance runs behave
+
+Risk tiering workflows are built around one principle: **an approval attests to a specific published version.**
+
+- **One published version = one governance run.** A publish-triggered workflow runs once per published version and stays bound to the exact version it judged. Publishing a new version archives the previous version, ends any of its still-active runs as aborted, and starts a fresh review of the new version — a full re-review, not a resumption. An archived version is terminal for governance: no workflow can start on it, so a re-run always targets the current version, not the displaced one.
+- **Approval does not publish.** A workflow moves stages and records approvals, but it never changes the Draft/Active/Archived status. When a review of a draft is approved, a person clicks **Publish** — the publishing decision stays with the author.
+- **Rejection ends the run.** A rejection typically moves the stage to something like *Changes Requested*, and the run ends. To address the feedback, revise and publish a new version — a publish-triggered review re-runs automatically, and a manual review can be re-run on demand.
+- **Publish-triggered and manual reviews are different tools.** Use a publish-triggered workflow as the governance backbone that runs on every publish, and manual workflows for on-demand reviews — such as governing a draft before it is published.
+
+## What's next
+
+- [Working with risk tiering](working-with-risk-tiering.qmd) — concepts, lifecycle overview, and roles.
+- [Manage risk tier assessments](manage-risk-tier-assessments.qmd) — create, publish, and version assessments.
+- [Workflow step types](/guide/workflows/workflow-step-types.qmd) — configuration reference for every workflow step.
+- [Working with workflows](/guide/workflows/working-with-workflows.qmd) — the full workflows guide.
+
+
+<!-- FOOTNOTES -->
+
+[^1]: [Manage risk tier templates](manage-risk-tier-templates.qmd)
+
+[^2]: [Working with risk tiering](working-with-risk-tiering.qmd#lifecycle)
+
+[^3]: [Configure workflow steps](/guide/workflows/configure-workflows.qmd#configure-workflow-steps)
+
+[^4]: [Workflow step types](/guide/workflows/workflow-step-types.qmd)
+
+[^5]: [Workflow step types](/guide/workflows/workflow-step-types.qmd#risk-assessment-stage-change)
+
+[^6]: [Publish workflow](/guide/workflows/configure-workflows.qmd#publish-workflow)
+
+[^7]: [Manage risk tier assessments](manage-risk-tier-assessments.qmd#assessment-sidebar)
+
+[^8]: [Manage risk tier templates](manage-risk-tier-templates.qmd)

site/guide/risk-tiering/working-with-risk-tiering.qmd

@@ -16,6 +16,7 @@ listing:
       - manage-risk-tier-templates.qmd
       - configure-risk-tier-calculation.qmd
       - manage-risk-tier-assessments.qmd
+      - set-up-risk-tiering-workflows.qmd
 ---
 
 Risk tiering gives your organization a structured, auditable way to classify AI models and other inventory records into discrete risk categories. Instead of relying on informal judgment calls, risk classification follows a defined methodology — configured once by administrators and applied consistently across every record in your inventory.
@@ -66,6 +67,9 @@ A per-factor setting that controls how component scores within a factor combine
 **Assessed Risk Tier**
 A system-managed, read-only inventory field that surfaces the risk tier of a record's most recently published assessment. It is automatically updated when an assessment is published and is visible to anyone with access to the record.
 
+**Governance stage**
+A named review stage — for example: In Development, In Review, Approved — that tracks where an assessment or template sits in your review process, separate from its Draft/Active/Archived status. Stages are defined per template and are typically moved by a [risk tiering workflow](set-up-risk-tiering-workflows.qmd).
+
 ## Lifecycle
 
 Both templates and assessments follow the same three lifecycle statuses:
@@ -78,6 +82,8 @@ Both templates and assessments follow the same three lifecycle statuses:
 
 Version history is append-only — once a version is published, its configuration is immutable. A new version must be created to make changes. Only one version of a given template can be Active at a time per record type. Only one assessment can be Active per record at a time.
 
+Separately from these statuses, an assessment or template can carry a **governance stage** that tracks its progress through your review process. See [Set up risk tiering workflows](set-up-risk-tiering-workflows.qmd).
+
 ## Who does what
 
 | Role | Responsibilities |
@@ -89,6 +95,8 @@ Version history is append-only — once a version is published, its configuratio
 
 - **Risk tier templates** — navigate to **Settings → Governance → Risk Tier Templates**.
 - **Risk tier assessments** — open any record in the model inventory and select the **Risk Tier Assessments** tab.
+- **Governance stages** — navigate to **Settings → Governance → Risk Tier Stages**.
+- **Risk tiering workflows** — navigate to **Settings → Governance → Workflows** and select the **Risk Tiering Workflows** tab.
 
 ## What's next