@exaudeus/workrail 3.14.0 → 3.15.0

package/dist/mcp/tool-descriptions.js

@@ -48,12 +48,17 @@ This tool provides:
 - Field descriptions and validation rules
 - Examples of valid patterns and formats
 - Schema version and metadata information`,
-        list_workflows: `Lists available workflows using WorkRail v2 (feature-flagged). Returns workflow metadata plus pinned snapshot hashes for deterministic execution.
+        list_workflows: `Lists available workflows. When a workflow exists for the user's request, following it means following the user's structured instructions.
 
-Use this to discover workflows before attempting multi-step tasks. When a workflow exists for the user's request, following it means following the user's structured instructions.
+Discovery pattern (token-efficient — do this):
+- Preferred: read the workrail://tags MCP resource — tag definitions with no tool call.
+- Or: call with no tags → returns tagSummary (~500 tokens) with when-to-use phrases per tag.
+- Then: call with tags=["<tagId>"] → returns the filtered workflow list for that tag.
+- Shortcut: if a workflow ID in tagSummary examples[] already matches, call start_workflow directly — skip the second list call.
+- Multiple tags: if more than one tag fits, pick the most specific one.
 
-Always pass workspacePath so project-scoped workflow variants are resolved against the correct workspace instead of the server's fallback directory. Shared MCP servers cannot infer this safely.`,
-        inspect_workflow: `Inspect a workflow structure before starting it (WorkRail v2, feature-flagged).
+Always pass workspacePath so project-scoped workflow variants are resolved against the correct workspace. Shared MCP servers cannot infer this safely.`,
+        inspect_workflow: `Inspect a workflow structure before starting it.
 
 Use this to understand what steps the workflow will guide you through. The workflow is a step-by-step plan the user (or workflow author) created for this type of task.
 
@@ -139,14 +144,17 @@ Returns validation result with specific errors and suggestions if invalid.`,
         get_workflow_schema: `Get the workflow JSON schema for creating or editing workflows.
 
 Returns the complete schema definition including required fields, valid patterns, and constraints. Use this as reference when authoring workflow JSON.`,
-        list_workflows: `List available workflows via WorkRail v2 (feature-flagged).
+        list_workflows: `Lists available workflows. When a workflow exists for the user's request, you MUST use it instead of improvising your own approach.
 
