@exaudeus/workrail 3.13.0 → 3.14.0

package/dist/manifest.json

@@ -942,12 +942,12 @@
       "bytes": 22303
     },
     "mcp/handlers/v2-workflow.d.ts": {
-      "sha256": "5c9590f121dd3708c516be3febe41d0be47531d643462b86b99b778ef0b54498",
-      "bytes": 396
+      "sha256": "d2a6af1bc62630e62f10c9564c60b7f3e7d1ff0b4e6339416a6d6bfcd935ee53",
+      "bytes": 699
     },
     "mcp/handlers/v2-workflow.js": {
-      "sha256": "e496675cf8ae2259e0c5a53692732a231fb4c923440214df4e54f696bb7ab734",
-      "bytes": 16632
+      "sha256": "545ad0cafe58f42010db5e32be2cbb302d3d1fc989022e5803a0bce077cc91a1",
+      "bytes": 19047
     },
     "mcp/handlers/v2-workspace-resolution.d.ts": {
       "sha256": "dd4de57b4918ebe749cf8c1df70c02bf1effc50932634bae60db53c9a157e872",
@@ -974,12 +974,12 @@
       "bytes": 7991
     },
     "mcp/output-schemas.d.ts": {
-      "sha256": "77c29cf4cc1500fccd383b8a725b3a4b30c7d1913ec31419b607b3e9f358f652",
-      "bytes": 86643
+      "sha256": "8da92586db497fe2f37df296c3ac95751a6b326ceb0bd348f126b3a9f44515e5",
+      "bytes": 90073
     },
     "mcp/output-schemas.js": {
-      "sha256": "692e8b71740b8b3f89a541b8bc57992ce1b4149b117c5e19d77988777e0b215e",
-      "bytes": 19084
+      "sha256": "d3446f0480e80dd0c7030b42f66489e982b93b968700371cffcbf1fb8d0fed96",
+      "bytes": 19456
     },
     "mcp/render-envelope.d.ts": {
       "sha256": "22e83e1aba52968a7136cf289125a217b5f462a5a66a1eebe4669006e3326fdb",
@@ -1366,8 +1366,8 @@
       "bytes": 395
     },
     "types/workflow-definition.d.ts": {
-      "sha256": "052ef59dd8ee28dc2648eb5f30a60023af18bb92dcde9b0664cc035e42ca4f52",
-      "bytes": 5796
+      "sha256": "683e5a939e0265f194a9a542d6c925222b090c5da5f9b94df07b0cf16ec40165",
+      "bytes": 5847
     },
     "types/workflow-definition.js": {
       "sha256": "204e7500d3d0dc91b1716199efb89af4776fb488546661e809f76be9333ea65c",

package/dist/mcp/handlers/v2-workflow.d.ts

@@ -1,4 +1,7 @@
 import type { ToolContext, ToolResult } from '../types.js';
 import type { V2InspectWorkflowInput, V2ListWorkflowsInput } from '../v2/tools.js';
+import type { StalenessSummary } from '../output-schemas.js';
+export declare function shouldShowStaleness(category: string | undefined, devMode?: boolean): boolean;
+export declare function computeWorkflowStaleness(stamp: number | undefined, currentVersion: number | null): StalenessSummary | undefined;
 export declare function handleV2ListWorkflows(input: V2ListWorkflowsInput, ctx: ToolContext): Promise<ToolResult<unknown>>;
 export declare function handleV2InspectWorkflow(input: V2InspectWorkflowInput, ctx: ToolContext): Promise<ToolResult<unknown>>;

package/dist/mcp/handlers/v2-workflow.js

@@ -3,9 +3,12 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.shouldShowStaleness = shouldShowStaleness;
+exports.computeWorkflowStaleness = computeWorkflowStaleness;
 exports.handleV2ListWorkflows = handleV2ListWorkflows;
 exports.handleV2InspectWorkflow = handleV2InspectWorkflow;
 const path_1 = __importDefault(require("path"));
+const fs_1 = __importDefault(require("fs"));
 const neverthrow_1 = require("neverthrow");
 const types_js_1 = require("../types.js");
 const error_mapper_js_1 = require("../error-mapper.js");
@@ -14,6 +17,51 @@ const output_schemas_js_1 = require("../output-schemas.js");
 const v1_to_v2_shim_js_1 = require("../../v2/read-only/v1-to-v2-shim.js");
 const hashing_js_1 = require("../../v2/durable-core/canonical/hashing.js");
 const TIMEOUT_MS = 30000;
+function readCurrentSpecVersion() {
+    try {
+        const specPath = path_1.default.resolve(__dirname, '../../../spec/authoring-spec.json');
+        const raw = fs_1.default.readFileSync(specPath, 'utf-8');
+        const parsed = JSON.parse(raw);
+        if (typeof parsed === 'object' && parsed !== null && 'version' in parsed) {
+            const v = parsed['version'];
+            if (typeof v === 'number' && Number.isInteger(v) && v >= 1)
+                return v;
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+const CURRENT_SPEC_VERSION = readCurrentSpecVersion();
+const DEV_STALENESS = process.env['WORKRAIL_DEV_STALENESS'] === '1';
+function shouldShowStaleness(category, devMode = DEV_STALENESS) {
+    if (devMode)
+        return true;
+    return category === 'personal' || category === 'rooted_sharing' || category === 'external';
+}
+function computeWorkflowStaleness(stamp, currentVersion) {
+    if (currentVersion === null)
+        return undefined;
+    if (stamp === undefined) {
+        return {
+            level: 'possible',
+            reason: 'This workflow has not been validated against the authoring spec via workflow-for-workflows.',
+        };
+    }
+    if (stamp === currentVersion) {
+        return {
+            level: 'none',
+            reason: `Workflow validated against current authoring spec (v${currentVersion}).`,
+            specVersionAtLastReview: stamp,
+        };
+    }
+    return {
+        level: 'likely',
+        reason: `Authoring spec updated from v${stamp} to v${currentVersion} since this workflow was last reviewed.`,
+        specVersionAtLastReview: stamp,
+    };
+}
 const with_timeout_js_1 = require("./shared/with-timeout.js");
 const request_workflow_reader_js_1 = require("./shared/request-workflow-reader.js");
 const remembered_roots_js_1 = require("./shared/remembered-roots.js");
@@ -142,6 +190,12 @@ async function handleV2InspectWorkflow(input, ctx) {
                 ...(visibility ? { visibility } : {}),
                 ...(stalePaths.length > 0 ? { staleRoots: [...stalePaths] } : {}),
                 ...(references != null && references.length > 0 ? { references } : {}),
+                ...(() => {
+                    const staleness = shouldShowStaleness(visibility?.category)
+                        ? computeWorkflowStaleness(workflow.definition.validatedAgainstSpecVersion, CURRENT_SPEC_VERSION)
+                        : undefined;
+                    return staleness !== undefined ? { staleness } : {};
+                })(),
             });
             return (0, neverthrow_1.okAsync)((0, types_js_1.success)(payload));
         }));
