@exaudeus/workrail 3.10.0 → 3.11.0

package/dist/v2/durable-core/schemas/session/events.d.ts

@@ -1098,6 +1098,229 @@ export declare const DomainEventV1Schema: z.ZodDiscriminatedUnion<"kind", [z.Zod
     eventIndex: z.ZodNumber;
     sessionId: z.ZodString;
     dedupeKey: z.ZodString;
+} & {
+    kind: z.ZodLiteral<"assessment_recorded">;
+    scope: z.ZodObject<{
+        runId: z.ZodString;
+        nodeId: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        runId: string;
+        nodeId: string;
+    }, {
+        runId: string;
+        nodeId: string;
+    }>;
+    data: z.ZodObject<{
+        assessmentId: z.ZodString;
+        attemptId: z.ZodString;
+        artifactOutputId: z.ZodString;
+        summary: z.ZodOptional<z.ZodString>;
+        normalizationNotes: z.ZodReadonly<z.ZodArray<z.ZodString, "many">>;
+        dimensions: z.ZodReadonly<z.ZodArray<z.ZodObject<{
+            dimensionId: z.ZodString;
+            level: z.ZodString;
+            rationale: z.ZodOptional<z.ZodString>;
+            normalization: z.ZodEnum<["exact", "normalized"]>;
+        }, "strip", z.ZodTypeAny, {
+            level: string;
+            dimensionId: string;
+            normalization: "exact" | "normalized";
+            rationale?: string | undefined;
+        }, {
+            level: string;
+            dimensionId: string;
+            normalization: "exact" | "normalized";
+            rationale?: string | undefined;
+        }>, "many">>;
+    }, "strip", z.ZodTypeAny, {
+        assessmentId: string;
+        dimensions: readonly {
+            level: string;
+            dimensionId: string;
+            normalization: "exact" | "normalized";
+            rationale?: string | undefined;
+        }[];
+        attemptId: string;
+        artifactOutputId: string;
+        normalizationNotes: readonly string[];
+        summary?: string | undefined;
+    }, {
+        assessmentId: string;
+        dimensions: readonly {
+            level: string;
+            dimensionId: string;
+            normalization: "exact" | "normalized";
+            rationale?: string | undefined;
+        }[];
+        attemptId: string;
+        artifactOutputId: string;
+        normalizationNotes: readonly string[];
+        summary?: string | undefined;
+    }>;
+}, "strip", z.ZodTypeAny, {
+    kind: "assessment_recorded";
+    sessionId: string;
+    data: {
+        assessmentId: string;
+        dimensions: readonly {
+            level: string;
+            dimensionId: string;
+            normalization: "exact" | "normalized";
+            rationale?: string | undefined;
+        }[];
+        attemptId: string;
+        artifactOutputId: string;
+        normalizationNotes: readonly string[];
+        summary?: string | undefined;
+    };
+    v: 1;
+    eventIndex: number;
+    eventId: string;
+    dedupeKey: string;
+    scope: {
+        runId: string;
+        nodeId: string;
+    };
+}, {
+    kind: "assessment_recorded";
+    sessionId: string;
+    data: {
+        assessmentId: string;
+        dimensions: readonly {
+            level: string;
+            dimensionId: string;
+            normalization: "exact" | "normalized";
+            rationale?: string | undefined;
+        }[];
+        attemptId: string;
+        artifactOutputId: string;
+        normalizationNotes: readonly string[];
+        summary?: string | undefined;
+    };
+    v: 1;
+    eventIndex: number;
+    eventId: string;
+    dedupeKey: string;
+    scope: {
+        runId: string;
+        nodeId: string;
+    };
+}>, z.ZodObject<{
+    v: z.ZodLiteral<1>;
+    eventId: z.ZodString;
+    eventIndex: z.ZodNumber;
+    sessionId: z.ZodString;
+    dedupeKey: z.ZodString;
+} & {
+    kind: z.ZodLiteral<"assessment_consequence_applied">;
+    scope: z.ZodObject<{
+        runId: z.ZodString;
+        nodeId: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        runId: string;
+        nodeId: string;
+    }, {
+        runId: string;
+        nodeId: string;
+    }>;
+    data: z.ZodObject<{
+        attemptId: z.ZodString;
+        assessmentId: z.ZodString;
+        trigger: z.ZodObject<{
+            dimensionId: z.ZodString;
+            level: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            level: string;
+            dimensionId: string;
+        }, {
+            level: string;
+            dimensionId: string;
+        }>;
+        effect: z.ZodObject<{
+            kind: z.ZodLiteral<"require_followup">;
+            guidance: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            kind: "require_followup";
+            guidance: string;
+        }, {
+            kind: "require_followup";
+            guidance: string;
+        }>;
+    }, "strip", z.ZodTypeAny, {
+        assessmentId: string;
+        effect: {
+            kind: "require_followup";
+            guidance: string;
+        };
+        attemptId: string;
+        trigger: {
+            level: string;
+            dimensionId: string;
+        };
+    }, {
+        assessmentId: string;
+        effect: {
+            kind: "require_followup";
+            guidance: string;
+        };
+        attemptId: string;
+        trigger: {
+            level: string;
+            dimensionId: string;
+        };
+    }>;
+}, "strip", z.ZodTypeAny, {
+    kind: "assessment_consequence_applied";
+    sessionId: string;
+    data: {
+        assessmentId: string;
+        effect: {
+            kind: "require_followup";
+            guidance: string;
+        };
+        attemptId: string;
+        trigger: {
+            level: string;
+            dimensionId: string;
+        };
+    };
+    v: 1;
+    eventIndex: number;
+    eventId: string;
+    dedupeKey: string;
+    scope: {
+        runId: string;
+        nodeId: string;
+    };
+}, {
+    kind: "assessment_consequence_applied";
+    sessionId: string;
+    data: {
+        assessmentId: string;
+        effect: {
+            kind: "require_followup";
+            guidance: string;
+        };
+        attemptId: string;
+        trigger: {
+            level: string;
+            dimensionId: string;
+        };
+    };
+    v: 1;
+    eventIndex: number;
+    eventId: string;
+    dedupeKey: string;
+    scope: {
+        runId: string;
+        nodeId: string;
+    };
+}>, z.ZodObject<{
+    v: z.ZodLiteral<1>;
+    eventId: z.ZodString;
+    eventIndex: z.ZodNumber;
+    sessionId: z.ZodString;
+    dedupeKey: z.ZodString;
 } & {
     kind: z.ZodLiteral<"preferences_changed">;
     scope: z.ZodObject<{
@@ -1653,6 +1876,7 @@ export declare const DomainEventV1Schema: z.ZodDiscriminatedUnion<"kind", [z.Zod
             outputId: string;
         }>]>, "many">>;
     }, "strip", z.ZodTypeAny, {
+        summary: string;
         reason: {
             detail: "needs_user_secret_or_token" | "needs_user_account_access" | "needs_user_artifact" | "needs_user_choice" | "needs_user_approval" | "needs_user_environment_action";
             category: "user_only_dependency";
@@ -1674,7 +1898,6 @@ export declare const DomainEventV1Schema: z.ZodDiscriminatedUnion<"kind", [z.Zod
         };
         gapId: string;
         severity: "warning" | "info" | "critical";
-        summary: string;
         evidenceRefs?: ({
             kind: "event";
             eventId: string;
@@ -1683,6 +1906,7 @@ export declare const DomainEventV1Schema: z.ZodDiscriminatedUnion<"kind", [z.Zod
             outputId: string;
         })[] | undefined;
     }, {
+        summary: string;
         reason: {
             detail: "needs_user_secret_or_token" | "needs_user_account_access" | "needs_user_artifact" | "needs_user_choice" | "needs_user_approval" | "needs_user_environment_action";
             category: "user_only_dependency";
@@ -1704,7 +1928,6 @@ export declare const DomainEventV1Schema: z.ZodDiscriminatedUnion<"kind", [z.Zod
         };
         gapId: string;
         severity: "warning" | "info" | "critical";
-        summary: string;
         evidenceRefs?: ({
             kind: "event";
             eventId: string;
@@ -1717,6 +1940,7 @@ export declare const DomainEventV1Schema: z.ZodDiscriminatedUnion<"kind", [z.Zod
     kind: "gap_recorded";
     sessionId: string;
     data: {
+        summary: string;
         reason: {
             detail: "needs_user_secret_or_token" | "needs_user_account_access" | "needs_user_artifact" | "needs_user_choice" | "needs_user_approval" | "needs_user_environment_action";
             category: "user_only_dependency";
@@ -1738,7 +1962,6 @@ export declare const DomainEventV1Schema: z.ZodDiscriminatedUnion<"kind", [z.Zod
         };
         gapId: string;
         severity: "warning" | "info" | "critical";
-        summary: string;
         evidenceRefs?: ({
             kind: "event";
             eventId: string;
@@ -1759,6 +1982,7 @@ export declare const DomainEventV1Schema: z.ZodDiscriminatedUnion<"kind", [z.Zod
     kind: "gap_recorded";
     sessionId: string;
     data: {
+        summary: string;
         reason: {
             detail: "needs_user_secret_or_token" | "needs_user_account_access" | "needs_user_artifact" | "needs_user_choice" | "needs_user_approval" | "needs_user_environment_action";
             category: "user_only_dependency";
@@ -1780,7 +2004,6 @@ export declare const DomainEventV1Schema: z.ZodDiscriminatedUnion<"kind", [z.Zod
         };
         gapId: string;
         severity: "warning" | "info" | "critical";
-        summary: string;
         evidenceRefs?: ({
             kind: "event";
             eventId: string;
@@ -1879,13 +2102,13 @@ export declare const DomainEventV1Schema: z.ZodDiscriminatedUnion<"kind", [z.Zod
         summary: z.ZodString;
         relatedStepId: z.ZodOptional<z.ZodString>;
     }, "strip", z.ZodTypeAny, {
-        reason: "missing_user_context" | "capability_unavailable" | "efficiency_skip" | "safety_stop" | "policy_constraint";
         summary: string;
+        reason: "missing_user_context" | "capability_unavailable" | "efficiency_skip" | "safety_stop" | "policy_constraint";
         divergenceId: string;
         relatedStepId?: string | undefined;
     }, {
-        reason: "missing_user_context" | "capability_unavailable" | "efficiency_skip" | "safety_stop" | "policy_constraint";
         summary: string;
+        reason: "missing_user_context" | "capability_unavailable" | "efficiency_skip" | "safety_stop" | "policy_constraint";
         divergenceId: string;
         relatedStepId?: string | undefined;
     }>;
@@ -1893,8 +2116,8 @@ export declare const DomainEventV1Schema: z.ZodDiscriminatedUnion<"kind", [z.Zod
     kind: "divergence_recorded";
     sessionId: string;
     data: {
-        reason: "missing_user_context" | "capability_unavailable" | "efficiency_skip" | "safety_stop" | "policy_constraint";
         summary: string;
+        reason: "missing_user_context" | "capability_unavailable" | "efficiency_skip" | "safety_stop" | "policy_constraint";
         divergenceId: string;
         relatedStepId?: string | undefined;
     };
@@ -1910,8 +2133,8 @@ export declare const DomainEventV1Schema: z.ZodDiscriminatedUnion<"kind", [z.Zod
     kind: "divergence_recorded";
     sessionId: string;
     data: {
-        reason: "missing_user_context" | "capability_unavailable" | "efficiency_skip" | "safety_stop" | "policy_constraint";
         summary: string;
+        reason: "missing_user_context" | "capability_unavailable" | "efficiency_skip" | "safety_stop" | "policy_constraint";
         divergenceId: string;
         relatedStepId?: string | undefined;
     };

package/dist/v2/durable-core/schemas/session/events.js

@@ -53,6 +53,32 @@ const AdvanceRecordedDataV1Schema = zod_1.z.object({
     intent: zod_1.z.literal('ack_pending'),
     outcome: AdvanceRecordedOutcomeV1Schema,
 });
+const AssessmentRecordedDimensionV1Schema = zod_1.z.object({
+    dimensionId: zod_1.z.string().min(1),
+    level: zod_1.z.string().min(1),
+    rationale: zod_1.z.string().min(1).optional(),
+    normalization: zod_1.z.enum(['exact', 'normalized']),
+});
+const AssessmentRecordedDataV1Schema = zod_1.z.object({
+    assessmentId: zod_1.z.string().min(1),
+    attemptId: zod_1.z.string().min(1),
+    artifactOutputId: zod_1.z.string().min(1),
+    summary: zod_1.z.string().min(1).optional(),
+    normalizationNotes: zod_1.z.array(zod_1.z.string().min(1)).readonly(),
+    dimensions: zod_1.z.array(AssessmentRecordedDimensionV1Schema).min(1).readonly(),
+});
+const AssessmentConsequenceAppliedDataV1Schema = zod_1.z.object({
+    attemptId: zod_1.z.string().min(1),
+    assessmentId: zod_1.z.string().min(1),
+    trigger: zod_1.z.object({
+        dimensionId: zod_1.z.string().min(1),
+        level: zod_1.z.string().min(1),
+    }),
+    effect: zod_1.z.object({
+        kind: zod_1.z.literal('require_followup'),
+        guidance: zod_1.z.string().min(1),
+    }),
+});
 const PreferencesChangedDataV1Schema = zod_1.z
     .object({
     changeId: zod_1.z.string().min(1),
@@ -120,6 +146,16 @@ exports.DomainEventV1Schema = zod_1.z.discriminatedUnion('kind', [
         scope: zod_1.z.object({ runId: zod_1.z.string().min(1), nodeId: zod_1.z.string().min(1) }),
         data: outputs_js_1.NodeOutputAppendedDataV1Schema,
     }),
+    exports.DomainEventEnvelopeV1Schema.extend({
+        kind: zod_1.z.literal('assessment_recorded'),
+        scope: zod_1.z.object({ runId: zod_1.z.string().min(1), nodeId: zod_1.z.string().min(1) }),
+        data: AssessmentRecordedDataV1Schema,
+    }),
+    exports.DomainEventEnvelopeV1Schema.extend({
+        kind: zod_1.z.literal('assessment_consequence_applied'),
+        scope: zod_1.z.object({ runId: zod_1.z.string().min(1), nodeId: zod_1.z.string().min(1) }),
+        data: AssessmentConsequenceAppliedDataV1Schema,
+    }),
     exports.DomainEventEnvelopeV1Schema.extend({
         kind: zod_1.z.literal('preferences_changed'),
         scope: zod_1.z.object({ runId: zod_1.z.string().min(1), nodeId: zod_1.z.string().min(1) }),

package/dist/v2/durable-core/schemas/session/gaps.d.ts

@@ -149,6 +149,7 @@ export declare const GapRecordedDataV1Schema: z.ZodObject<{
         outputId: string;
     }>]>, "many">>;
 }, "strip", z.ZodTypeAny, {
+    summary: string;
     reason: {
         detail: "needs_user_secret_or_token" | "needs_user_account_access" | "needs_user_artifact" | "needs_user_choice" | "needs_user_approval" | "needs_user_environment_action";
         category: "user_only_dependency";
@@ -170,7 +171,6 @@ export declare const GapRecordedDataV1Schema: z.ZodObject<{
     };
     gapId: string;
     severity: "warning" | "info" | "critical";
-    summary: string;
     evidenceRefs?: ({
         kind: "event";
         eventId: string;
@@ -179,6 +179,7 @@ export declare const GapRecordedDataV1Schema: z.ZodObject<{
         outputId: string;
     })[] | undefined;
 }, {
+    summary: string;
     reason: {
         detail: "needs_user_secret_or_token" | "needs_user_account_access" | "needs_user_artifact" | "needs_user_choice" | "needs_user_approval" | "needs_user_environment_action";
         category: "user_only_dependency";
@@ -200,7 +201,6 @@ export declare const GapRecordedDataV1Schema: z.ZodObject<{
     };
     gapId: string;
     severity: "warning" | "info" | "critical";
-    summary: string;
     evidenceRefs?: ({
         kind: "event";
         eventId: string;

package/dist/v2/projections/assessment-consequences.d.ts

@@ -0,0 +1,19 @@
+import type { Result } from 'neverthrow';
+import type { DomainEventV1 } from '../durable-core/schemas/session/index.js';
+import type { ProjectionError } from './projection-error.js';
+type AssessmentConsequenceAppliedEventV1 = Extract<DomainEventV1, {
+    kind: 'assessment_consequence_applied';
+}>;
+export interface AppliedAssessmentConsequenceViewV2 {
+    readonly assessmentId: string;
+    readonly attemptId: string;
+    readonly trigger: AssessmentConsequenceAppliedEventV1['data']['trigger'];
+    readonly effect: AssessmentConsequenceAppliedEventV1['data']['effect'];
+    readonly recordedAtEventIndex: number;
+}
+export interface AssessmentConsequencesProjectionV2 {
+    readonly byNodeId: Readonly<Record<string, readonly AppliedAssessmentConsequenceViewV2[]>>;
+}
+export declare function projectAssessmentConsequencesV2(events: readonly DomainEventV1[]): Result<AssessmentConsequencesProjectionV2, ProjectionError>;
+export declare function getLatestAssessmentConsequenceForNode(projection: AssessmentConsequencesProjectionV2, nodeId: string): AppliedAssessmentConsequenceViewV2 | undefined;
+export {};

package/dist/v2/projections/assessment-consequences.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.projectAssessmentConsequencesV2 = projectAssessmentConsequencesV2;
+exports.getLatestAssessmentConsequenceForNode = getLatestAssessmentConsequenceForNode;
+const neverthrow_1 = require("neverthrow");
+const constants_js_1 = require("../durable-core/constants.js");
+function projectAssessmentConsequencesV2(events) {
+    for (let i = 1; i < events.length; i++) {
+        if (events[i].eventIndex < events[i - 1].eventIndex) {
+            return (0, neverthrow_1.err)({ code: 'PROJECTION_INVARIANT_VIOLATION', message: 'Events must be sorted by eventIndex ascending' });
+        }
+    }
+    const byNodeId = {};
+    for (const event of events) {
+        if (event.kind !== constants_js_1.EVENT_KIND.ASSESSMENT_CONSEQUENCE_APPLIED)
+            continue;
+        const nodeId = event.scope.nodeId;
+        if (!byNodeId[nodeId])
+            byNodeId[nodeId] = [];
+        byNodeId[nodeId].push({
+            assessmentId: event.data.assessmentId,
+            attemptId: event.data.attemptId,
+            trigger: event.data.trigger,
+            effect: event.data.effect,
+            recordedAtEventIndex: event.eventIndex,
+        });
+    }
+    return (0, neverthrow_1.ok)({ byNodeId });
+}
+function getLatestAssessmentConsequenceForNode(projection, nodeId) {
+    const consequences = projection.byNodeId[nodeId];
+    return consequences && consequences.length > 0 ? consequences[consequences.length - 1] : undefined;
+}

package/dist/v2/projections/assessments.d.ts

@@ -0,0 +1,21 @@
+import type { Result } from 'neverthrow';
+import type { DomainEventV1 } from '../durable-core/schemas/session/index.js';
+import type { ProjectionError } from './projection-error.js';
+type AssessmentRecordedEventV1 = Extract<DomainEventV1, {
+    kind: 'assessment_recorded';
+}>;
+export interface RecordedAssessmentViewV2 {
+    readonly assessmentId: string;
+    readonly attemptId: string;
+    readonly artifactOutputId: string;
+    readonly summary?: string;
+    readonly normalizationNotes: readonly string[];
+    readonly dimensions: AssessmentRecordedEventV1['data']['dimensions'];
+    readonly recordedAtEventIndex: number;
+}
+export interface AssessmentsProjectionV2 {
+    readonly byNodeId: Readonly<Record<string, readonly RecordedAssessmentViewV2[]>>;
+}
+export declare function projectAssessmentsV2(events: readonly DomainEventV1[]): Result<AssessmentsProjectionV2, ProjectionError>;
+export declare function getLatestAssessmentForNode(projection: AssessmentsProjectionV2, nodeId: string): RecordedAssessmentViewV2 | undefined;
+export {};

package/dist/v2/projections/assessments.js

@@ -0,0 +1,35 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.projectAssessmentsV2 = projectAssessmentsV2;
+exports.getLatestAssessmentForNode = getLatestAssessmentForNode;
+const neverthrow_1 = require("neverthrow");
+const constants_js_1 = require("../durable-core/constants.js");
+function projectAssessmentsV2(events) {
+    for (let i = 1; i < events.length; i++) {
+        if (events[i].eventIndex < events[i - 1].eventIndex) {
+            return (0, neverthrow_1.err)({ code: 'PROJECTION_INVARIANT_VIOLATION', message: 'Events must be sorted by eventIndex ascending' });
+        }
+    }
+    const byNodeId = {};
+    for (const event of events) {
+        if (event.kind !== constants_js_1.EVENT_KIND.ASSESSMENT_RECORDED)
+            continue;
+        const nodeId = event.scope.nodeId;
+        if (!byNodeId[nodeId])
+            byNodeId[nodeId] = [];
+        byNodeId[nodeId].push({
+            assessmentId: event.data.assessmentId,
+            attemptId: event.data.attemptId,
+            artifactOutputId: event.data.artifactOutputId,
+            summary: event.data.summary,
+            normalizationNotes: event.data.normalizationNotes,
+            dimensions: event.data.dimensions,
+            recordedAtEventIndex: event.eventIndex,
+        });
+    }
+    return (0, neverthrow_1.ok)({ byNodeId });
+}
+function getLatestAssessmentForNode(projection, nodeId) {
+    const assessments = projection.byNodeId[nodeId];
+    return assessments && assessments.length > 0 ? assessments[assessments.length - 1] : undefined;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@exaudeus/workrail",
-  "version": "3.10.0",
+  "version": "3.11.0",
   "description": "Step-by-step workflow enforcement for AI agents via MCP",
   "license": "MIT",
   "repository": {

package/spec/workflow.schema.json

@@ -135,6 +135,14 @@
       },
       "uniqueItems": true
     },
+    "assessments": {
+      "type": "array",
+      "description": "Workflow-declared assessment definitions. Steps reference these by ID via assessmentRefs instead of embedding assessment structure inline repeatedly.",
+      "items": {
+        "$ref": "#/$defs/assessmentDefinition"
+      },
+      "uniqueItems": true
+    },
     "extensionPoints": {
       "type": "array",
       "description": "Bounded cognitive slots that users can customize via .workrail/bindings.json. Each slot is referenced in step prompts via {{wr.bindings.slotId}} and resolved at compile time. Use extension points for bounded cognitive units, not for core orchestration or final synthesis ownership.",
@@ -293,6 +301,21 @@
         "runCondition": { "$ref": "#/$defs/condition" },
         "validationCriteria": { "oneOf": [ { "type": "array", "items": { "$ref": "#/$defs/validationRule" } }, { "$ref": "#/$defs/validationComposition" } ] },
         "outputContract": { "$ref": "#/$defs/outputContract" },
+        "assessmentRefs": {
+          "type": "array",
+          "description": "References to workflow-level assessment definitions expected for this step. V1 supports exactly one assessmentRef per step.",
+          "items": { "type": "string", "minLength": 1, "maxLength": 64 },
+          "minItems": 1,
+          "maxItems": 1,
+          "uniqueItems": true
+        },
+        "assessmentConsequences": {
+          "type": "array",
+          "description": "Step-local assessment consequence declarations. V1 supports at most one exact-match follow-up consequence.",
+          "items": { "$ref": "#/$defs/assessmentConsequence" },
+          "minItems": 1,
+          "maxItems": 1
+        },
         "notesOptional": { "type": "boolean", "description": "When true, output.notesMarkdown is not required for this step. Steps with outputContract are automatically exempt. Use sparingly for mechanical steps with no substantive work to document." },
         "functionDefinitions": { "type": "array", "items": { "$ref": "#/$defs/functionDefinition" } },
         "functionCalls": { "type": "array", "items": { "$ref": "#/$defs/functionCall" } },
@@ -727,6 +750,93 @@
       "required": ["contractRef"],
       "additionalProperties": false
     },
+    "assessmentDimension": {
+      "type": "object",
+      "description": "A bounded dimension within a workflow-declared assessment definition.",
+      "properties": {
+        "id": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 64
+        },
+        "purpose": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 256
+        },
+        "levels": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 64
+          },
+          "minItems": 2,
+          "uniqueItems": true
+        },
+        "required": {
+          "type": "boolean",
+          "default": true
+        }
+      },
+      "required": ["id", "purpose", "levels"],
+      "additionalProperties": false
+    },
+    "assessmentDefinition": {
+      "type": "object",
+      "description": "Workflow-declared assessment definition referenced by steps.",
+      "properties": {
+        "id": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 64
+        },
+        "purpose": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 256
+        },
+        "dimensions": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/assessmentDimension"
+          },
+          "minItems": 1
+        }
+      },
+      "required": ["id", "purpose", "dimensions"],
+      "additionalProperties": false
+    },
+    "assessmentConsequenceTrigger": {
+      "type": "object",
+      "description": "Exact-match trigger on one declared assessment dimension and one declared canonical level.",
+      "properties": {
+        "dimensionId": { "type": "string", "minLength": 1, "maxLength": 64 },
+        "equalsLevel": { "type": "string", "minLength": 1, "maxLength": 64 }
+      },
+      "required": ["dimensionId", "equalsLevel"],
+      "additionalProperties": false
+    },
+    "assessmentConsequenceEffect": {
+      "type": "object",
+      "description": "V1 assessment consequence effect. Keeps the same step pending and requires follow-up before retry.",
+      "properties": {
+        "kind": { "const": "require_followup" },
+        "guidance": { "type": "string", "minLength": 1, "maxLength": 512 }
+      },
+      "required": ["kind", "guidance"],
+      "additionalProperties": false
+    },
+    "assessmentConsequence": {
+      "type": "object",
+      "description": "Step-local assessment consequence declaration. V1 supports one exact-match follow-up consequence only.",
+      "properties": {
+        "when": { "$ref": "#/$defs/assessmentConsequenceTrigger" },
+        "effect": { "$ref": "#/$defs/assessmentConsequenceEffect" }
+      },
+      "required": ["when", "effect"],
+      "additionalProperties": false
+    },
     "functionCall": {
       "type": "object",
       "properties": {