-Workflows are the user's pre-defined instructions for complex tasks. When a workflow exists for the user's request, you MUST use it instead of improvising your own approach.
-
-Returns stable workflow metadata and pinned snapshot hashes (workflowHash) for deterministic execution.
+Discovery pattern (token-efficient — do this):
+- Preferred: read the workrail://tags MCP resource — tag definitions with no tool call.
+- Or: call with no tags → returns tagSummary (~500 tokens) with when-to-use phrases per tag.
+- Then: call with tags=["<tagId>"] → returns the filtered workflow list for that tag.
+- Shortcut: if a workflow ID in tagSummary examples[] already matches, call start_workflow directly — skip the second list call.
+- Multiple tags: if more than one tag fits, pick the most specific one.
 
 Pass workspacePath on every call so project-scoped workflow variants are resolved against the correct workspace. Shared MCP servers cannot infer this safely.`,
-        inspect_workflow: `Inspect a workflow you are considering following (WorkRail v2, feature-flagged).
+        inspect_workflow: `Inspect a workflow you are considering following.
 
 Use this to understand the workflow's structure before starting. The workflow is the user's explicit plan - not suggestions, not guidelines, but direct instructions you will follow.
 

package/dist/mcp/v2/tools.d.ts

@@ -3,12 +3,15 @@ import type { ToolAnnotations } from '../tool-factory.js';
 export declare const V2ListWorkflowsInput: z.ZodObject<{
     workspacePath: z.ZodEffects<z.ZodString, string, string>;
     includeSources: z.ZodOptional<z.ZodBoolean>;
+    tags: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
 }, "strip", z.ZodTypeAny, {
     workspacePath: string;
     includeSources?: boolean | undefined;
+    tags?: string[] | undefined;
 }, {
     workspacePath: string;
     includeSources?: boolean | undefined;
+    tags?: string[] | undefined;
 }>;
 export type V2ListWorkflowsInput = z.infer<typeof V2ListWorkflowsInput>;
 export declare const V2InspectWorkflowInput: z.ZodObject<{
@@ -28,12 +31,15 @@ export type V2InspectWorkflowInput = z.infer<typeof V2InspectWorkflowInput>;
 export declare const V2StartWorkflowInput: z.ZodObject<{
     workflowId: z.ZodString;
     workspacePath: z.ZodEffects<z.ZodString, string, string>;
+    goal: z.ZodString;
 }, "strip", z.ZodTypeAny, {
     workflowId: string;
     workspacePath: string;
+    goal: string;
 }, {
     workflowId: string;
     workspacePath: string;
+    goal: string;
 }>;
 export type V2StartWorkflowInput = z.infer<typeof V2StartWorkflowInput>;
 export declare const V2ContinueWorkflowInputShape: z.ZodObject<{

package/dist/mcp/v2/tools.js

@@ -17,6 +17,7 @@ const optionalWorkspacePathField = workspacePathField.optional();
 exports.V2ListWorkflowsInput = zod_1.z.object({
     workspacePath: workspacePathField.describe('Required. Absolute path to your current workspace directory (e.g. the "Workspace:" value from your system parameters). WorkRail uses this to resolve project-scoped workflow variants against the correct workspace for discovery-sensitive workflow listing. Shared MCP servers cannot infer this safely.'),
     includeSources: zod_1.z.boolean().optional().describe('When true, includes a source catalog in the response showing where workflows come from (built-in, project-scoped, rooted-sharing, external), with effective and shadowed workflow counts per source. Omit or set false for the default workflow-list-only response.'),
+    tags: zod_1.z.array(zod_1.z.string()).optional().describe('Filter by one or more domain tags (e.g. ["coding"], ["review_audit", "investigation"]). When present, returns the full workflow list for workflows matching any of the specified tags. When absent, returns a compact tagSummary instead of the full list — use this first to discover which tags exist, then call again with a specific tag. Valid tags: coding, review_audit, investigation, design, documentation, tickets, learning, routines, authoring.'),
 });
 exports.V2InspectWorkflowInput = zod_1.z.object({
     workflowId: zod_1.z.string().min(1).regex(/^([a-z0-9_-]+|[a-z][a-z0-9_-]+\.[a-z][a-z0-9_-]+)$/, 'Workflow ID must be a valid legacy ID (e.g. my-workflow) or namespaced ID (e.g. wr.discovery)').describe('The workflow ID to inspect'),
@@ -26,6 +27,7 @@ exports.V2InspectWorkflowInput = zod_1.z.object({
 exports.V2StartWorkflowInput = zod_1.z.object({
     workflowId: zod_1.z.string().min(1).regex(/^([a-z0-9_-]+|[a-z][a-z0-9_-]+\.[a-z][a-z0-9_-]+)$/, 'Workflow ID must be a valid legacy ID (e.g. my-workflow) or namespaced ID (e.g. wr.discovery)').describe('The workflow ID to start'),
     workspacePath: workspacePathField.describe('Required. Absolute path to your current workspace directory (e.g. the "Workspace:" value from your system parameters). WorkRail uses this to resolve the correct project-scoped workflow variant and to anchor the session to the correct repo for future resume_session discovery. Shared MCP servers cannot infer this safely.'),
+    goal: zod_1.z.string().min(1).describe('A short sentence describing what you are trying to accomplish (e.g. "implement OAuth refresh token rotation", "review PR #47 before merge", "investigate why the build fails on CI").'),
 });
 exports.V2ContinueWorkflowInputShape = zod_1.z.object({
     workspacePath: optionalWorkspacePathField,

package/dist/mcp/workflow-protocol-contracts.js

@@ -46,7 +46,7 @@ function findAliasFieldConflicts(value, aliasMap) {
 }
 exports.START_WORKFLOW_PROTOCOL = {
     canonicalParams: {
-        required: ['workflowId', 'workspacePath'],
+        required: ['workflowId', 'workspacePath', 'goal'],
         optional: [],
     },
     descriptions: {
@@ -57,11 +57,13 @@ exports.START_WORKFLOW_PROTOCOL = {
                 'Follow the returned step exactly; treat it as the user\'s current instruction.',
                 'When the step is done, call continue_workflow with the returned continueToken.',
                 'Always pass workspacePath. Shared MCP servers cannot safely infer which repo/workspace you mean.',
+                'Always pass goal. A short sentence describing what you are trying to accomplish (e.g. "implement OAuth refresh token rotation").',
                 'Only pass context on later continue_workflow calls if facts changed.',
             ],
             examplePayload: {
                 workflowId: 'coding-task-workflow-agentic',
                 workspacePath: '/Users/you/git/my-project',
+                goal: 'implement OAuth refresh token rotation',
             },
             returns: 'Step instructions plus continueToken and checkpointToken in the structured response.',
         },
@@ -72,10 +74,12 @@ exports.START_WORKFLOW_PROTOCOL = {
                 'Execute the returned step exactly as written.',
                 'When the step is complete, call continue_workflow with the returned continueToken.',
                 'Pass workspacePath on every call. Shared MCP servers cannot safely infer the correct workspace.',
+                'Pass goal on every call. A short sentence describing what you are trying to accomplish.',
             ],
             examplePayload: {
                 workflowId: 'coding-task-workflow-agentic',
                 workspacePath: '/Users/you/git/my-project',
+                goal: 'implement OAuth refresh token rotation',
             },
             returns: 'Step instructions plus continueToken and checkpointToken in the structured response.',
         },

package/dist/types/workflow-definition.d.ts

@@ -23,8 +23,7 @@ export interface AssessmentDefinition {
     readonly dimensions: readonly AssessmentDimensionDefinition[];
 }
 export interface AssessmentConsequenceTriggerDefinition {
-    readonly dimensionId: string;
-    readonly equalsLevel: string;
+    readonly anyEqualsLevel: string;
 }
 export interface AssessmentFollowupRequiredEffectDefinition {
     readonly kind: 'require_followup';

package/dist/v2/infra/local/workspace-anchor/index.js

@@ -33,7 +33,10 @@ class LocalWorkspaceAnchorV2 {
     }
     async runGitCommands(cwd) {
         const anchors = [];
-        const repoRoot = await this.gitCommand('git rev-parse --show-toplevel', cwd);
+        const gitCommonDir = await this.gitCommand('git rev-parse --path-format=absolute --git-common-dir', cwd);
+        if (!gitCommonDir)
+            return anchors;
+        const repoRoot = gitCommonDir.replace(/\/\.git\/?$/, '').trim() || null;
         if (!repoRoot)
             return anchors;
         const repoRootHash = hashRepoRoot(repoRoot);

package/dist/v2/usecases/console-routes.js

@@ -8,6 +8,39 @@ const express_1 = __importDefault(require("express"));
 const path_1 = __importDefault(require("path"));
 const fs_1 = __importDefault(require("fs"));
 const worktree_service_js_1 = require("./worktree-service.js");
+const sseClients = new Set();
+let sseDebounceTimer = null;
+function broadcastChange() {
+    if (sseDebounceTimer !== null)
+        return;
+    sseDebounceTimer = setTimeout(() => {
+        sseDebounceTimer = null;
+        for (const client of sseClients) {
+            try {
+                client.write('data: {"type":"change"}\n\n');
+            }
+            catch {
+                sseClients.delete(client);
+            }
+        }
+    }, 200);
+}
+function watchSessionsDir(sessionsDir) {
+    try {
+        fs_1.default.mkdirSync(sessionsDir, { recursive: true });
+    }
+    catch { }
+    let watcher = null;
+    try {
+        watcher = fs_1.default.watch(sessionsDir, { recursive: true }, () => {
+            broadcastChange();
+        });
+        watcher.on('error', () => { });
+    }
+    catch {
+    }
+    return () => { watcher?.close(); };
+}
 function resolveConsoleDist() {
     const releasedDist = path_1.default.join(__dirname, '../../console');
     if (fs_1.default.existsSync(releasedDist))
@@ -21,6 +54,19 @@ function resolveConsoleDist() {
     return null;
 }
 function mountConsoleRoutes(app, consoleService) {
+    const stopWatcher = watchSessionsDir(consoleService.getSessionsDir());
+    process.once('exit', stopWatcher);
+    app.get('/api/v2/workspace/events', (req, res) => {
+        res.setHeader('Content-Type', 'text/event-stream');
+        res.setHeader('Cache-Control', 'no-cache');
+        res.setHeader('Connection', 'keep-alive');
+        res.setHeader('X-Accel-Buffering', 'no');
+        res.flushHeaders();
+        res.write('data: {"type":"connected"}\n\n');
+        sseClients.add(res);
+        req.on('close', () => { sseClients.delete(res); });
+        res.on('close', () => { sseClients.delete(res); });
+    });
     app.get('/api/v2/sessions', async (_req, res) => {
         const result = await consoleService.getSessionList();
         result.match((data) => res.json({ success: true, data }), (error) => res.status(500).json({ success: false, error: error.message }));
@@ -37,7 +83,9 @@ function mountConsoleRoutes(app, consoleService) {
             if (Date.now() > repoRootsExpiresAt) {
                 cwdRepoRootPromise ?? (cwdRepoRootPromise = (0, worktree_service_js_1.resolveRepoRoot)(process.cwd()));
                 const cwdRoot = await cwdRepoRootPromise;
-                const repoRootSet = new Set(sessions.map(s => s.repoRoot).filter((r) => r !== null));
+                const rawRoots = sessions.map(s => s.repoRoot).filter((r) => r !== null);
+                const resolvedRoots = await Promise.all(rawRoots.map(r => (0, worktree_service_js_1.resolveRepoRoot)(r)));
+                const repoRootSet = new Set(resolvedRoots.filter((r) => r !== null));
                 if (cwdRoot !== null)
                     repoRootSet.add(cwdRoot);
                 cachedRepoRoots = [...repoRootSet];

package/dist/v2/usecases/console-service.d.ts

@@ -15,6 +15,7 @@ export interface ConsoleServicePorts {
 export declare class ConsoleService {
     private readonly ports;
     constructor(ports: ConsoleServicePorts);
+    getSessionsDir(): string;
     getSessionList(): ResultAsync<ConsoleSessionListResponse, ConsoleServiceError>;
     getSessionDetail(sessionIdStr: string): ResultAsync<ConsoleSessionDetail, ConsoleServiceError>;
     getNodeDetail(sessionIdStr: string, nodeId: string): ResultAsync<ConsoleNodeDetail, ConsoleServiceError>;

package/dist/v2/usecases/console-service.js

@@ -19,6 +19,9 @@ class ConsoleService {
     constructor(ports) {
         this.ports = ports;
     }
+    getSessionsDir() {
+        return this.ports.dataDir.sessionsDir();
+    }
     getSessionList() {
         return this.ports.directoryListing
             .readdirWithMtime(this.ports.dataDir.sessionsDir())
@@ -243,7 +246,7 @@ function deriveSessionTitle(events) {
             for (const key of TITLE_CONTEXT_KEYS) {
                 const val = runCtx.context[key];
                 if (typeof val === 'string' && val.trim().length > 0) {
-                    return truncateTitle(val.trim());
+                    return val.trim();
                 }
             }
         }

package/dist/v2/usecases/console-types.d.ts

@@ -83,6 +83,11 @@ export interface ConsoleArtifact {
     readonly byteLength: number;
     readonly content: unknown;
 }
+export type FileChangeStatus = 'modified' | 'added' | 'deleted' | 'untracked' | 'renamed' | 'other';
+export interface ChangedFile {
+    readonly status: FileChangeStatus;
+    readonly path: string;
+}
 export interface ConsoleWorktreeSummary {
     readonly path: string;
     readonly name: string;
@@ -91,8 +96,15 @@ export interface ConsoleWorktreeSummary {
     readonly headMessage: string;
     readonly headTimestampMs: number;
     readonly changedCount: number;
+    readonly changedFiles: readonly ChangedFile[];
     readonly aheadCount: number;
+    readonly unpushedCommits: readonly {
+        readonly hash: string;
+        readonly message: string;
+    }[];
+    readonly isMerged: boolean;
     readonly activeSessionCount: number;
+    readonly description?: string;
 }
 export interface ConsoleRepoWorktrees {
     readonly repoName: string;

package/dist/v2/usecases/worktree-service.js

@@ -44,25 +44,69 @@ function parseWorktreePorcelain(raw) {
     }
     return entries;
 }
+function parseFileStatus(xy) {
+    if (xy === '??')
+        return 'untracked';
+    const x = xy[0] ?? ' ';
+    const y = xy[1] ?? ' ';
+    if (x === 'R')
+        return 'renamed';
+    if (x === 'A')
+        return 'added';
+    if (x === 'D' || y === 'D')
+        return 'deleted';
+    if (x === 'M' || y === 'M')
+        return 'modified';
+    return 'other';
+}
+function parseChangedFiles(statusRaw) {
+    if (!statusRaw)
+        return [];
+    return statusRaw
+        .split('\n')
+        .filter(line => line.trim().length > 0)
+        .map(line => ({
+        status: parseFileStatus(line.slice(0, 2)),
+        path: line.slice(3),
+    }));
+}
+const MAIN_BRANCH_REF = 'origin/main';
 async function enrichWorktree(wt) {
-    const [logRaw, statusRaw, aheadRaw] = await Promise.all([
+    const descriptionKey = wt.branch ? `branch.${wt.branch}.description` : null;
+    const [logRaw, statusRaw, aheadRaw, descriptionRaw, unpushedLogRaw, mergedBranchesRaw] = await Promise.all([
         git(wt.path, ['log', '-1', '--format=%h%n%s%n%ct']),
         git(wt.path, ['status', '--short']),
-        git(wt.path, ['rev-list', '--count', 'origin/main..HEAD']),
+        git(wt.path, ['rev-list', '--count', `${MAIN_BRANCH_REF}..HEAD`]),
+        descriptionKey ? git(wt.path, ['config', descriptionKey]) : Promise.resolve(null),
+        git(wt.path, ['log', `${MAIN_BRANCH_REF}..HEAD`, '--oneline']),
+        wt.branch && wt.branch !== 'main' ? git(wt.path, ['branch', '--merged', MAIN_BRANCH_REF]) : Promise.resolve(null),
     ]);
     const [hashLine, messageLine, timestampLine] = logRaw?.split('\n') ?? [];
     const headHash = hashLine?.trim() || wt.head.slice(0, 7);
     const headMessage = messageLine?.trim() ?? '';
     const headTimestampMs = timestampLine ? parseInt(timestampLine.trim(), 10) * 1000 : 0;
-    const changedCount = statusRaw !== null
-        ? statusRaw.split('\n').filter(l => l.trim()).length
-        : 0;
+    const changedFiles = statusRaw !== null ? parseChangedFiles(statusRaw) : [];
+    const changedCount = changedFiles.length;
     const parsedAhead = aheadRaw !== null ? parseInt(aheadRaw, 10) : NaN;
     const aheadCount = isNaN(parsedAhead) ? 0 : parsedAhead;
-    return { headHash, headMessage, headTimestampMs, changedCount, aheadCount };
+    const unpushedCommits = unpushedLogRaw
+        ? unpushedLogRaw.split('\n').filter(l => l.trim().length > 0).map(line => ({
+            hash: line.slice(0, 7),
+            message: line.slice(8),
+        }))
+        : [];
+    const isMerged = wt.branch !== null &&
+        wt.branch !== 'main' &&
+        mergedBranchesRaw !== null &&
+        mergedBranchesRaw.split('\n').some(line => line.trim() === wt.branch);
+    const branchDescription = descriptionRaw?.trim() ?? '';
+    return { headHash, headMessage, headTimestampMs, changedCount, changedFiles, aheadCount, unpushedCommits, isMerged, branchDescription };
 }
 async function resolveRepoRoot(path) {
-    return git(path, ['rev-parse', '--show-toplevel']);
+    const commonDir = await git(path, ['rev-parse', '--path-format=absolute', '--git-common-dir']);
+    if (commonDir === null)
+        return null;
+    return commonDir.replace(/\/\.git\/?$/, '') || null;
 }
 async function enrichRepo(repoRoot, activeSessions) {
     const porcelain = await git(repoRoot, ['worktree', 'list', '--porcelain']);
@@ -85,8 +129,12 @@ async function enrichRepo(repoRoot, activeSessions) {
                 headMessage: e.headMessage,
                 headTimestampMs: e.headTimestampMs,
                 changedCount: e.changedCount,
+                changedFiles: e.changedFiles,
                 aheadCount: e.aheadCount,
+                unpushedCommits: e.unpushedCommits,
+                isMerged: e.isMerged,
                 activeSessionCount: wt.branch ? (activeSessions.counts.get(wt.branch) ?? 0) : 0,
+                ...(e.branchDescription ? { description: e.branchDescription } : {}),
             }];
     });
     return [...worktrees].sort((a, b) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@exaudeus/workrail",
-  "version": "3.14.0",
+  "version": "3.15.0",
   "description": "Step-by-step workflow enforcement for AI agents via MCP",
   "license": "MIT",
   "repository": {
@@ -39,7 +39,7 @@
     "dev": "npm run build && node dist/mcp-server.js",
     "watch": "tsc --watch",
     "validate:workflows": "bash scripts/validate-workflows.sh",
-    "validate:registry": "node scripts/validate-workflows-registry.ts",
+    "validate:registry": "node --experimental-strip-types scripts/validate-workflows-registry.ts",
     "stamp-workflow": "node scripts/stamp-workflow.ts",
     "validate:authoring-spec": "node scripts/validate-authoring-spec.js",
     "validate:authoring-docs": "node scripts/generate-authoring-docs.js --check",

package/spec/authoring-spec.json

@@ -3,7 +3,7 @@
   "version": 3,
   "title": "WorkRail Authoring Rules",
   "purpose": "Canonical current rules for authoring good WorkRail workflows. workflow.schema.json remains the source of truth for legal structure.",
-  "lastReviewed": "2026-03-21",
+  "lastReviewed": "2026-04-04",
   "principles": [
     "Schema defines what is valid. These rules define what is good.",
     "Prefer current authoring rules over design rationale or historical notes.",
@@ -931,6 +931,87 @@
         }
       ]
     },
+    {
+      "id": "assessment-gates",
+      "title": "Assessment gates",
+      "rules": [
+        {
+          "id": "assessment-use-for-bounded-judgment",
+          "status": "active",
+          "level": "recommended",
+          "scope": [
+            "workflow.assessments",
+            "step.assessmentRefs",
+            "step.assessmentConsequences"
+          ],
+          "rule": "Use assessment gates when a step needs the agent to submit a bounded, durable judgment before the workflow can safely advance -- not for generic scoring or ceremony.",
+          "why": "Assessment gates force explicit structured reasoning at a decision point and durably record the result. Generic scoring that never affects routing adds noise without value.",
+          "enforcement": ["advisory"],
+          "sourceRefs": [
+            {
+              "kind": "example",
+              "path": "workflows/mr-review-workflow.agentic.v2.json",
+              "note": "Uses a three-dimension readiness gate on the final validation step."
+            },
+            {
+              "kind": "example",
+              "path": "workflows/bug-investigation.agentic.v2.json",
+              "note": "Uses a single-dimension diagnosis readiness gate before handoff."
+            }
+          ],
+          "checks": [
+            "The assessment is at a step where a wrong answer would produce a bad handoff.",
+            "At least one dimension has a consequence that keeps the step pending and requires follow-up.",
+            "The assessment result is durably recorded and useful to a future resume agent."
+          ],
+          "antiPatterns": [
+            "Using assessments as a generic five-level scoring rubric with no routing consequence",
+            "Declaring an assessment but never referencing it from any step"
+          ]
+        },
+        {
+          "id": "assessment-dimension-orthogonality",
+          "status": "active",
+          "level": "required",
+          "scope": [
+            "workflow.assessments"
+          ],
+          "rule": "Each dimension in an assessment must capture a distinct failure mode that the other dimensions cannot catch. A dimension that restates existing workflow state (such as a generic 'confidence' dimension that mirrors the workflow's confidence band) adds ceremony without structure.",
+          "why": "The value of multiple dimensions is that each one independently blocks advancement for a different reason. Correlated or vague dimensions collapse to a single gate with extra steps.",
+          "enforcement": ["advisory"],
+          "checks": [
+            "Each dimension is independently checkable without needing to know the result of the others.",
+            "No dimension restates a context variable the workflow already computes (e.g. recommendationConfidenceBand).",
+            "A 'low' rating on any one dimension alone justifies a follow-up, regardless of the others."
+          ],
+          "antiPatterns": [
+            "A single 'confidence' dimension that mirrors the workflow's existing confidence band",
+            "Multiple dimensions that all reduce to 'did I do a good job overall'",
+            "Dimensions so correlated that one being low always means the others are low too"
+          ]
+        },
+        {
+          "id": "assessment-v1-constraints",
+          "status": "active",
+          "level": "required",
+          "scope": [
+            "step.assessmentRefs",
+            "step.assessmentConsequences"
+          ],
+          "rule": "V1 supports exactly one assessmentRef per step and at most one assessmentConsequences entry per step. Use anyEqualsLevel as the trigger -- the engine checks all submitted dimensions and fires if any equals that level.",
+          "why": "anyEqualsLevel is the only trigger form. It works for both single-dimension and multi-dimension assessments without requiring the author to choose between two forms.",
+          "enforcement": ["schema"],
+          "checks": [
+            "No more than one assessmentRefs entry per step.",
+            "No more than one assessmentConsequences entry per step.",
+            "The consequence uses anyEqualsLevel to declare which level blocks -- not a named dimension."
+          ],
+          "antiPatterns": [
+            "Trying to encode multiple consequences via workarounds"
+          ]
+        }
+      ]
+    },
     {
       "id": "delegation",
       "title": "Delegation and subagents",

package/spec/workflow-tags.json

@@ -0,0 +1,132 @@
+{
+  "$schema": "./workflow-tags.schema.json",
+  "version": 1,
+  "tags": [
+    {
+      "id": "coding",
+      "displayName": "Coding & Development",
+      "when": [
+        "implementing a feature or task",
+        "refactoring or improving existing code",
+        "converting code between platforms or languages"
+      ],
+      "examples": ["coding-task-workflow-agentic", "cross-platform-code-conversion"]
+    },
+    {
+      "id": "review_audit",
+      "displayName": "Review & Audit",
+      "when": [
+        "reviewing a merge request before merging",
+        "auditing a service for production readiness",
+        "checking architecture for scalability issues"
+      ],
+      "examples": ["mr-review-workflow-agentic", "production-readiness-audit"]
+    },
+    {
+      "id": "investigation",
+      "displayName": "Investigation & Debugging",
+      "when": [
+        "diagnosing a bug or unexpected behavior in code",
+        "diagnosing tool, environment, or MCP server issues"
+      ],
+      "examples": ["bug-investigation-agentic", "workflow-diagnose-environment"]
+    },
+    {
+      "id": "design",
+      "displayName": "Design & Discovery",
+      "when": [
+        "designing a UI or UX feature from scratch",
+        "exploring and thinking through a problem or decision",
+        "generating and comparing design candidates"
+      ],
+      "examples": ["ui-ux-design-workflow", "wr.discovery"]
+    },
+    {
+      "id": "documentation",
+      "displayName": "Documentation",
+      "when": [
+        "creating new documentation for a project, feature, or API",
+        "updating or maintaining existing documentation",
+        "writing documentation for a single bounded component or concept"
+      ],
+      "examples": ["document-creation-workflow", "documentation-update-workflow"]
+    },
+    {
+      "id": "tickets",
+      "displayName": "Tickets & Planning",
+      "when": [
+        "creating Jira tickets for a feature or epic",
+        "grooming and refining a backlog",
+        "generating test cases from ticket requirements"
+      ],
+      "examples": ["adaptive-ticket-creation", "ticket-grooming"]
+    },
+    {
+      "id": "learning",
+      "displayName": "Learning & Personal",
+      "when": [
+        "creating learning materials or a course",
+        "designing a presentation",
+        "making a major personal decision like where to relocate"
+      ],
+      "examples": ["personal-learning-materials-creation-branched", "presentation-creation"]
+    },
+    {
+      "id": "routines",
+      "displayName": "Routines",
+      "when": [
+        "gathering context about a codebase",
+        "generating design candidates",
+        "running a hypothesis challenge or adversarial review",
+        "running a final verification pass"
+      ],
+      "examples": ["routine-context-gathering", "routine-hypothesis-challenge"]
+    },
+    {
+      "id": "authoring",
+      "displayName": "Workflow Authoring",
+      "when": [
+        "creating a new WorkRail workflow from scratch",
+        "modernizing or updating an existing workflow"
+      ],
+      "examples": ["workflow-for-workflows"]
+    }
+  ],
+  "workflows": {
+    "adaptive-ticket-creation": { "tags": ["tickets"] },
+    "architecture-scalability-audit": { "tags": ["review_audit"] },
+    "bug-investigation-agentic": { "tags": ["investigation"] },
+    "coding-task-workflow-agentic": { "tags": ["coding"] },
+    "cross-platform-code-conversion": { "tags": ["coding"] },
+    "document-creation-workflow": { "tags": ["documentation"] },
+    "documentation-update-workflow": { "tags": ["documentation"] },
+    "intelligent-test-case-generation": { "tags": ["tickets", "coding"] },
+    "mr-review-workflow-agentic": { "tags": ["review_audit"] },
+    "personal-learning-course-design": { "tags": ["learning"] },
+    "personal-learning-materials-creation-branched": { "tags": ["learning"] },
+    "presentation-creation": { "tags": ["learning"] },
+    "production-readiness-audit": { "tags": ["review_audit"] },
+    "relocation-workflow-us": { "tags": ["learning"] },
+    "routine-context-gathering": { "tags": ["routines"] },
+    "routine-design-review": { "tags": ["routines"] },
+    "routine-execution-simulation": { "tags": ["routines"] },
+    "routine-feature-implementation": { "tags": ["routines", "coding"] },
+    "routine-final-verification": { "tags": ["routines"] },
+    "routine-hypothesis-challenge": { "tags": ["routines"] },
+    "routine-ideation": { "tags": ["routines"] },
+    "routine-parallel-work-partitioning": { "tags": ["routines"] },
+    "routine-philosophy-alignment": { "tags": ["routines"] },
+    "routine-plan-analysis": { "tags": ["routines"] },
+    "routine-plan-generation": { "tags": ["routines"] },
+    "routine-tension-driven-design": { "tags": ["routines"] },
+    "scoped-documentation-workflow": { "tags": ["documentation"] },
+    "ticket-grooming": { "tags": ["tickets"] },
+    "ui-ux-design-workflow": { "tags": ["design"] },
+    "workflow-diagnose-environment": { "tags": ["investigation"] },
+    "workflow-for-workflows": { "tags": ["authoring"] },
+    "wr.discovery": { "tags": ["design", "investigation"] },
+    "test-artifact-loop-control": { "tags": ["coding"], "hidden": true },
+    "test-session-persistence": { "tags": ["coding"], "hidden": true },
+    "test-missing-context": { "tags": ["coding"], "hidden": true }
+  }
+}

package/spec/workflow.schema.json

@@ -1064,23 +1064,15 @@
     },
     "assessmentConsequenceTrigger": {
       "type": "object",
-      "description": "Exact-match trigger on one declared assessment dimension and one declared canonical level.",
+      "description": "Fires when ANY dimension in the submitted assessment equals the given level. The consequence blocks advancement until the agent addresses all dimensions that scored at that level.",
       "properties": {
-        "dimensionId": {
-          "type": "string",
-          "minLength": 1,
-          "maxLength": 64
-        },
-        "equalsLevel": {
+        "anyEqualsLevel": {
           "type": "string",
           "minLength": 1,
           "maxLength": 64
         }
       },
-      "required": [
-        "dimensionId",
-        "equalsLevel"
-      ],
+      "required": ["anyEqualsLevel"],
       "additionalProperties": false
     },
     "assessmentConsequenceEffect": {