@@ -199,6 +253,9 @@ async function buildV2WorkflowListItem(options) {
             };
         }
     }
+    const staleness = shouldShowStaleness(visibility?.category)
+        ? computeWorkflowStaleness(workflow.definition.validatedAgainstSpecVersion, CURRENT_SPEC_VERSION)
+        : undefined;
     return {
         workflowId: summary.id,
         name: summary.name,
@@ -207,6 +264,7 @@ async function buildV2WorkflowListItem(options) {
         workflowHash: hash,
         kind: 'workflow',
         visibility,
+        ...(staleness !== undefined ? { staleness } : {}),
     };
 }
 async function buildSourceCatalog(workflowReader, rememberedRootRecords) {

package/dist/mcp/output-schemas.d.ts

@@ -152,6 +152,20 @@ export declare const WorkflowGetSchemaOutputSchema: z.ZodObject<{
         stepStructure: Record<string, string>;
     };
 }>;
+export declare const StalenessSummarySchema: z.ZodObject<{
+    level: z.ZodEnum<["none", "possible", "likely"]>;
+    reason: z.ZodString;
+    specVersionAtLastReview: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    level: "none" | "possible" | "likely";
+    reason: string;
+    specVersionAtLastReview?: number | undefined;
+}, {
+    level: "none" | "possible" | "likely";
+    reason: string;
+    specVersionAtLastReview?: number | undefined;
+}>;
+export type StalenessSummary = z.infer<typeof StalenessSummarySchema>;
 export declare const V2WorkflowListItemSchema: z.ZodObject<{
     workflowId: z.ZodString;
     name: z.ZodString;
@@ -235,6 +249,19 @@ export declare const V2WorkflowListItemSchema: z.ZodObject<{
             currentSource: "legacy_project";
         } | undefined;
     }>>;
