@exaudeus/workrail 3.8.1 → 3.9.0

package/dist/mcp/output-schemas.js

@@ -54,6 +54,24 @@ exports.V2WorkflowListItemSchema = zod_1.z.object({
     version: zod_1.z.string().min(1),
     kind: zod_1.z.literal('workflow'),
     workflowHash: zod_1.z.string().nullable(),
+    visibility: zod_1.z.object({
+        category: zod_1.z.enum(['built_in', 'personal', 'legacy_project', 'rooted_sharing', 'external']),
+        source: zod_1.z.object({
+            kind: zod_1.z.enum(['bundled', 'user', 'project', 'custom', 'git', 'remote', 'plugin']),
+            displayName: zod_1.z.string().min(1),
+        }),
+        rootedSharing: zod_1.z.object({
+            kind: zod_1.z.literal('remembered_root'),
+            rootPath: zod_1.z.string().min(1),
+            groupLabel: zod_1.z.string().min(1),
+        }).optional(),
+        migration: zod_1.z.object({
+            preferredSource: zod_1.z.literal('rooted_sharing'),
+            currentSource: zod_1.z.literal('legacy_project'),
+            reason: zod_1.z.literal('legacy_project_precedence'),
+            summary: zod_1.z.string().min(1),
+        }).optional(),
+    }).optional(),
 });
 exports.V2WorkflowListOutputSchema = zod_1.z.object({
     workflows: zod_1.z.array(exports.V2WorkflowListItemSchema),
@@ -63,6 +81,7 @@ exports.V2WorkflowInspectOutputSchema = zod_1.z.object({
     workflowHash: zod_1.z.string().min(1),
     mode: zod_1.z.enum(['metadata', 'preview']),
     compiled: exports.JsonValueSchema,
+    visibility: exports.V2WorkflowListItemSchema.shape.visibility.optional(),
     references: zod_1.z.array(zod_1.z.object({
         id: zod_1.z.string().min(1),
         title: zod_1.z.string().min(1),

package/dist/mcp/server.js

@@ -109,6 +109,7 @@ async function createToolContext() {
             if (aliasLoadResult.isErr()) {
                 console.error(`[V2Init] Token alias index load warning: ${aliasLoadResult.error.message}`);
             }
+            const rememberedRootsStore = container_js_1.container.resolve(tokens_js_1.DI.V2.RememberedRootsStore);
             v2 = {
                 gate,
                 sessionStore,
@@ -120,6 +121,7 @@ async function createToolContext() {
                 idFactory,
                 tokenCodecPorts,
                 tokenAliasStore,
+                rememberedRootsStore,
                 validationPipelineDeps,
                 resolvedRootUris: [],
                 workspaceResolver: new index_js_1.LocalWorkspaceAnchorV2(process.cwd()),

package/dist/mcp/tool-descriptions.js

@@ -52,16 +52,21 @@ This tool provides:
 
 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.
 
-Pass workspacePath when available so project-scoped workflow variants are resolved against the correct workspace instead of the server's fallback directory.`,
+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).
 
 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.
 
+Parameters:
+- workflowId: The workflow to inspect
+- mode: metadata mode shows name/description only; preview mode shows the full step breakdown
+- workspacePath: absolute workspace path for correct project-scoped workflow resolution
+
 Returns:
 - metadata mode: Just name and description
 - preview mode: Full step-by-step breakdown (default)
 
-Pass workspacePath when available so project-scoped workflow variants are resolved against the correct workspace.
+Always pass workspacePath so project-scoped workflow variants are resolved against the correct workspace. Shared MCP servers cannot infer this safely.
 
 Remember: inspecting is read-only. Call start_workflow when ready to begin.`,
         start_workflow: (0, workflow_protocol_contracts_js_1.renderProtocolDescription)(workflow_protocol_contracts_js_1.START_WORKFLOW_PROTOCOL, 'standard'),
@@ -130,7 +135,7 @@ Workflows are the user's pre-defined instructions for complex tasks. When a work
 
 Returns stable workflow metadata and pinned snapshot hashes (workflowHash) for deterministic execution.
 
-Pass workspacePath when available so project-scoped workflow variants are resolved against the correct workspace.`,
+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).
 
 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.
@@ -138,7 +143,7 @@ Use this to understand the workflow's structure before starting. The workflow is
 Parameters:
 - workflowId: The workflow to inspect
 - mode: 'metadata' (name/description only) or 'preview' (full step breakdown)
-- workspacePath: optional absolute workspace path for correct project-scoped workflow resolution
+- workspacePath: absolute workspace path for correct project-scoped workflow resolution
 
 This is read-only. Call start_workflow when ready to commit to following the workflow.`,
         start_workflow: (0, workflow_protocol_contracts_js_1.renderProtocolDescription)(workflow_protocol_contracts_js_1.START_WORKFLOW_PROTOCOL, 'authoritative'),

package/dist/mcp/types.d.ts

@@ -19,6 +19,7 @@ import type { SessionSummaryProviderPortV2 } from '../v2/ports/session-summary-p
 import type { ValidationPipelineDepsPhase1a } from '../application/services/workflow-validation-pipeline.js';
 import type { TokenAliasStorePortV2 } from '../v2/ports/token-alias-store.port.js';
 import type { RandomEntropyPortV2 } from '../v2/ports/random-entropy.port.js';
+import type { RememberedRootsStorePortV2 } from '../v2/ports/remembered-roots-store.port.js';
 export interface SessionHealthDetails {
     readonly health: SessionHealthV2;
 }
@@ -59,6 +60,7 @@ export interface V2Dependencies {
     readonly idFactory: IdFactoryV2;
     readonly tokenCodecPorts: TokenCodecPorts;
     readonly tokenAliasStore: TokenAliasStorePortV2;
+    readonly rememberedRootsStore?: RememberedRootsStorePortV2;
     readonly entropy: RandomEntropyPortV2;
     readonly validationPipelineDeps: ValidationPipelineDepsPhase1a;
     readonly resolvedRootUris?: readonly string[];

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

@@ -1,24 +1,24 @@
 import { z } from 'zod';
 import type { ToolAnnotations } from '../tool-factory.js';
 export declare const V2ListWorkflowsInput: z.ZodObject<{
-    workspacePath: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+    workspacePath: z.ZodEffects<z.ZodString, string, string>;
 }, "strip", z.ZodTypeAny, {
-    workspacePath?: string | undefined;
+    workspacePath: string;
 }, {
-    workspacePath?: string | undefined;
+    workspacePath: string;
 }>;
 export type V2ListWorkflowsInput = z.infer<typeof V2ListWorkflowsInput>;
 export declare const V2InspectWorkflowInput: z.ZodObject<{
     workflowId: z.ZodString;
     mode: z.ZodDefault<z.ZodEnum<["metadata", "preview"]>>;
-    workspacePath: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+    workspacePath: z.ZodEffects<z.ZodString, string, string>;
 }, "strip", z.ZodTypeAny, {
     workflowId: string;
+    workspacePath: string;
     mode: "metadata" | "preview";
-    workspacePath?: string | undefined;
 }, {
     workflowId: string;
-    workspacePath?: string | undefined;
+    workspacePath: string;
     mode?: "metadata" | "preview" | undefined;
 }>;
 export type V2InspectWorkflowInput = z.infer<typeof V2InspectWorkflowInput>;

package/dist/mcp/v2/tools.js

@@ -15,12 +15,12 @@ const workspacePathField = zod_1.z.string()
     .describe('Absolute path to your current workspace directory (e.g. the "Workspace:" value from your system parameters). Used to resolve project-scoped workflow variants against the correct workspace. If omitted, WorkRail uses MCP roots when available, then falls back to the server process directory.');
 const optionalWorkspacePathField = workspacePathField.optional();
 exports.V2ListWorkflowsInput = zod_1.z.object({
-    workspacePath: optionalWorkspacePathField,
+    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.'),
 });
 exports.V2InspectWorkflowInput = zod_1.z.object({
     workflowId: zod_1.z.string().min(1).regex(/^[A-Za-z0-9_-]+$/, 'Workflow ID must contain only letters, numbers, hyphens, and underscores').describe('The workflow ID to inspect'),
     mode: zod_1.z.enum(['metadata', 'preview']).default('preview').describe('Detail level: metadata (name and description only) or preview (full step-by-step breakdown, default)'),
-    workspacePath: optionalWorkspacePathField,
+    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 for discovery-sensitive workflow inspection. Shared MCP servers cannot infer this safely.'),
 });
 exports.V2StartWorkflowInput = zod_1.z.object({
     workflowId: zod_1.z.string().min(1).regex(/^[A-Za-z0-9_-]+$/, 'Workflow ID must contain only letters, numbers, hyphens, and underscores').describe('The workflow ID to start'),

package/dist/v2/infra/local/data-dir/index.d.ts

@@ -5,6 +5,8 @@ export declare class LocalDataDirV2 implements DataDirPortV2 {
     constructor(env: Record<string, string | undefined>);
     private safeFileSegment;
     private root;
+    rememberedRootsPath(): string;
+    rememberedRootsLockPath(): string;
     snapshotsDir(): string;
     snapshotPath(snapshotRef: SnapshotRef): string;
     keysDir(): string;

package/dist/v2/infra/local/data-dir/index.js

@@ -47,6 +47,12 @@ class LocalDataDirV2 {
         const configured = this.env['WORKRAIL_DATA_DIR'];
         return configured ? configured : path.join(os.homedir(), '.workrail', 'data');
     }
+    rememberedRootsPath() {
+        return path.join(this.root(), 'workflow-sources', 'remembered-roots.json');
+    }
+    rememberedRootsLockPath() {
+        return path.join(this.root(), 'workflow-sources', 'remembered-roots.lock');
+    }
     snapshotsDir() {
         return path.join(this.root(), 'snapshots');
     }

package/dist/v2/infra/local/remembered-roots-store/index.d.ts

@@ -0,0 +1,14 @@
+import type { ResultAsync } from 'neverthrow';
+import type { DataDirPortV2 } from '../../../ports/data-dir.port.js';
+import type { FileSystemPortV2 } from '../../../ports/fs.port.js';
+import type { RememberedRootRecordV2, RememberedRootsStoreError, RememberedRootsStorePortV2 } from '../../../ports/remembered-roots-store.port.js';
+export declare class LocalRememberedRootsStoreV2 implements RememberedRootsStorePortV2 {
+    private readonly dataDir;
+    private readonly fs;
+    constructor(dataDir: DataDirPortV2, fs: FileSystemPortV2);
+    listRoots(): ResultAsync<readonly string[], RememberedRootsStoreError>;
+    listRootRecords(): ResultAsync<readonly RememberedRootRecordV2[], RememberedRootsStoreError>;
+    rememberRoot(rootPath: string): ResultAsync<void, RememberedRootsStoreError>;
+    private persist;
+    private withLock;
+}

package/dist/v2/infra/local/remembered-roots-store/index.js

@@ -0,0 +1,172 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LocalRememberedRootsStoreV2 = void 0;
+const path_1 = __importDefault(require("path"));
+const zod_1 = require("zod");
+const neverthrow_1 = require("neverthrow");
+const jcs_js_1 = require("../../../durable-core/canonical/jcs.js");
+const REMEMBERED_ROOTS_LOCK_RETRY_MS = 250;
+const RememberedRootRecordSchema = zod_1.z.object({
+    path: zod_1.z.string(),
+    addedAtMs: zod_1.z.number().int().nonnegative(),
+    lastSeenAtMs: zod_1.z.number().int().nonnegative(),
+    source: zod_1.z.literal('explicit_workspace_path'),
+});
+const RememberedRootsFileSchema = zod_1.z.object({
+    v: zod_1.z.literal(1),
+    roots: zod_1.z.array(RememberedRootRecordSchema),
+});
+function mapFsToRememberedRootsError(e) {
+    if (e.code === 'FS_ALREADY_EXISTS') {
+        return {
+            code: 'REMEMBERED_ROOTS_BUSY',
+            message: 'Remembered roots are being updated by another WorkRail process.',
+            retry: { kind: 'retryable_after_ms', afterMs: REMEMBERED_ROOTS_LOCK_RETRY_MS },
+            lockPath: 'remembered-roots.lock',
+        };
+    }
+    return { code: 'REMEMBERED_ROOTS_IO_ERROR', message: e.message };
+}
+function normalizeRootRecords(roots) {
+    const seen = new Set();
+    const normalized = [];
+    for (const root of roots) {
+        const nextPath = path_1.default.resolve(root.path);
+        if (seen.has(nextPath))
+            continue;
+        seen.add(nextPath);
+        normalized.push({
+            path: nextPath,
+            addedAtMs: root.addedAtMs,
+            lastSeenAtMs: root.lastSeenAtMs,
+            source: root.source,
+        });
+    }
+    return normalized;
+}
+class LocalRememberedRootsStoreV2 {
+    constructor(dataDir, fs) {
+        this.dataDir = dataDir;
+        this.fs = fs;
+    }
+    listRoots() {
+        return this.listRootRecords().map((roots) => roots.map((root) => root.path));
+    }
+    listRootRecords() {
+        const filePath = this.dataDir.rememberedRootsPath();
+        return this.fs.readFileUtf8(filePath)
+            .orElse((e) => {
+            if (e.code === 'FS_NOT_FOUND')
+                return (0, neverthrow_1.okAsync)('');
+            return (0, neverthrow_1.errAsync)(mapFsToRememberedRootsError(e));
+        })
+            .andThen((raw) => {
+            if (raw === '')
+                return (0, neverthrow_1.okAsync)([]);
+            let parsed;
+            try {
+                parsed = JSON.parse(raw);
+            }
+            catch {
+                return (0, neverthrow_1.errAsync)({
+                    code: 'REMEMBERED_ROOTS_CORRUPTION',
+                    message: `Invalid JSON in remembered roots file: ${filePath}`,
+                });
+            }
+            const validated = RememberedRootsFileSchema.safeParse(parsed);
+            if (!validated.success) {
+                return (0, neverthrow_1.errAsync)({
+                    code: 'REMEMBERED_ROOTS_CORRUPTION',
+                    message: `Remembered roots file has invalid shape: ${filePath}`,
+                });
+            }
+            return (0, neverthrow_1.okAsync)(normalizeRootRecords(validated.data.roots));
+        });
+    }
+    rememberRoot(rootPath) {
+        const normalizedRoot = path_1.default.resolve(rootPath);
+        const nowMs = Date.now();
+        return this.withLock(() => this.listRootRecords().andThen((roots) => {
+            const existing = roots.find((root) => root.path === normalizedRoot);
+            const nextRoots = existing
+                ? roots.map((root) => root.path === normalizedRoot
+                    ? { ...root, lastSeenAtMs: nowMs }
+                    : root)
+                : [
+                    ...roots,
+                    {
+                        path: normalizedRoot,
+                        addedAtMs: nowMs,
+                        lastSeenAtMs: nowMs,
+                        source: 'explicit_workspace_path',
+                    },
+                ];
+            return this.persist(nextRoots);
+        }));
+    }
+    persist(roots) {
+        const filePath = this.dataDir.rememberedRootsPath();
+        const dir = path_1.default.dirname(filePath);
+        const tmpPath = `${filePath}.tmp`;
+        const fileValue = {
+            v: 1,
+            roots: [...normalizeRootRecords(roots)],
+        };
+        const canonical = (0, jcs_js_1.toCanonicalBytes)(fileValue).mapErr((e) => ({
+            code: 'REMEMBERED_ROOTS_IO_ERROR',
+            message: `Failed to canonicalize remembered roots state: ${e.message}`,
+        }));
+        if (canonical.isErr())
+            return (0, neverthrow_1.errAsync)(canonical.error);
+        const bytes = canonical.value;
+        return this.fs.mkdirp(dir)
+            .mapErr(mapFsToRememberedRootsError)
+            .andThen(() => this.fs.openWriteTruncate(tmpPath).mapErr(mapFsToRememberedRootsError))
+            .andThen(({ fd }) => this.fs.writeAll(fd, bytes)
+            .mapErr(mapFsToRememberedRootsError)
+            .andThen(() => this.fs.fsyncFile(fd).mapErr(mapFsToRememberedRootsError))
+            .andThen(() => this.fs.closeFile(fd).mapErr(mapFsToRememberedRootsError))
+            .orElse((e) => this.fs.closeFile(fd)
+            .mapErr(() => e)
+            .andThen(() => (0, neverthrow_1.errAsync)(e))))
+            .andThen(() => this.fs.rename(tmpPath, filePath).mapErr(mapFsToRememberedRootsError))
+            .andThen(() => this.fs.fsyncDir(dir).mapErr(mapFsToRememberedRootsError));
+    }
+    withLock(run) {
+        const lockPath = this.dataDir.rememberedRootsLockPath();
+        const dir = path_1.default.dirname(lockPath);
+        const lockBytes = new TextEncoder().encode(JSON.stringify({ v: 1, pid: process.pid }));
+        return this.fs.mkdirp(dir)
+            .mapErr(mapFsToRememberedRootsError)
+            .andThen(() => this.fs.openExclusive(lockPath, lockBytes)
+            .mapErr((e) => {
+            const mapped = mapFsToRememberedRootsError(e);
+            if (mapped.code === 'REMEMBERED_ROOTS_BUSY') {
+                return { ...mapped, lockPath };
+            }
+            return mapped;
+        }))
+            .andThen(({ fd }) => this.fs.fsyncFile(fd)
+            .mapErr(mapFsToRememberedRootsError)
+            .andThen(() => this.fs.closeFile(fd).mapErr(mapFsToRememberedRootsError))
+            .andThen(() => run())
+            .andThen((value) => this.fs.unlink(lockPath)
+            .orElse((e) => {
+            if (e.code === 'FS_NOT_FOUND')
+                return (0, neverthrow_1.okAsync)(undefined);
+            return (0, neverthrow_1.errAsync)(mapFsToRememberedRootsError(e));
+        })
+            .map(() => value))
+            .orElse((error) => this.fs.unlink(lockPath)
+            .orElse((e) => {
+            if (e.code === 'FS_NOT_FOUND')
+                return (0, neverthrow_1.okAsync)(undefined);
+            return (0, neverthrow_1.errAsync)(mapFsToRememberedRootsError(e));
+        })
+            .andThen(() => (0, neverthrow_1.errAsync)(error))));
+    }
+}
+exports.LocalRememberedRootsStoreV2 = LocalRememberedRootsStoreV2;

package/dist/v2/ports/data-dir.port.d.ts

@@ -1,5 +1,7 @@
 import type { SessionId, WorkflowHash, SnapshotRef } from '../durable-core/ids/index.js';
 export interface DataDirPortV2 {
+    rememberedRootsPath(): string;
+    rememberedRootsLockPath(): string;
     pinnedWorkflowsDir(): string;
     pinnedWorkflowPath(workflowHash: WorkflowHash): string;
     snapshotsDir(): string;

package/dist/v2/ports/remembered-roots-store.port.d.ts

@@ -0,0 +1,27 @@
+import type { ResultAsync } from 'neverthrow';
+export type RememberedRootsStoreError = {
+    readonly code: 'REMEMBERED_ROOTS_BUSY';
+    readonly message: string;
+    readonly retry: {
+        readonly kind: 'retryable_after_ms';
+        readonly afterMs: number;
+    };
+    readonly lockPath: string;
+} | {
+    readonly code: 'REMEMBERED_ROOTS_IO_ERROR';
+    readonly message: string;
+} | {
+    readonly code: 'REMEMBERED_ROOTS_CORRUPTION';
+    readonly message: string;
+};
+export interface RememberedRootRecordV2 {
+    readonly path: string;
+    readonly addedAtMs: number;
+    readonly lastSeenAtMs: number;
+    readonly source: 'explicit_workspace_path';
+}
+export interface RememberedRootsStorePortV2 {
+    listRoots(): ResultAsync<readonly string[], RememberedRootsStoreError>;
+    listRootRecords(): ResultAsync<readonly RememberedRootRecordV2[], RememberedRootsStoreError>;
+    rememberRoot(rootPath: string): ResultAsync<void, RememberedRootsStoreError>;
+}

package/dist/v2/ports/remembered-roots-store.port.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

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

package/workflows/workflow-for-workflows.v2.json

@@ -17,7 +17,7 @@
     "META DISTINCTION: you are authoring or modernizing a workflow, not executing one. Keep the authored workflow's concerns separate from this meta-workflow's execution.",
     "DEFAULT BEHAVIOR: self-execute with tools. Only ask the user for business decisions about the workflow being authored or modernized, not things you can learn from the schema, authoring spec, or example workflows.",
     "AUTHORED VOICE: prompts in the authored workflow must be user-voiced. No middleware narration, no pseudo-DSL, no tutorial framing, no teaching-product language.",
-    "VOICE ADAPTATION: the lean coding workflow is one voice example, not the universal template. Adapt vocabulary and tone to the authored workflow's domain.",
+    "VOICE ADAPTATION: the lean coding workflow is one voice example, not the universal template. Copy structural patterns, not domain language. Adapt vocabulary and tone to the authored workflow's domain.",
     "VOICE EXAMPLES: Coding: 'Review the changes in this MR.' Ops: 'Check whether the pipeline is healthy.' Content: 'Read the draft and check the argument.' NOT: 'The system will now perform a comprehensive analysis of...'",
     "VALIDATION GATE: validate with real validators, not regex approximations. When validator output and authoring assumptions conflict, runtime wins.",
     "ARTIFACT STRATEGY: the workflow JSON file is the primary output. Intermediate notes go in output.notesMarkdown. Do not create extra planning artifacts unless the workflow is genuinely complex.",
@@ -87,7 +87,7 @@
     {
       "id": "phase-0-understand",
       "title": "Phase 0: Understand the Workflow to Author or Modernize",
-      "prompt": "Before you write anything, understand what you're working on.\n\nStart by reading:\n- `workflow-schema` reference (legal structure)\n- `authoring-spec` reference (canonical authoring rules)\n- `authoring-guide-v2` reference (current v2 authoring principles)\n- `workflow-authoring-reference` reference (detailed structure patterns)\n- `lean-coding-workflow` reference (modern example to inspect)\n\nRead `routines-guide` too if you think the authored workflow may need delegation or template injection.\n\nThen decide what kind of authoring task this is:\n- `authoringMode`: `create` or `modernize_existing`\n\nIf `authoringMode = create`, understand:\n- What recurring task or problem should this workflow solve?\n- Who runs it and how often?\n- What does success look like?\n- What constraints exist (tools, permissions, domain rules)?\n\nIf `authoringMode = modernize_existing`, understand:\n- Which workflow file is being updated?\n- What should stay the same about its purpose?\n- What feels stale, legacy, repetitive, or misaligned with current authoring guidance?\n- What constraints apply to the modernization (keep file path, preserve compatibility, avoid broad rewrites, etc.)?\n\nExplore first. Use tools to understand the existing workflow, surrounding docs, and relevant domain context. Ask the user only what you genuinely cannot figure out yourself.\n\nThen classify:\n- `workflowComplexity`: Simple (linear, few steps) / Medium (branches, loops, or moderate step count) / Complex (multiple loops, delegation, extension points, many steps)\n- `rigorMode`: QUICK (simple linear workflow, low risk) / STANDARD (moderate complexity or domain risk) / THOROUGH (complex architecture, high stakes, needs review loops)\n\nCapture:\n- `authoringMode`\n- `workflowComplexity`\n- `rigorMode`\n- `taskDescription`\n- `intendedAudience`\n- `successCriteria`\n- `domainConstraints`\n- `targetWorkflowPath` (required for `modernize_existing`, otherwise empty)\n- `modernizationGoals` (required for `modernize_existing`, otherwise empty)\n- `openQuestions` (only real questions that need user input)",
+      "prompt": "Before you write anything, understand what you're working on.\n\nStart by reading:\n- `workflow-schema` reference (legal structure)\n- `authoring-spec` reference (canonical authoring rules)\n- `authoring-guide-v2` reference (current v2 authoring principles)\n- `workflow-authoring-reference` reference (detailed structure patterns)\n- `lean-coding-workflow` reference (modern example to inspect)\n\nRead `routines-guide` too if you think the authored workflow may need delegation or template injection.\n\nThen decide what kind of authoring task this is:\n- `authoringMode`: `create` or `modernize_existing`\n\nIf `authoringMode = create`, understand:\n- What recurring task or problem should this workflow solve?\n- Who runs it and how often?\n- What does success look like?\n- What constraints exist (tools, permissions, domain rules)?\n\nIf `authoringMode = modernize_existing`, understand:\n- Which workflow file is being updated?\n- What should stay the same about its purpose?\n- What feels stale, legacy, repetitive, or misaligned with current authoring guidance?\n- What constraints apply to the modernization (keep file path, preserve compatibility, avoid broad rewrites, etc.)?\n- Which modern example should act as the primary baseline, if any?\n\nFor `modernize_existing`, make an explicit baseline decision before architecture work:\n- choose exactly one `primaryBaseline` when a single modern example fits well\n- optional `secondaryBaselines` may be used for supporting patterns only\n- if no single baseline fits, set `primaryBaseline = none` and explain whether you are using a hybrid baseline or reasoning directly from schema + authoring guidance\n- list `patternsToBorrow` and `patternsToAvoid`\n\nRule:\n- baselines are models, not templates. Copy structural patterns, not another workflow's domain voice.\n\nExplore first. Use tools to understand the existing workflow, surrounding docs, and relevant domain context. Ask the user only what you genuinely cannot figure out yourself.\n\nThen classify:\n- `workflowComplexity`: Simple (linear, few steps) / Medium (branches, loops, or moderate step count) / Complex (multiple loops, delegation, extension points, many steps)\n- `rigorMode`: QUICK (simple linear workflow, low risk) / STANDARD (moderate complexity or domain risk) / THOROUGH (complex architecture, high stakes, needs review loops)\n\nCapture:\n- `authoringMode`\n- `workflowComplexity`\n- `rigorMode`\n- `taskDescription`\n- `intendedAudience`\n- `successCriteria`\n- `domainConstraints`\n- `targetWorkflowPath` (required for `modernize_existing`, otherwise empty)\n- `modernizationGoals` (required for `modernize_existing`, otherwise empty)\n- `primaryBaseline` (for `modernize_existing`, otherwise empty)\n- `secondaryBaselines` (for `modernize_existing`, otherwise empty)\n- `baselineDecisionRationale` (for `modernize_existing`, otherwise empty)\n- `patternsToBorrow` (for `modernize_existing`, otherwise empty)\n- `patternsToAvoid` (for `modernize_existing`, otherwise empty)\n- `openQuestions` (only real questions that need user input)",
       "requireConfirmation": true
     },
     {
@@ -97,7 +97,7 @@
         "var": "workflowComplexity",
         "not_equals": "Simple"
       },
-      "prompt": "Decide the architecture before you write JSON.\n\nBased on what you learned in Phase 0, decide:\n\n1. **Step structure**: how many phases, what each one does, what order\n2. **Loops**: does any phase need iteration? If so, what are the exit rules and max iterations?\n\nLoop design heuristics:\n- Add a loop ONLY when: (a) a quality gate may fail on first pass (validation, review), (b) each pass adds measurable value (progressive refinement), or (c) external feedback requires re-execution.\n- Do NOT loop when: (a) the agent can get it right in one pass with sufficient context, or (b) the full workflow is cheap enough to re-run entirely.\n- Every loop needs: an explicit exit condition (not vibes), a bounded maxIterations, and a decision step with outputContract.\n- Sensible defaults: validation ≈ 2-3, review/refinement ≈ 2, user-feedback ≈ 2-3 with confirmation gate. Go higher only with explicit justification in your notes.\n3. **Confirmation gates**: where does the user genuinely need to approve before proceeding? Don't add confirmations as ceremony.\n4. **Delegation**: does any step benefit from subagent routines? If so, which ones and why? Keep delegation bounded.\n5. **Prompt composition**: will any steps need promptFragments for rigor-mode branching? Will any steps share enough structure to use templates?\n6. **Extension points**: are there customizable slots that projects might want to override (e.g., a verification routine, a review routine)?\n7. **References**: should the authored workflow declare its own references to external docs?\n8. **Artifacts**: what does each step produce? Which artifact is canonical for which concern?\n9. **metaGuidance**: what persistent behavioral rules should the agent see on start and resume?\n\nIf `authoringMode = modernize_existing`, also decide:\n- should this workflow be preserved mostly in place, restructured selectively, or rewritten more substantially?\n- which existing steps, loops, references, or metaGuidance should stay because they still fit the workflow's purpose?\n- which legacy patterns or repetitive sections should be removed or reshaped?\n- whether the file path should stay the same or whether a new variant/file is genuinely warranted\n\nWrite the shape as a structured outline in your notes. Include:\n- Phase list with titles and one-line goals\n- Which phases loop and why\n- Which phases have confirmation gates and why\n- Context variables that flow between phases\n- Artifact ownership (which artifact is canonical for what)\n- for `modernize_existing`: whether the plan is preserve-in-place, restructure, or rewrite-biased and why\n\nDon't write JSON yet.\n\nCapture:\n- `workflowOutline`\n- `loopDesign`\n- `confirmationDesign`\n- `delegationDesign`\n- `artifactPlan`\n- `contextModel` (the context variables the workflow will use and where they're set)\n- `voiceStrategy` (domain vocabulary, authority posture: directive/collaborative/supervisory, density calibration)\n- `modernizationStrategy` (for `modernize_existing`: preserve_in_place / restructure / rewrite, otherwise empty)",
+      "prompt": "Decide the architecture before you write JSON.\n\nBased on what you learned in Phase 0, decide:\n\n1. **Step structure**: how many phases, what each one does, what order\n2. **Loops**: does any phase need iteration? If so, what are the exit rules and max iterations?\n\nLoop design heuristics:\n- Add a loop ONLY when: (a) a quality gate may fail on first pass (validation, review), (b) each pass adds measurable value (progressive refinement), or (c) external feedback requires re-execution.\n- Do NOT loop when: (a) the agent can get it right in one pass with sufficient context, or (b) the full workflow is cheap enough to re-run entirely.\n- Every loop needs: an explicit exit condition (not vibes), a bounded maxIterations, and a decision step with outputContract.\n- Sensible defaults: validation ≈ 2-3, review/refinement ≈ 2, user-feedback ≈ 2-3 with confirmation gate. Go higher only with explicit justification in your notes.\n3. **Confirmation gates**: where does the user genuinely need to approve before proceeding? Don't add confirmations as ceremony.\n4. **Delegation and reuse**: for each phase, decide between direct execution, routine delegation, template injection, or no special mechanism. If a routine or template is not used, say why not. Keep delegation bounded and keep ownership with the main agent.\n5. **Prompt composition**: will any steps need promptFragments for rigor-mode branching? Will any steps share enough structure to use templates?\n6. **Extension points**: are there customizable slots that projects might want to override (e.g., a verification routine, a review routine)?\n7. **References**: should the authored workflow declare its own references to external docs?\n8. **Artifacts**: what does each step produce? Which artifact is canonical for which concern?\n9. **metaGuidance**: what persistent behavioral rules should the agent see on start and resume?\n\nIf `authoringMode = modernize_existing`, also decide:\n- should this workflow be preserved mostly in place, restructured selectively, or rewritten more substantially?\n- which existing steps, loops, references, or metaGuidance should stay because they still fit the workflow's purpose?\n- which legacy patterns or repetitive sections should be removed or reshaped?\n- whether the file path should stay the same or whether a new variant/file is genuinely warranted\n- how each major old phase or behavior maps to the new workflow: `keep`, `merge`, `remove`, or `replace`\n\nFor `modernize_existing`, create a compact legacy mapping in your notes. For each major old phase or behavior, record:\n- source step or behavior\n- disposition: `keep` / `merge` / `remove` / `replace`\n- rationale\n- destination in the new workflow, if any\n\nFor routine and template decisions, create a compact audit in your notes. For each meaningful phase or concern, record:\n- chosen mechanism: direct / routine / template / none\n- why it helps or why it would be overkill\n- the ownership boundary that stays with the main agent\n\nWrite the shape as a structured outline in your notes. Include:\n- Phase list with titles and one-line goals\n- Which phases loop and why\n- Which phases have confirmation gates and why\n- Context variables that flow between phases\n- Artifact ownership (which artifact is canonical for what)\n- for `modernize_existing`: whether the plan is preserve-in-place, restructure, or rewrite-biased and why\n\nDon't write JSON yet.\n\nCapture:\n- `workflowOutline`\n- `loopDesign`\n- `confirmationDesign`\n- `delegationDesign`\n- `artifactPlan`\n- `contextModel` (the context variables the workflow will use and where they're set)\n- `voiceStrategy` (domain vocabulary, authority posture: directive/collaborative/supervisory, density calibration)\n- `routineAudit`\n- `delegationBoundaries`\n- `templateInjectionPlan`\n- `modernizationStrategy` (for `modernize_existing`: preserve_in_place / restructure / rewrite, otherwise empty)\n- `legacyMapping` (for `modernize_existing`, otherwise empty)\n- `behaviorPreservationNotes` (for `modernize_existing`, otherwise empty)",
       "requireConfirmation": {
         "or": [
           { "var": "workflowComplexity", "not_equals": "Simple" },
@@ -169,7 +169,7 @@
     {
       "id": "phase-4-review",
       "title": "Phase 4: Method Review",
-      "prompt": "The workflow is valid. Now check whether it's actually good.\n\nScore each dimension 0-2 with one sentence of evidence:\n\n- `voiceClarity`: 0 = prompts are direct user-voiced asks in the workflow's domain vocabulary, 1 = mostly user-voiced but borrows vocabulary from other domains or has middleware narration, 2 = reads like system documentation or sounds like a different domain\n- `ceremonyLevel`: 0 = confirmations only at real decision points, 1 = one or two unnecessary gates, 2 = over-asks the user or adds routine ceremony\n- `loopSoundness`: 0 = loops have explicit exit rules, bounded iterations, and real decision steps, 1 = minor issues with exit clarity, 2 = vibes-only exit conditions or unbounded loops (score 0 if no loops)\n- `delegationBoundedness`: 0 = delegation is bounded and explicit or absent, 1 = one delegation could be tighter, 2 = open-ended or ownership-transferring delegation (score 0 if no delegation)\n- `legacyPatterns`: 0 = no legacy anti-patterns, 1 = minor legacy residue, 2 = pseudo-DSL, learning paths, satisfaction loops, or regex-as-gate present\n- `artifactClarity`: 0 = clear what each artifact is for and which is canonical, 1 = mostly clear, 2 = ambiguous artifact ownership\n- `modeFit`: 0 = the workflow fits the selected `authoringMode`, 1 = minor creation/modernization mismatch remains, 2 = the workflow still reads like the wrong mode entirely\n\nIf the total score is 0-3: the workflow is ready.\nIf the total score is 4-6: fix the worst dimensions before proceeding.\nIf the total score is 7+: this needs significant rework. Fix the worst dimensions here, re-validate, and record what you would change if you could redraft from scratch.\n\nIf `authoringMode = modernize_existing`, check explicitly:\n- does the updated workflow preserve the right purpose?\n- did you remove legacy structure without rewriting valuable behavior away?\n- do any prompts, captures, or handoff notes still assume this was a brand-new workflow?\n\nFix any issues directly in the workflow file. Re-run validation if you changed structure.\n\nCapture:\n- `reviewScores`\n- `reviewPassed`\n- `fixesApplied`",
+      "prompt": "The workflow is valid. Now check whether it's actually good.\n\nScore each dimension 0-2 with one sentence of evidence:\n\n- `voiceClarity`: 0 = prompts are direct user-voiced asks in the workflow's domain vocabulary, 1 = mostly user-voiced but borrows vocabulary from other domains or has middleware narration, 2 = reads like system documentation or sounds like a different domain\n- `ceremonyLevel`: 0 = confirmations only at real decision points, 1 = one or two unnecessary gates, 2 = over-asks the user or adds routine ceremony\n- `loopSoundness`: 0 = loops have explicit exit rules, bounded iterations, and real decision steps, 1 = minor issues with exit clarity, 2 = vibes-only exit conditions or unbounded loops (score 0 if no loops)\n- `delegationBoundedness`: 0 = delegation is bounded and explicit or absent, 1 = one delegation could be tighter or a good routine/template opportunity was missed, 2 = open-ended or ownership-transferring delegation, or routine/template choices are unjustified (score 0 if no delegation and no reuse need exists)\n- `legacyPatterns`: 0 = no legacy anti-patterns, 1 = minor legacy residue, 2 = pseudo-DSL, learning paths, satisfaction loops, or regex-as-gate present\n- `artifactClarity`: 0 = clear what each artifact is for and which is canonical, 1 = mostly clear, 2 = ambiguous artifact ownership\n- `modeFit`: 0 = the workflow fits the selected `authoringMode`, 1 = minor creation/modernization mismatch remains, 2 = the workflow still reads like the wrong mode entirely\n- `modernizationDiscipline`: 0 = valuable behavior was preserved and legacy structure was removed cleanly, 1 = minor mismatch or over/under-preservation, 2 = either valuable behavior was lost or legacy structure still dominates (score 0 for `create` mode)\n\nIf the total score is 0-3: the workflow is ready.\nIf the total score is 4-6: fix the worst dimensions before proceeding.\nIf the total score is 7+: this needs significant rework. Fix the worst dimensions here, re-validate, and record what you would change if you could redraft from scratch.\n\nIf `authoringMode = modernize_existing`, check explicitly:\n- does the updated workflow preserve the right purpose?\n- did you remove legacy structure without rewriting valuable behavior away?\n- does the final workflow still align with `primaryBaseline` and `patternsToBorrow` without copying domain language?\n- does the final workflow respect the `legacyMapping`, especially for anything marked keep or merge?\n- do the routine/template choices still match the `routineAudit` and stay bounded?\n- do any prompts, captures, or handoff notes still assume this was a brand-new workflow?\n\nFix any issues directly in the workflow file. Re-run validation if you changed structure.\n\nCapture:\n- `reviewScores`\n- `reviewPassed`\n- `fixesApplied`",
       "promptFragments": [
         {
           "id": "phase-4-quick-skip",