+    staleness: z.ZodOptional<z.ZodObject<{
+        level: z.ZodEnum<["none", "possible", "likely"]>;
+        reason: z.ZodString;
+        specVersionAtLastReview: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        level: "none" | "possible" | "likely";
+        reason: string;
+        specVersionAtLastReview?: number | undefined;
+    }, {
+        level: "none" | "possible" | "likely";
+        reason: string;
+        specVersionAtLastReview?: number | undefined;
+    }>>;
 }, "strip", z.ZodTypeAny, {
     kind: "workflow";
     name: string;
@@ -260,6 +287,11 @@ export declare const V2WorkflowListItemSchema: z.ZodObject<{
             currentSource: "legacy_project";
         } | undefined;
     } | undefined;
+    staleness?: {
+        level: "none" | "possible" | "likely";
+        reason: string;
+        specVersionAtLastReview?: number | undefined;
+    } | undefined;
 }, {
     kind: "workflow";
     name: string;
@@ -285,6 +317,11 @@ export declare const V2WorkflowListItemSchema: z.ZodObject<{
             currentSource: "legacy_project";
         } | undefined;
     } | undefined;
+    staleness?: {
+        level: "none" | "possible" | "likely";
+        reason: string;
+        specVersionAtLastReview?: number | undefined;
+    } | undefined;
 }>;
 export declare const V2WorkflowSourceCatalogEntrySchema: z.ZodObject<{
     sourceKey: z.ZodString;
@@ -461,6 +498,19 @@ export declare const V2WorkflowListOutputSchema: z.ZodObject<{
                 currentSource: "legacy_project";
             } | undefined;
         }>>;
+        staleness: z.ZodOptional<z.ZodObject<{
+            level: z.ZodEnum<["none", "possible", "likely"]>;
+            reason: z.ZodString;
+            specVersionAtLastReview: z.ZodOptional<z.ZodNumber>;
+        }, "strip", z.ZodTypeAny, {
+            level: "none" | "possible" | "likely";
+            reason: string;
+            specVersionAtLastReview?: number | undefined;
+        }, {
+            level: "none" | "possible" | "likely";
+            reason: string;
+            specVersionAtLastReview?: number | undefined;
+        }>>;
     }, "strip", z.ZodTypeAny, {
         kind: "workflow";
         name: string;
@@ -486,6 +536,11 @@ export declare const V2WorkflowListOutputSchema: z.ZodObject<{
                 currentSource: "legacy_project";
             } | undefined;
         } | undefined;
+        staleness?: {
+            level: "none" | "possible" | "likely";
+            reason: string;
+            specVersionAtLastReview?: number | undefined;
+        } | undefined;
     }, {
         kind: "workflow";
         name: string;
@@ -511,6 +566,11 @@ export declare const V2WorkflowListOutputSchema: z.ZodObject<{
                 currentSource: "legacy_project";
             } | undefined;
         } | undefined;
+        staleness?: {
+            level: "none" | "possible" | "likely";
+            reason: string;
+            specVersionAtLastReview?: number | undefined;
+        } | undefined;
     }>, "many">;
     staleRoots: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
     sources: z.ZodOptional<z.ZodArray<z.ZodObject<{
@@ -630,6 +690,11 @@ export declare const V2WorkflowListOutputSchema: z.ZodObject<{
                 currentSource: "legacy_project";
             } | undefined;
         } | undefined;
+        staleness?: {
+            level: "none" | "possible" | "likely";
+            reason: string;
+            specVersionAtLastReview?: number | undefined;
+        } | undefined;
     }[];
     sources?: {
         source: {
@@ -681,6 +746,11 @@ export declare const V2WorkflowListOutputSchema: z.ZodObject<{
                 currentSource: "legacy_project";
             } | undefined;
         } | undefined;
+        staleness?: {
+            level: "none" | "possible" | "likely";
+            reason: string;
+            specVersionAtLastReview?: number | undefined;
+        } | undefined;
     }[];
     sources?: {
         source: {
@@ -811,6 +881,19 @@ export declare const V2WorkflowInspectOutputSchema: z.ZodObject<{
         authoritative: boolean;
         resolveFrom?: "workspace" | "package" | undefined;
     }>, "many">>;
+    staleness: z.ZodOptional<z.ZodObject<{
+        level: z.ZodEnum<["none", "possible", "likely"]>;
+        reason: z.ZodString;
+        specVersionAtLastReview: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        level: "none" | "possible" | "likely";
+        reason: string;
+        specVersionAtLastReview?: number | undefined;
+    }, {
+        level: "none" | "possible" | "likely";
+        reason: string;
+        specVersionAtLastReview?: number | undefined;
+    }>>;
 }, "strip", z.ZodTypeAny, {
     workflowId: string;
     workflowHash: string;
@@ -842,6 +925,11 @@ export declare const V2WorkflowInspectOutputSchema: z.ZodObject<{
             currentSource: "legacy_project";
         } | undefined;
     } | undefined;
+    staleness?: {
+        level: "none" | "possible" | "likely";
+        reason: string;
+        specVersionAtLastReview?: number | undefined;
+    } | undefined;
     staleRoots?: string[] | undefined;
 }, {
     workflowId: string;
@@ -874,6 +962,11 @@ export declare const V2WorkflowInspectOutputSchema: z.ZodObject<{
             currentSource: "legacy_project";
         } | undefined;
     } | undefined;
+    staleness?: {
+        level: "none" | "possible" | "likely";
+        reason: string;
+        specVersionAtLastReview?: number | undefined;
+    } | undefined;
     staleRoots?: string[] | undefined;
 }>;
 export declare const V2PendingStepSchema: z.ZodObject<{

package/dist/mcp/output-schemas.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.OpenDashboardOutputSchema = exports.ReadSessionSchemaOutputSchema = exports.ReadSessionOutputSchema = exports.UpdateSessionOutputSchema = exports.CreateSessionOutputSchema = exports.V2StartWorkflowOutputSchema = exports.V2CheckpointWorkflowOutputSchema = exports.V2ResumeSessionOutputSchema = exports.V2ContinueWorkflowOutputSchema = exports.V2StepContextSchema = exports.V2BindingDriftWarningSchema = exports.V2BlockerReportSchema = exports.V2ResumeNextCallSchema = exports.V2NextCallSchema = exports.V2NextIntentSchema = exports.V2PreferencesSchema = exports.V2PendingStepSchema = exports.V2WorkflowInspectOutputSchema = exports.V2WorkflowListOutputSchema = exports.V2WorkflowSourceCatalogEntrySchema = exports.V2WorkflowListItemSchema = exports.WorkflowGetSchemaOutputSchema = exports.WorkflowValidateJsonOutputSchema = exports.WorkflowNextOutputSchema = exports.WorkflowGetOutputSchema = exports.WorkflowListOutputSchema = exports.WorkflowSummarySchema = exports.JsonValueSchema = void 0;
+exports.OpenDashboardOutputSchema = exports.ReadSessionSchemaOutputSchema = exports.ReadSessionOutputSchema = exports.UpdateSessionOutputSchema = exports.CreateSessionOutputSchema = exports.V2StartWorkflowOutputSchema = exports.V2CheckpointWorkflowOutputSchema = exports.V2ResumeSessionOutputSchema = exports.V2ContinueWorkflowOutputSchema = exports.V2StepContextSchema = exports.V2BindingDriftWarningSchema = exports.V2BlockerReportSchema = exports.V2ResumeNextCallSchema = exports.V2NextCallSchema = exports.V2NextIntentSchema = exports.V2PreferencesSchema = exports.V2PendingStepSchema = exports.V2WorkflowInspectOutputSchema = exports.V2WorkflowListOutputSchema = exports.V2WorkflowSourceCatalogEntrySchema = exports.V2WorkflowListItemSchema = exports.StalenessSummarySchema = exports.WorkflowGetSchemaOutputSchema = exports.WorkflowValidateJsonOutputSchema = exports.WorkflowNextOutputSchema = exports.WorkflowGetOutputSchema = exports.WorkflowListOutputSchema = exports.WorkflowSummarySchema = exports.JsonValueSchema = void 0;
 exports.toPendingStep = toPendingStep;
 const zod_1 = require("zod");
 const state_js_1 = require("../domain/execution/state.js");
@@ -48,6 +48,11 @@ exports.WorkflowGetSchemaOutputSchema = zod_1.z.object({
         stepStructure: zod_1.z.record(zod_1.z.string()),
     }),
 });
+exports.StalenessSummarySchema = zod_1.z.object({
+    level: zod_1.z.enum(['none', 'possible', 'likely']),
+    reason: zod_1.z.string().min(1),
+    specVersionAtLastReview: zod_1.z.number().int().positive().optional(),
+});
 exports.V2WorkflowListItemSchema = zod_1.z.object({
     workflowId: zod_1.z.string().min(1),
     name: zod_1.z.string().min(1),
@@ -73,6 +78,7 @@ exports.V2WorkflowListItemSchema = zod_1.z.object({
             summary: zod_1.z.string().min(1),
         }).optional(),
     }).optional(),
+    staleness: exports.StalenessSummarySchema.optional(),
 });
 exports.V2WorkflowSourceCatalogEntrySchema = zod_1.z.object({
     sourceKey: zod_1.z.string().min(1).describe('Stable identifier for this source. Format: "{kind}:{absolutePath}" for filesystem sources (e.g. "project:/path/to/workflows", "custom:/path/to/.workrail/workflows"), or "built_in" for bundled sources.'),
@@ -122,6 +128,7 @@ exports.V2WorkflowInspectOutputSchema = zod_1.z.object({
         authoritative: zod_1.z.boolean(),
         resolveFrom: zod_1.z.enum(['workspace', 'package']).optional(),
     })).optional(),
+    staleness: exports.StalenessSummarySchema.optional(),
 });
 exports.V2PendingStepSchema = zod_1.z.object({
     stepId: zod_1.z.string().min(1),

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

@@ -134,6 +134,7 @@ export interface WorkflowDefinition {
     readonly assessments?: readonly AssessmentDefinition[];
     readonly extensionPoints?: readonly ExtensionPoint[];
     readonly references?: readonly WorkflowReference[];
+    readonly validatedAgainstSpecVersion?: number;
 }
 export declare function isLoopStepDefinition(step: WorkflowStepDefinition | LoopStepDefinition): step is LoopStepDefinition;
 export declare function isWorkflowStepDefinition(step: WorkflowStepDefinition | LoopStepDefinition): step is WorkflowStepDefinition;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@exaudeus/workrail",
-  "version": "3.13.0",
+  "version": "3.14.0",
   "description": "Step-by-step workflow enforcement for AI agents via MCP",
   "license": "MIT",
   "repository": {
@@ -40,6 +40,7 @@
     "watch": "tsc --watch",
     "validate:workflows": "bash scripts/validate-workflows.sh",
     "validate:registry": "node 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",
     "validate:workflow-discovery": "node scripts/validate-workflow-discovery.js",

package/spec/authoring-spec.json

@@ -20,7 +20,8 @@
     "When a workflow feature lands or changes, update the schema and runtime first.",
     "Then update this authoring spec so guidance matches the shipped behavior.",
     "Then regenerate or update human-facing docs and examples derived from this spec.",
-    "Do not leave authoring guidance behind the runtime."
+    "Do not leave authoring guidance behind the runtime.",
+    "Increment `version` when any required-level rule is added, removed, or materially changed. Add a `changelog` entry for the new version."
   ],
   "ruleModel": {
     "levels": [
@@ -1402,6 +1403,12 @@
       ]
     }
   ],
-  "plannedRules": [
+  "plannedRules": [],
+  "changelog": [
+    {
+      "version": 3,
+      "date": "2026-03-21",
+      "summary": "Baseline version at staleness feature introduction."
+    }
   ]
 }