@ctrl-spc/cli 1.2.3 → 1.3.0

package/dist/commands/run.js

@@ -12,6 +12,7 @@ import { MCP_PORT } from '../env.js';
 import { startMcpServer } from '../mcp.js';
 import { getMachineIdentity } from '../config.js';
 import { discoverRepositoryTopology } from '../topology.js';
+import { createAgentDispatchController } from '../dispatch.js';
 function mcpUrl() {
     return `http://localhost:${MCP_PORT}/mcp`;
 }
@@ -611,12 +612,13 @@ export function createProjectPresenceReconciler(client, userId, profileName, mac
  * tool call can flip presence back to "working" mid-shutdown) and only then
  * untracks presence, before exiting.
  */
-function installShutdownHandler(presence, mcpServer) {
+function installShutdownHandler(presence, mcpServer, dispatch) {
     let shuttingDown = false;
     const shutdown = () => {
         if (shuttingDown)
             return;
         shuttingDown = true;
+        dispatch?.stop();
         console.log('\nShutting down — closing MCP server, untracking presence...');
         mcpServer
             .close()
@@ -712,8 +714,10 @@ export async function run() {
     }
     console.log(`MCP: ${url} (tools: list_tasks, get_task, begin_work, heartbeat_work, reserve_work_paths, ` +
         'release_work_paths, transfer_coordination, acknowledge_unavailable_checkout, record_context_exploration, ' +
-        'ask_question, end_work, create_task, update_task, create_artifact, add_comment)');
+        'ask_question, record_user_input, submit_workflow_stage, decide_workflow_review, ' +
+        'end_work, create_task, update_task, create_artifact, add_comment)');
     console.log(`Projects: ${projects.length > 0 ? projects.map((project) => project.name).join(', ') : 'none initialized on this machine'}`);
     console.log('Presence: available');
-    installShutdownHandler(presence, mcpServer);
+    const dispatch = createAgentDispatchController(client, machine.id, registeredAgents);
+    installShutdownHandler(presence, mcpServer, dispatch);
 }

package/dist/dispatch.js

@@ -0,0 +1,104 @@
+import { spawn } from 'node:child_process';
+import { resolveAgentCommand } from './agents.js';
+function shellQuote(value) {
+    return `'${value.replaceAll("'", "'\\''")}'`;
+}
+function appleScriptString(value) {
+    return `"${value.replaceAll('\\', '\\\\').replaceAll('"', '\\"')}"`;
+}
+export function agentTerminalCommand(request, executable) {
+    const prompt = shellQuote(request.prompt);
+    const binary = shellQuote(executable);
+    const fresh = `${binary} ${prompt}`;
+    const resume = request.agent_kind === 'claude'
+        ? `${binary} --continue ${prompt}`
+        : `${binary} resume --last ${prompt}`;
+    const agentCommand = request.mode === 'resume' ? `( ${resume} || ${fresh} )` : fresh;
+    return `cd ${shellQuote(request.workspace_root)} && ${agentCommand}`;
+}
+/** Opens a visible agent conversation. Resume is best-effort and falls back
+ * to a fresh task conversation in the same project checkout. */
+export async function launchAgentDispatch(request) {
+    if (process.platform !== 'darwin') {
+        throw new Error('Automatic agent launch currently requires macOS Terminal.');
+    }
+    const executable = resolveAgentCommand(request.agent_kind);
+    if (!executable)
+        throw new Error(`${request.agent_kind} is not installed on this machine.`);
+    const command = agentTerminalCommand(request, executable);
+    const script = `tell application "Terminal" to activate\ntell application "Terminal" to do script ${appleScriptString(command)}`;
+    await new Promise((resolve, reject) => {
+        const child = spawn('/usr/bin/osascript', ['-e', script], {
+            stdio: ['ignore', 'ignore', 'pipe'],
+        });
+        let stderr = '';
+        child.stderr.on('data', (chunk) => { stderr += String(chunk); });
+        child.once('error', reject);
+        child.once('exit', (code) => {
+            if (code === 0)
+                resolve();
+            else
+                reject(new Error(stderr.trim() || `Terminal launch exited with code ${code ?? 'unknown'}.`));
+        });
+    });
+}
+export function createAgentDispatchController(client, machineId, agents, deps = {}) {
+    const claim = deps.claim ?? (async () => {
+        const { data, error } = await client.rpc('claim_agent_dispatch_request', {
+            p_machine: machineId,
+            p_agents: agents,
+        });
+        if (error)
+            throw error;
+        return data;
+    });
+    const complete = deps.complete ?? (async (id, state, errorMessage) => {
+        const { error } = await client.rpc('complete_agent_dispatch_request', {
+            p_request: id,
+            p_state: state,
+            p_error: errorMessage ?? null,
+        });
+        if (error)
+            throw error;
+    });
+    const launch = deps.launch ?? launchAgentDispatch;
+    let stopped = false;
+    let polling = false;
+    let timer;
+    const poll = async () => {
+        if (stopped || polling)
+            return;
+        polling = true;
+        try {
+            const request = await claim();
+            if (!request)
+                return;
+            try {
+                await launch(request);
+                await complete(request.id, 'launched');
+            }
+            catch (err) {
+                await complete(request.id, 'failed', err instanceof Error ? err.message : String(err));
+            }
+        }
+        finally {
+            polling = false;
+        }
+    };
+    timer = setInterval(() => {
+        void poll().catch((err) => console.warn(`Warning: agent dispatch poll failed: ${err.message}`));
+    }, deps.intervalMs ?? 2500);
+    timer.unref();
+    if (deps.startImmediately !== false) {
+        void poll().catch((err) => console.warn(`Warning: agent dispatch poll failed: ${err.message}`));
+    }
+    return {
+        poll,
+        stop() {
+            stopped = true;
+            if (timer)
+                clearInterval(timer);
+            timer = undefined;
+        },
+    };
+}

package/dist/mcp.js

@@ -82,6 +82,25 @@ function requiredProjectId(deps, action) {
         throw new Error(`${action} requires a project-bound agent run`);
     return deps.projectId;
 }
+function normalizeWorkflowContext(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return { enabled: false };
+    const context = value;
+    return context.enabled === true ? context : { enabled: false };
+}
+async function loadWorkflowContext(client, taskId) {
+    const value = await must(client.rpc('get_task_workflow_context', { p_task: taskId }));
+    return normalizeWorkflowContext(value);
+}
+function workflowCapabilityError(run, capability, action) {
+    const workflow = run.workflow;
+    if (!workflow?.enabled)
+        return null;
+    if (workflow.current_stage?.capabilities?.includes(capability))
+        return null;
+    return errorResult(`${action} is not allowed during workflow stage "${workflow.current_stage?.name ?? 'unknown'}". ` +
+        'Follow the stored stage instructions returned by get_task.');
+}
 /**
  * One future-proof task read model. `*` keeps every direct task column without
  * requiring a CLI release when an additive migration lands. Every relationship
@@ -363,8 +382,8 @@ export async function beginAgentRunHandler(deps, session, args) {
                 'Call end_work before beginning a different task in the same agent session.');
         }
         const task = deps.projectId
-            ? await must(deps.client.from('tasks').select('id,project_id').eq('id', args.task_id).eq('project_id', deps.projectId).maybeSingle())
-            : await must(deps.client.from('tasks').select('id,project_id').eq('id', args.task_id).maybeSingle());
+            ? await must(deps.client.from('tasks').select('id,project_id,description').eq('id', args.task_id).eq('project_id', deps.projectId).maybeSingle())
+            : await must(deps.client.from('tasks').select('id,project_id,description').eq('id', args.task_id).maybeSingle());
         if (!task)
             return errorResult(`No accessible task found for id "${args.task_id}".`);
         const taskProjectId = task.project_id ?? deps.projectId;
@@ -434,7 +453,29 @@ export async function beginAgentRunHandler(deps, session, args) {
             previousExploration.topologyRevision === Number(result.topology_revision)
             ? previousExploration
             : null;
+        try {
+            session.run.workflow = normalizeWorkflowContext(await must(deps.client.rpc('begin_workflow_stage', { p_run: result.run_id })));
+            if (!session.run.workflow.enabled) {
+                // A real task row always has a string description. Treat an omitted
+                // field as already provided only for backwards-compatible embedded
+                // clients/test doubles that predate this contract.
+                const persistedInstruction = typeof task.description === 'string' ? task.description.trim() : null;
+                session.run.noWorkflowIntent = persistedInstruction === '' && !args.prompt_instruction?.trim()
+                    ? 'missing'
+                    : 'provided';
+            }
+        }
+        catch (workflowError) {
+            await deps.client.rpc('end_agent_run', {
+                p_run: result.run_id,
+                p_reason: 'workflow stage unavailable',
+            });
+            session.run = null;
+            session.exploration = null;
+            throw workflowError;
+        }
         const collaborator = result.role === 'collaborator';
+        const workflow = session.run.workflow;
         return textResult({
             coordination: {
                 status: collaborator ? 'joined_as_collaborator' : 'coordinating',
@@ -446,6 +487,16 @@ export async function beginAgentRunHandler(deps, session, args) {
                     : 'You are coordinating this task. Inspect every repository, then call reserve_work_paths before editing. Collaborators may join with disjoint reservations.',
             },
             agent_run: session.run,
+            workflow,
+            ...(workflow?.enabled ? {
+                workflow_instruction: workflow.current_stage?.state === 'awaiting_review'
+                    ? `Current stage: ${workflow.current_stage?.name ?? 'unknown'} is awaiting review. ` +
+                        'Only record the user\'s explicit approval or change request with decide_workflow_review; do not redo or advance the stage first.'
+                    : `Current stage: ${workflow.current_stage?.name ?? 'unknown'}. ` +
+                        `${workflow.current_stage?.instructions ?? 'Follow the stored workflow instructions.'}`,
+            } : session.run.noWorkflowIntent === 'missing' ? {
+                no_workflow_instruction: 'This No workflow item has no instructions. After context exploration, ask the user what should be done with ask_question(category: intent). Do not plan, create another artifact, reserve paths, or edit first.',
+            } : {}),
         });
     }
     catch (err) {
@@ -485,6 +536,11 @@ export async function reserveWorkPathsHandler(deps, session, args) {
     if (!Array.isArray(args.reservations) || args.reservations.length === 0) {
         return errorResult('reserve_work_paths requires at least one repository/path reservation.');
     }
+    if (args.reservations.some((reservation) => (reservation.mode ?? 'write') === 'write')) {
+        const workflowError = workflowCapabilityError(active, 'reserve_write', 'reserve_work_paths');
+        if (workflowError)
+            return workflowError;
+    }
     const missingCheckout = args.reservations.find((reservation) => (reservation.mode ?? 'write') === 'write' && !reservation.repository_checkout_id);
     if (missingCheckout) {
         return errorResult('Every write reservation requires repository_checkout_id from get_task topology.checkouts. ' +
@@ -777,11 +833,180 @@ export async function askQuestionHandler(deps, attribution, args, agentRun) {
     if (!first || first.type !== 'text')
         return errorResult('ask_question returned no persisted comment.');
     const payload = JSON.parse(first.text);
+    const commentId = typeof payload.comment?.id === 'string' ? payload.comment.id : null;
+    let workflowQuestionId = null;
+    if (agentRun.workflow?.enabled) {
+        if (!commentId)
+            return errorResult('ask_question returned no persisted comment id for the workflow question.');
+        workflowQuestionId = await must(deps.client.rpc('open_workflow_question', {
+            p_run: agentRun.runId,
+            p_comment: commentId,
+            p_category: args.category,
+            p_question: question,
+        }));
+        agentRun.workflow = await loadWorkflowContext(deps.client, agentRun.taskId);
+    }
     return textResult({
-        question: { category: args.category, text: question, comment_id: payload.comment?.id ?? null },
+        question: {
+            category: args.category,
+            text: question,
+            comment_id: commentId,
+            workflow_question_id: workflowQuestionId,
+        },
         comment: payload.comment ?? null,
+        ...(agentRun.workflow?.enabled ? { workflow: agentRun.workflow } : {}),
     });
 }
+export async function recordUserInputHandler(deps, attribution, session, args) {
+    const active = joinedRunOrError(session, 'record_user_input');
+    if ('content' in active)
+        return active;
+    if (!active.workflow?.enabled)
+        return errorResult('record_user_input requires a workflow task.');
+    const capabilityError = workflowCapabilityError(active, 'record_user_input', 'record_user_input');
+    if (capabilityError)
+        return capabilityError;
+    if (!Array.isArray(args.question_ids) || args.question_ids.length === 0) {
+        return errorResult('record_user_input requires at least one workflow question id.');
+    }
+    if (!args.answer?.trim())
+        return errorResult('record_user_input requires the user\'s exact answer.');
+    try {
+        const openQuestions = active.workflow.open_questions ?? [];
+        const questionText = args.question_ids.map((id) => {
+            const question = openQuestions.find((candidate) => candidate.id === id);
+            return `- ${typeof question?.question === 'string' ? question.question : id}`;
+        }).join('\n');
+        const artifactResult = await createArtifactHandler(bindProject(deps, active.projectId), attribution, {
+            task_id: active.taskId,
+            type: 'analysis',
+            format: 'md',
+            content: `# User input\n\n## Questions\n\n${questionText}\n\n## User answer\n\n${args.answer.trim()}`,
+            coverage: args.coverage,
+        }, active);
+        if (artifactResult.isError)
+            return artifactResult;
+        const first = artifactResult.content[0];
+        if (!first || first.type !== 'text')
+            throw new Error('answer artifact returned no text result');
+        const payload = JSON.parse(first.text);
+        const artifactId = typeof payload.artifact?.id === 'string' ? payload.artifact.id : null;
+        if (!artifactId)
+            throw new Error('answer artifact returned no id');
+        active.workflow = normalizeWorkflowContext(await must(deps.client.rpc('record_workflow_answer', {
+            p_run: active.runId,
+            p_question_ids: args.question_ids,
+            p_artifact: artifactId,
+        })));
+        return textResult({
+            recorded: true,
+            artifact_id: artifactId,
+            question_ids: args.question_ids,
+            workflow: active.workflow,
+        });
+    }
+    catch (err) {
+        return coordinationError('record_user_input', err);
+    }
+}
+export async function submitWorkflowStageHandler(deps, session, args) {
+    const active = joinedRunOrError(session, 'submit_workflow_stage');
+    if ('content' in active)
+        return active;
+    if (!active.workflow?.enabled)
+        return errorResult('submit_workflow_stage requires a workflow task.');
+    const capabilityError = workflowCapabilityError(active, 'submit_stage', 'submit_workflow_stage');
+    if (capabilityError)
+        return capabilityError;
+    if (!Number.isInteger(args.expected_workflow_revision) || args.expected_workflow_revision < 1) {
+        return errorResult('submit_workflow_stage requires the current positive workflow revision from get_task.');
+    }
+    if (!Array.isArray(args.artifacts))
+        return errorResult('submit_workflow_stage requires an artifacts array.');
+    try {
+        active.workflow = normalizeWorkflowContext(await must(deps.client.rpc('submit_workflow_stage', {
+            p_run: active.runId,
+            p_expected_workflow_revision: args.expected_workflow_revision,
+            p_artifacts: args.artifacts,
+        })));
+        const waiting = active.workflow.state === 'awaiting_user';
+        return textResult({
+            submitted: true,
+            workflow: active.workflow,
+            instruction: waiting
+                ? 'This stage is awaiting explicit user review. Do not begin the next stage. End this agent run after persisting its receipt.'
+                : `Continue with workflow stage "${active.workflow.current_stage?.name ?? 'next'}" and follow its stored instructions.`,
+        });
+    }
+    catch (err) {
+        return coordinationError('submit_workflow_stage', err);
+    }
+}
+export async function decideWorkflowReviewHandler(deps, session, args) {
+    const active = joinedRunOrError(session, 'decide_workflow_review');
+    if ('content' in active)
+        return active;
+    if (active.taskId !== args.task_id) {
+        return errorResult(`decide_workflow_review must stay on this agent run's task (${active.taskId}).`);
+    }
+    if (!active.workflow?.enabled || active.workflow.current_stage?.stage_run_id !== args.stage_run_id ||
+        active.workflow.current_stage?.state !== 'awaiting_review') {
+        return errorResult('decide_workflow_review requires this live agent run to be bound to the current review stage.');
+    }
+    if (!args.user_message?.trim()) {
+        return errorResult('decide_workflow_review requires the user\'s exact approval or change-request message as evidence.');
+    }
+    try {
+        const scopes = await activeRepositoryScopes(deps.client, active.projectId);
+        const evidenceResult = await createArtifactHandler(bindProject(deps, active.projectId), attributionFromClientName(session.clientName), {
+            task_id: active.taskId,
+            type: 'analysis',
+            format: 'md',
+            content: `# Workflow review decision\n\n${args.user_message.trim()}`,
+            coverage: scopes.map(scope => ({
+                repository_scope_id: scope.repository_scope_id,
+                disposition: 'context_only',
+                reason: 'Conversation review evidence applies to this workflow task.',
+            })),
+        }, active);
+        if (evidenceResult.isError)
+            return evidenceResult;
+        const evidenceBlock = evidenceResult.content[0];
+        if (!evidenceBlock || evidenceBlock.type !== 'text')
+            throw new Error('review evidence artifact returned no text result');
+        const evidencePayload = JSON.parse(evidenceBlock.text);
+        const evidenceArtifactId = typeof evidencePayload.artifact?.id === 'string' ? evidencePayload.artifact.id : null;
+        if (!evidenceArtifactId)
+            throw new Error('review evidence artifact returned no id');
+        const context = normalizeWorkflowContext(await must(deps.client.rpc('decide_workflow_review', {
+            p_task: args.task_id,
+            p_stage_run: args.stage_run_id,
+            p_expected_workflow_revision: args.expected_workflow_revision,
+            p_decision: args.decision,
+            p_source: 'agent_conversation',
+            p_evidence: args.user_message.trim(),
+            p_agent_run: active.runId,
+            p_evidence_artifact: evidenceArtifactId,
+            p_dispatch_agent: false,
+        })));
+        if (session.run?.state === 'joined' && session.run.taskId === args.task_id) {
+            session.run.workflow = context;
+        }
+        session.reviewEvidenceArtifactId = evidenceArtifactId;
+        return textResult({
+            recorded: true,
+            decision: args.decision,
+            evidence_artifact_id: evidenceArtifactId,
+            workflow: context,
+            instruction: context.state === 'completed'
+                ? 'The user approved completion. The workflow and work item are Done.'
+                : `The workflow remains on stage "${context.current_stage?.name ?? 'unknown'}". Call begin_work before continuing agent work.`,
+        });
+    }
+    catch (err) {
+        return coordinationError('decide_workflow_review', err);
+    }
+}
 export async function endAgentRunHandler(deps, session, args = {}, options = {}) {
     const active = runOrError(session, 'end_work');
     if ('content' in active)
@@ -789,18 +1014,19 @@ export async function endAgentRunHandler(deps, session, args = {}, options = {})
     try {
         if (options.requirePersistenceReceipt) {
             const exploration = session.exploration;
+            const reviewEvidenceArtifactId = session.reviewEvidenceArtifactId ?? null;
             const receipt = args.persistence_receipt;
-            if (!exploration || !receipt) {
-                return errorResult('end_work requires a persistence_receipt and this session\'s persisted context exploration artifact.');
+            if ((!exploration && !reviewEvidenceArtifactId) || !receipt) {
+                return errorResult('end_work requires a persistence_receipt and this session\'s persisted context or review evidence artifact.');
             }
             const outcome = receipt.outcome ?? 'completed';
-            if (exploration.status === 'blocked' && !['blocked', 'aborted'].includes(outcome)) {
+            if (exploration?.status === 'blocked' && !['blocked', 'aborted'].includes(outcome)) {
                 return errorResult('A subagents_unavailable session may end only with outcome blocked or aborted.');
             }
-            if (exploration.status === 'explored' && !['completed', 'blocked'].includes(outcome)) {
+            if (exploration?.status === 'explored' && !['completed', 'blocked'].includes(outcome)) {
                 return errorResult('An explored session may end as completed, or blocked after persisting a question for the user.');
             }
-            if (exploration.status === 'explored' && outcome === 'blocked') {
+            if (exploration?.status === 'explored' && outcome === 'blocked') {
                 const questionRows = (await must(deps.client
                     .from('comments')
                     .select('id,task_id,agent_run_id,body,created_at')
@@ -822,8 +1048,9 @@ export async function endAgentRunHandler(deps, session, args = {}, options = {})
             if (artifactIds.length !== receipt.artifact_ids.length) {
                 return errorResult('end_work persistence_receipt artifact_ids must be unique.');
             }
-            if (!artifactIds.includes(exploration.artifactId)) {
-                return errorResult('end_work persistence_receipt must include the context exploration artifact id.');
+            const requiredEvidenceArtifactId = exploration?.artifactId ?? reviewEvidenceArtifactId;
+            if (!artifactIds.includes(requiredEvidenceArtifactId)) {
+                return errorResult('end_work persistence_receipt must include this session\'s required evidence artifact id.');
             }
             const task = await must(deps.client
                 .from('tasks')
@@ -851,10 +1078,10 @@ export async function endAgentRunHandler(deps, session, args = {}, options = {})
                     `this task run. Missing: ${missingArtifactIds.join(', ') || 'none'}. ` +
                     `Foreign or deleted: ${foreignArtifactIds.join(', ') || 'none'}.`);
             }
-            const explorationArtifact = artifactsById.get(exploration.artifactId);
-            if (!explorationArtifact || explorationArtifact.task_id !== exploration.taskId ||
-                explorationArtifact.agent_run_id !== exploration.agentRunId) {
-                return errorResult('end_work could not verify this session\'s persisted context exploration artifact.');
+            const evidenceArtifact = artifactsById.get(requiredEvidenceArtifactId);
+            if (!evidenceArtifact || evidenceArtifact.task_id !== active.taskId ||
+                evidenceArtifact.agent_run_id !== active.runId) {
+                return errorResult('end_work could not verify this session\'s required evidence artifact.');
             }
         }
         const ended = await must(deps.client.rpc('end_agent_run', {
@@ -863,6 +1090,7 @@ export async function endAgentRunHandler(deps, session, args = {}, options = {})
         }));
         session.run = null;
         session.exploration = null;
+        session.reviewEvidenceArtifactId = null;
         return textResult({
             ended: Boolean(ended),
             agent_run_id: active.runId,
@@ -940,7 +1168,7 @@ export async function getTaskHandler(deps, _attribution, args, machineId) {
         }
         const task = parseTaskRow(row);
         const topologyMachineId = machineId ?? deps.machineId;
-        const [rawComments, rawArtifacts, rawVersions, rawAgentRuns, rawTaskClaims, collaborationDocument, topology] = await Promise.all([
+        const [rawComments, rawArtifacts, rawVersions, rawAgentRuns, rawTaskClaims, collaborationDocument, topology, workflow] = await Promise.all([
             must(client
                 .from('comments')
                 .select(COMMENT_SELECT)
@@ -986,6 +1214,7 @@ export async function getTaskHandler(deps, _attribution, args, machineId) {
             topologyMachineId
                 ? loadAgentProjectTopology(client, row.project_id, deps.userId, topologyMachineId)
                 : Promise.resolve(undefined),
+            loadWorkflowContext(client, row.id),
         ]);
         const comments = sortRecords((rawComments ?? []).map(normalizeComment), 'created_at', 'id');
         const normalizedArtifacts = sortRecords((rawArtifacts ?? []).map(normalizeArtifact), 'created_at', 'id');
@@ -1043,6 +1272,7 @@ export async function getTaskHandler(deps, _attribution, args, machineId) {
             active_work_reservations: activeWorkReservations,
             collaborative_description: collaborativeDescription,
             ...(topology ? { topology } : {}),
+            workflow,
             highlighted_artifact_id: highlightArtifactId,
             protocol: PROTOCOL_SHORT,
         });
@@ -1058,20 +1288,16 @@ export async function createTaskHandler(deps, _attribution, args) {
         const { client, userId } = deps;
         const projectId = requiredProjectId(deps, 'create_task');
         const tags = await resolveOrCreateTags(client, projectId, args.tags ?? []);
-        const inserted = await must(client
-            .from('tasks')
-            .insert({
-            project_id: projectId,
-            name: args.name,
-            description: args.description ?? '',
-            owner_id: userId,
-            status: 'backlog',
-        })
-            .select('id')
-            .single());
-        if (!inserted)
-            throw new Error('Task insert returned no row.');
-        const taskId = inserted.id;
+        const taskId = await must(client.rpc('create_task_with_workflow', {
+            p_project: projectId,
+            p_name: args.name,
+            p_description: args.description ?? '',
+            p_owner: userId,
+            p_use_workflow: true,
+            p_workflow_version: null,
+        }));
+        if (!taskId)
+            throw new Error('Task insert returned no id.');
         if (tags.length > 0) {
             await must(client.from('task_tags').insert(tags.map((t) => ({ task_id: taskId, tag_id: t.id }))));
         }
@@ -1098,6 +1324,14 @@ export async function updateTaskHandler(deps, _attribution, args, agentRun) {
         if (agentRun && (id !== agentRun.taskId || projectId !== agentRun.projectId)) {
             return errorResult(`update_task must stay on this agent run's task ${agentRun.taskId} in project ${agentRun.projectId}.`);
         }
+        if (agentRun?.workflow?.enabled) {
+            const capabilityError = workflowCapabilityError(agentRun, 'update_task', 'update_task');
+            if (capabilityError)
+                return capabilityError;
+            if (fields.status !== undefined) {
+                return errorResult('Workflow task status is controlled by workflow transitions and final user approval.');
+            }
+        }
         if (!Number.isInteger(expected_revision) || expected_revision < 1) {
             return errorResult('update_task requires expected_revision from the most recent get_task response.');
         }
@@ -1399,6 +1633,15 @@ export async function startMcpServer(deps) {
         }
         return null;
     }
+    function requireNoWorkflowIntent(session, tool) {
+        const run = session.context.run;
+        if (!run || run.state !== 'joined' || run.workflow?.enabled || run.noWorkflowIntent === 'provided')
+            return null;
+        return errorResult(`${tool} is blocked because this No workflow item has no instructions. ` +
+            (run.noWorkflowIntent === 'missing'
+                ? 'Call ask_question with category intent to ask the user what should be done.'
+                : 'Persist the user\'s answer in the task description with update_task before continuing.'));
+    }
     function buildServer(session) {
         const server = new McpServer({ name: 'ctrl-spc', version: BROKER_VERSION });
         function attribution() {
@@ -1426,7 +1669,10 @@ export async function startMcpServer(deps) {
         });
         server.registerTool('begin_work', {
             description: 'Explicitly begin work on a task. The first live agent coordinates; later agents join as collaborators. No agent may edit repository paths until reserve_work_paths succeeds.',
-            inputSchema: { task_id: z.string() },
+            inputSchema: {
+                task_id: z.string(),
+                prompt_instruction: z.string().optional().describe('Exact work instruction supplied alongside the copied command. Omit when the paste contains only the command.'),
+            },
         }, async (args) => {
             syncClientIdentity();
             const result = await beginAgentRunHandler(handlerDeps, session.context, args);
@@ -1454,6 +1700,9 @@ export async function startMcpServer(deps) {
             const missing = requireExploredSessionRun(session, 'reserve_work_paths');
             if (missing)
                 return missing;
+            const intent = requireNoWorkflowIntent(session, 'reserve_work_paths');
+            if (intent)
+                return intent;
             return reserveWorkPathsHandler(handlerDeps, session.context, args);
         });
         server.registerTool('record_context_exploration', {
@@ -1483,6 +1732,10 @@ export async function startMcpServer(deps) {
             const missing = requireActiveSessionRun(session, 'record_context_exploration');
             if (missing)
                 return missing;
+            const run = session.context.run;
+            const workflowError = workflowCapabilityError(run, 'record_context', 'record_context_exploration');
+            if (workflowError)
+                return workflowError;
             return recordContextExplorationHandler(handlerDeps, attribution(), session.context, args);
         });
         server.registerTool('release_work_paths', {
@@ -1535,7 +1788,13 @@ export async function startMcpServer(deps) {
             const missing = requireExploredSessionRun(session, 'create_task');
             if (missing)
                 return missing;
+            const intent = requireNoWorkflowIntent(session, 'create_task');
+            if (intent)
+                return intent;
             const run = session.context.run;
+            const workflowError = workflowCapabilityError(run, 'create_task', 'create_task');
+            if (workflowError)
+                return workflowError;
             return createTaskHandler(bindProject(handlerDeps, run.projectId), attribution(), args);
         });
         server.registerTool('update_task', {
@@ -1559,7 +1818,22 @@ export async function startMcpServer(deps) {
             if (missing)
                 return missing;
             const run = session.context.run;
-            return updateTaskHandler(bindProject(handlerDeps, run.projectId), attribution(), args, run);
+            if (!run.workflow?.enabled && run.noWorkflowIntent !== 'provided') {
+                if (run.noWorkflowIntent !== 'intent_question_asked') {
+                    return requireNoWorkflowIntent(session, 'update_task');
+                }
+                if (!args.fields.description?.trim() || Object.keys(args.fields).some(field => field !== 'description')) {
+                    return errorResult('After the No workflow intent question, update_task must first persist only the user\'s answer in the task description.');
+                }
+            }
+            const workflowError = workflowCapabilityError(run, 'update_task', 'update_task');
+            if (workflowError)
+                return workflowError;
+            const result = await updateTaskHandler(bindProject(handlerDeps, run.projectId), attribution(), args, run);
+            if (!result.isError && !run.workflow?.enabled && run.noWorkflowIntent === 'intent_question_asked') {
+                run.noWorkflowIntent = 'provided';
+            }
+            return result;
         });
         server.registerTool('create_artifact', {
             description: 'Persist an analysis/plan/spec/diagram/mock/wireframe on a task after context exploration. Never write planning documents into a repository.',
@@ -1579,7 +1853,13 @@ export async function startMcpServer(deps) {
             const missing = requireExploredSessionRun(session, 'create_artifact');
             if (missing)
                 return missing;
+            const intent = requireNoWorkflowIntent(session, 'create_artifact');
+            if (intent)
+                return intent;
             const run = session.context.run;
+            const workflowError = workflowCapabilityError(run, 'create_artifact', 'create_artifact');
+            if (workflowError)
+                return workflowError;
             return createArtifactHandler(bindProject(handlerDeps, run.projectId), attribution(), args, run);
         });
         server.registerTool('ask_question', {
@@ -1594,7 +1874,65 @@ export async function startMcpServer(deps) {
             if (missing)
                 return missing;
             const run = session.context.run;
-            return askQuestionHandler(handlerDeps, attribution(), args, run);
+            if (!run.workflow?.enabled && run.noWorkflowIntent === 'missing' && args.category !== 'intent') {
+                return errorResult('This No workflow item has no instructions. The first question must use category intent and ask what should be done.');
+            }
+            if (!run.workflow?.enabled && run.noWorkflowIntent === 'intent_question_asked') {
+                return requireNoWorkflowIntent(session, 'ask_question');
+            }
+            const workflowError = workflowCapabilityError(run, 'ask_question', 'ask_question');
+            if (workflowError)
+                return workflowError;
+            const result = await askQuestionHandler(handlerDeps, attribution(), args, run);
+            if (!result.isError && !run.workflow?.enabled && run.noWorkflowIntent === 'missing') {
+                run.noWorkflowIntent = 'intent_question_asked';
+            }
+            return result;
+        });
+        server.registerTool('record_user_input', {
+            description: 'Persist the user\'s exact answer as an artifact and resolve the current workflow questions before continuing.',
+            inputSchema: {
+                question_ids: z.array(z.string()).min(1),
+                answer: z.string(),
+                coverage: z.array(z.object({
+                    repository_scope_id: z.string(),
+                    disposition: z.enum(['affected', 'reviewed_no_change', 'context_only', 'unavailable_acknowledged']),
+                    reason: z.string(),
+                    acknowledgement_id: z.string().nullable().optional(),
+                })).min(1),
+            },
+        }, async (args) => {
+            const missing = requireExploredSessionRun(session, 'record_user_input');
+            if (missing)
+                return missing;
+            return recordUserInputHandler(handlerDeps, attribution(), session.context, args);
+        });
+        server.registerTool('submit_workflow_stage', {
+            description: 'Submit the current workflow stage. The database validates its stored requirements and either advances or waits for user review.',
+            inputSchema: {
+                expected_workflow_revision: z.number().int().positive(),
+                artifacts: z.array(z.object({ artifact_id: z.string(), role: z.string() })),
+            },
+        }, async (args) => {
+            const missing = requireExploredSessionRun(session, 'submit_workflow_stage');
+            if (missing)
+                return missing;
+            return submitWorkflowStageHandler(handlerDeps, session.context, args);
+        });
+        server.registerTool('decide_workflow_review', {
+            description: 'Record the user\'s explicit approval or request for changes from this conversation. Uses the same workflow gate as the web app.',
+            inputSchema: {
+                task_id: z.string(),
+                stage_run_id: z.string(),
+                expected_workflow_revision: z.number().int().positive(),
+                decision: z.enum(['approved', 'changes_requested']),
+                user_message: z.string(),
+            },
+        }, async (args) => {
+            const missing = requireActiveSessionRun(session, 'decide_workflow_review');
+            if (missing)
+                return missing;
+            return decideWorkflowReviewHandler(handlerDeps, session.context, args);
         });
         server.registerTool('add_comment', {
             description: 'Legacy question-only alias. Agent progress narration is not persisted; use ask_question for categorized questions.',
@@ -1604,6 +1942,9 @@ export async function startMcpServer(deps) {
             if (missing)
                 return missing;
             const run = session.context.run;
+            const intent = requireNoWorkflowIntent(session, 'add_comment');
+            if (intent)
+                return intent;
             if (args.task_id !== run.taskId) {
                 return errorResult(`add_comment must stay on this agent run's task (${run.taskId}).`);
             }

package/dist/protocol.js

@@ -13,7 +13,16 @@ export const PROTOCOL_FULL = `## 5a. Agent working protocol
 
 Delivered redundantly (installed skill + MCP), phrased imperatively for the agent:
 
-**HARD STOP — unclear novel feature.** After \`record_context_exploration\` succeeds,
+**Workflow authority.** The \`workflow\` object returned by \`get_task\` is the durable
+source of truth. When \`workflow.enabled\` is true, follow only its current stage,
+stored instructions, capabilities, requirements, and gate. Never infer or skip a
+stage. Call \`submit_workflow_stage\` with the stage's persisted artifacts when its
+requirements are satisfied. A stage awaiting review never advances until the user
+approves through the web app or explicitly in conversation. Requested changes stay
+in the same stage. Only final user approval moves the item to Done.
+
+**HARD STOP — no-workflow unclear novel feature.** This rule applies only when
+\`workflow.enabled\` is false. After \`record_context_exploration\` succeeds,
 if the task does not explicitly request a build or name a deliverable, the immediate
 next tool call is \`ask_question\` with category \`intent\` and the exact question:
 “What should I produce for this feature? Select one or more: build, plan, spec,
@@ -36,8 +45,11 @@ is saved to the work item. I am applying the task's explicit intent gate now.”
    collaboration, claims, or reservations. The ID is the only context in the paste;
    everything current lives in ctrl-spc.
 2. **Begin explicitly.** Read every active repository scope, checkout, topology revision,
-   unmet dependency, and collaborator, then call \`begin_work\`. The first live run
-   becomes coordinator and \`begin_work\` moves a Backlog item to In Progress. Later runs
+   unmet dependency, and collaborator, then call \`begin_work\`. If the user supplied an
+   exact instruction alongside the copied command, pass it as \`prompt_instruction\`; never
+   invent one. The first live run
+   becomes coordinator and \`begin_work\` moves a Backlog item to In Progress. Workflow
+   tasks remain In Progress through every active stage and review gate. Later runs
    join as collaborators without repeating that transition. Only the current coordinator
    may make later task-status changes, and no agent marks an item Done autonomously.
 3. **Repair missing context.** If \`begin_work\` reports unavailable checkouts, warn the
@@ -76,13 +88,15 @@ is saved to the work item. I am applying the task's explicit intent gate now.”
    never disclose findings, conclusions, likely impact, or decisions. After persistence,
    terminal summaries may reference the persisted artifact/question but must add no
    unpersisted facts.
-6. **Infer explicit work; otherwise ask exactly what is needed.** After exploration is
-   recorded, classify intent from the work item's explicit wording and accepted answers,
+6. **Follow the workflow; otherwise ask exactly what is needed.** For an assigned workflow,
+   the stored current-stage instructions and capabilities decide the work; never skip ahead
+   based on task wording. Without a workflow, after exploration is recorded, classify intent
+   from the work item's explicit wording and accepted answers,
    never from the exploration findings. Findings do not turn an unclear request into an
    authorized deliverable. Perform the action only when the item explicitly names it; do
    not ask for confirmation. Otherwise use \`ask_question\`. For a bug, ask for reproduction steps,
    expected behavior, or actual behavior only when each is missing and not discoverable.
-   For a novel feature with no explicit build action or deliverable, apply the HARD STOP
+   For a no-workflow novel feature with no explicit build action or deliverable, apply the HARD STOP
    above; the immediate next call is the exact build/plan/spec/diagram/mock/wireframe
    \`ask_question\`.
    Generic goals such as “improve,” “coordinate,” “prepare,” or “support” do not authorize
@@ -94,11 +108,15 @@ is saved to the work item. I am applying the task's explicit intent gate now.”
    collision handoff. After \`ask_question\` succeeds, do no more work in that run: call
    \`end_work\` with reason \`pending_user_answer\`, a receipt outcome of \`blocked\`, the
    final task revision, and every live artifact ID; continue only in a later pasted run.
-7. **Persist every accepted answer and durable finding.** Immediately call \`update_task\`
-   to add accepted decisions, constraints, acceptance criteria, and durable findings to the
-   description. Use the latest \`get_task\` revision; refetch and reconcile on conflict.
+7. **Persist every accepted answer and durable finding.** For workflow questions, call
+   \`record_user_input\` with the open question IDs and the user's exact answer; it creates
+   the required answer artifact before the stage continues. For no-workflow tasks, use
+   revision-safe \`update_task\` for accepted decisions and constraints. Immediately call \`update_task\`
+   after accepting a no-workflow answer so a later agent can recover it.
    Never leave an accepted answer or finding only in terminal, chat, or a subagent report.
-8. **Reserve the exact write surface.** Before editing, call \`reserve_work_paths\` with
+8. **Reserve the exact write surface only when allowed.** Read-only workflow stages never
+   reserve write paths or edit files. When the current stage allows repository writes, call
+   \`reserve_work_paths\` with
    the topology revision and, for every intended edit, the exact
    \`repository_scope_id\`, selected \`repository_checkout_id\`, repo-relative path, and
    write mode. An empty path reserves the entire scope. Do not edit until the full atomic
@@ -106,12 +124,14 @@ is saved to the work item. I am applying the task's explicit intent gate now.”
 9. **Never edit through a collision.** A collision reserves nothing. Narrow to disjoint
    paths, wait, ask for an explicit handoff, or use an isolated Git worktree. Never edit a
    conflicting path, overwrite unexpected local changes, or assume another agent stopped.
-10. **Persist every substantive non-question output.** Use \`create_artifact\` for every
+10. **Persist and submit every substantive non-question output.** Use \`create_artifact\` for every
    plan, specification, research/finding report, schema, diagram, mock, and wireframe before
    presenting it as complete. Use type \`analysis\` for research/findings, \`plan\` for plans,
    \`spec\` for specifications or proposed schemas, and the matching visual type. Never
    write planning documents into a repository. Every artifact has exactly one coverage disposition and non-empty
-   reason for every active repository scope at the current topology revision.
+   reason for every active repository scope at the current topology revision. For workflow
+   tasks, pass those artifact IDs and requirement roles to \`submit_workflow_stage\`; the
+   database alone decides whether the next stage starts or a review gate opens.
 11. **Keep the work item self-sufficient.** Questions are durable records created through
    \`ask_question\`; accepted answers and durable facts live in the description; substantive
    outputs live in artifacts. No progress comments. Never leave useful
@@ -127,10 +147,11 @@ is saved to the work item. I am applying the task's explicit intent gate now.”
    abandoning the run. Missing, stale, foreign, duplicate, or incomplete receipts are
    rejected. Ending releases only this session's work.`;
 export const PROTOCOL_SHORT = 'ctrl-spc protocol (compact — full text: MCP prompt `ctrl-spc-protocol`): ' +
-    'HARD STOP unclear novel feature: immediately after record_context_exploration, ask_question category intent exactly “What should I produce for this feature? Select one or more: build, plan, spec, diagram, mock, wireframe.” Then end_work blocked pending_user_answer. No intervening get_task/update_task/create_artifact/reservation/tool; read-only sandbox is not a missing checkout. ' +
-    '1) get_task is read-only; begin_work (run coordinator); resolve missing checkouts via fetch/link or acknowledge_unavailable_checkout. ' +
+    'Workflow is authoritative: follow only get_task.workflow.current_stage instructions, capabilities, requirements, and gate. submit_workflow_stage cannot skip stages; requested changes stay in-stage; only final user approval sets Done. ' +
+    'For no-workflow unclear features only, MUST use ask_question and end blocked before doing unrequested work; never infer from findings. Generic goals improve, coordinate, prepare, and support are not deliverables. ' +
+    '1) get_task is read-only; begin_work (run coordinator) with exact prompt_instruction when supplied; resolve missing checkouts via fetch/link or acknowledge_unavailable_checkout. ' +
     '2) Every item needs read-only subagents covering scope IDs once. Codex spawn_agent MUST use fork_turns:none; its self-contained prompt has exact IDs/paths/focus, no copied command. Child calls no ctrl-spc tools and writes nothing. If unavailable, record blocked; stop. ' +
     '3) Parent must record_context_exploration before deciding, asking, planning, reserving, or editing. Before success narrate process only—no findings/conclusions/impact/decisions. Later summaries add no unpersisted facts. ' +
-    '4) Intent only from task/accepted answers, never findings; improve/coordinate/prepare/support are not deliverables. Unclear novel feature: next mutation after context MUST be ask_question for build/plan/spec/diagram/mock/wireframe. No update_task/create_artifact/reservation/decision/edit before answer; end blocked pending_user_answer. Bugs ask only missing repro/expected/actual. ' +
-    '5) Put every accepted answer and durable finding in the description via revision-safe update_task; use create_artifact for every substantive non-question output with coverage for every active scope. No progress comments or terminal-only findings. ' +
-    '6) reserve_work_paths exact checkout+paths; never edit collisions. release_work_paths, then end_work with persistence_receipt={final_task_revision,artifact_ids,outcome}.';
+    '4) Workflow stage data decides intent. Without a workflow, intent comes only from task, prompt, and accepted answers—never from findings. ' +
+    '5) Workflow answers use record_user_input artifacts; no-workflow answers use revision-safe update_task. Persist every substantive output with create_artifact and every active scope covered. No progress comments or terminal-only findings. ' +
+    '6) Call reserve_work_paths only when the stage allows writes and target the exact checkout; never edit collisions. release_work_paths, then end_work with persistence_receipt={final_task_revision,artifact_ids,outcome}.';

package/dist/skills.js

@@ -38,21 +38,23 @@ export function codexLegacySkillPath() {
 function protocolBody(mcpUrl) {
     return `Resolve a CTRL+SPC work item or artifact pasted as \`/ctrl-spc work <id>\` or \`/ctrl-spc artifact <id>\`, then follow the ctrl-spc working protocol:
 
-HARD STOP — unclear novel feature: after \`record_context_exploration\` succeeds, if the task does not explicitly request a build or name a deliverable, the next tool call MUST be \`ask_question\` with category \`intent\` and this exact question: “What should I produce for this feature? Select one or more: build, plan, spec, diagram, mock, wireframe.” Then call \`end_work\` with reason \`pending_user_answer\` and outcome \`blocked\`. In that run, never call \`get_task\` again, \`update_task\`, \`create_artifact\`, \`reserve_work_paths\`, or any other tool between the context artifact and \`ask_question\`. The context artifact is the only allowed artifact. Do not copy findings into the task description before the user answers. A read-only execution sandbox is not a missing checkout and must not change this intent question.
+WORKFLOW AUTHORITY — when \`get_task.workflow.enabled\` is true, follow only its current stage, stored instructions, capabilities, requirements, and gate. Never infer or skip a stage. Persist each required artifact, then call \`submit_workflow_stage\`. Review gates advance only after explicit user approval in the web app or conversation; requested changes stay in the same stage. Only final approval sets Done.
+
+HARD STOP — unclear novel feature (No workflow only): when \`workflow.enabled\` is false, after \`record_context_exploration\` succeeds, if the task does not explicitly request a build or name a deliverable, the next tool call MUST be \`ask_question\` with category \`intent\` and this exact question: “What should I produce for this feature? Select one or more: build, plan, spec, diagram, mock, wireframe.” Then call \`end_work\` with reason \`pending_user_answer\` and outcome \`blocked\`. In that run, never call \`get_task\` again, \`update_task\`, \`create_artifact\`, \`reserve_work_paths\`, or any other tool between the context artifact and \`ask_question\`. The context artifact is the only allowed artifact. Do not copy findings into the task description before the user answers. A read-only execution sandbox is not a missing checkout and must not change this intent question. The user may select one or more: build, plan, spec, diagram, mock, wireframe.
 
 Before the context artifact exists, never state or imply a requested deliverable and never mention repository counts, contents, tests, findings, or likely impact. If progress commentary is required, use only: “The required CTRL+SPC context review is in progress; no decision or repository change has been made.” After the context artifact and before the intent question, either say nothing or use only: “The required context review is saved to the work item. I am applying the task's explicit intent gate now.”
 
 1. Resolve without side effects — call \`get_task\` before anything else. It is read-only: it does not change status, presence, claims, or reservations. The ID is the only context in the paste; everything current lives in ctrl-spc.
-2. Begin explicitly — call \`begin_work\` after reading the topology. The first live run is coordinator and \`begin_work\` moves Backlog to In Progress; later runs join as collaborators. Only the coordinator changes status. Never mark an item \`done\` autonomously.
+2. Begin explicitly — call \`begin_work\` after reading the topology. If the user supplied an exact instruction alongside the copied command, pass it as \`prompt_instruction\`; never invent one. The first live run is coordinator and \`begin_work\` moves Backlog to In Progress; later runs join as collaborators. Only the coordinator changes status. Never mark an item \`done\` autonomously.
 3. Repair missing context — if \`begin_work\` reports an unavailable checkout, warn the user and offer to fetch or link it. Never fetch without approval. If the user explicitly continues without it, call \`acknowledge_unavailable_checkout\`, then call \`begin_work\` again after every missing scope is fetched or acknowledged.
 4. Delegate exploration — every pasted work item MUST use at least one read-only subagent. After \`begin_work\` joins, partition every available repository scope exactly once across bounded subagent invocations. Every child prompt must explicitly list its assigned \`repository_scope_ids\`; across the batch each available ID appears exactly once. When using Codex \`spawn_agent\`, MUST pass \`fork_turns: "none"\`; never pass \`all\` or a recent-turn count. Give each child a self-contained assignment containing only its exact scope IDs, checkout paths, inspection focus, read-only restrictions, and required report shape. Never include or inherit the parent \`/ctrl-spc work\` command. The child must not call any ctrl-spc tool—including \`get_task\` or \`begin_work\`—or pick up the work item; it only inspects assigned paths and returns its report. If zero scopes are available after explicit acknowledgements, one child inspects the task/artifact context and reports those unavailable scopes without pretending they were reviewed. Children inspect only: no file mutation, path reservation, ctrl-spc call, \`tee\`, shell redirection, temp/capture file, install, formatter, cache-generating command, or any command that can write. Inspection-first is sufficient; do not decide intent before reports are persisted. Each report uses \`{ agent, focus, repository_scope_ids, inspected_paths, findings, likely_impact, unresolved_questions }\`. If no subagent is available, do not explore directly: call \`record_context_exploration\` with \`blocked_reason = subagents_unavailable\`, tell the user, and stop.
-5. Persist context before deciding — the parent consolidates every child report and MUST call \`record_context_exploration\` to create the work item's analysis artifact before deciding what to do, asking a task question, planning, reserving, or editing. Pass the structured reports plus a separate coverage array; include every active scope exactly once, and give unavailable scopes their acknowledgement. Before the tool succeeds, commentary may state process only: never disclose findings, conclusions, likely impact, or decisions. After persistence, terminal summaries may reference the persisted artifact/question but must add no unpersisted facts.
-6. Decide or ask deterministically — after exploration is recorded, classify intent only from the work item's explicit wording and accepted answers, never from findings. Findings do not authorize a deliverable. Infer and perform the action only when the item explicitly names it. Otherwise persist only the necessary question with \`ask_question\`. For a bug, ask for reproduction steps, expected behavior, or actual behavior only when each is missing and not discoverable. For a novel feature with no explicit build action or deliverable, apply the HARD STOP above: the mandatory next mutating call after \`record_context_exploration\` is \`ask_question\`; it must say “select one or more: build, plan, spec, diagram, mock, wireframe.” Generic goals such as “improve,” “coordinate,” “prepare,” or “support” are not deliverables. In this state do not call \`update_task\`, \`create_artifact\`, \`reserve_work_paths\`, or \`create_task\`; do not decide, edit, or complete. The context analysis is the only allowed artifact before the answer. Ask before overriding an unmet dependency, splitting work, fetching, or accepting a collision handoff. After \`ask_question\` succeeds, do no more work in that run: call \`end_work\` with reason \`pending_user_answer\` and outcome \`blocked\`, then wait for a later pasted run.
-7. Persist answers and findings — after every accepted answer, call \`update_task\` to add the decision, constraint, acceptance criterion, and durable findings to the description. Pass the latest revision and refetch/reconcile on conflict. Do not use progress comments; do not leave findings only in the terminal.
-8. Reserve before writing — call \`reserve_work_paths\` with the topology revision, exact checkout ID, and every repository-relative path you intend to edit. Do not edit until the full atomic request succeeds. On collision, narrow to disjoint paths, wait, ask for an explicit handoff, or use an isolated Git worktree. Never edit a conflicting path.
-9. Persist every output — every substantive non-question output must be a ctrl-spc artifact before it is presented as complete. Use \`create_artifact\` type \`analysis\` for research/findings, \`plan\` for plans, \`spec\` for specifications or proposed schemas, and the matching type for diagrams, mocks, and wireframes. Never write planning documents into a repository. Every artifact includes exactly one coverage disposition and non-empty reason for every active repository scope.
+5. Persist context before deciding — the parent consolidates every child report and MUST call \`record_context_exploration\` to create the work item's analysis artifact before deciding what to do, asking a task question, planning, reserving, or editing. Pass the structured reports plus a separate coverage array; include every active repository scope exactly once, and give unavailable scopes their acknowledgement. Before the tool succeeds, commentary may state process only: never disclose findings, conclusions, likely impact, or decisions. After persistence, terminal summaries may reference the persisted artifact/question but must add no unpersisted facts.
+6. Decide or ask deterministically — assigned workflow stage data decides the work. Without a workflow, classify intent only from the work item's explicit wording and accepted answers, never from findings. Findings do not authorize a deliverable. Infer and perform the action only when the item explicitly names it. Otherwise persist only the necessary question with \`ask_question\`. For a bug, ask for reproduction steps, expected behavior, or actual behavior only when each is missing and not discoverable. For a novel feature with no explicit build action or deliverable, apply the HARD STOP above: the mandatory next mutating call after \`record_context_exploration\` is \`ask_question\`; it must say “select one or more: build, plan, spec, diagram, mock, wireframe.” Generic goals such as “improve,” “coordinate,” “prepare,” or “support” are not deliverables. In this state do not call \`update_task\`, \`create_artifact\`, \`reserve_work_paths\`, or \`create_task\`; do not decide, edit, or complete. The context analysis is the only allowed artifact before the answer. Ask before overriding an unmet dependency, splitting work, fetching, or accepting a collision handoff. After \`ask_question\` succeeds, do no more work in that run: call \`end_work\` with reason \`pending_user_answer\` and outcome \`blocked\`, then wait for a later pasted run.
+7. Persist answers and findings — workflow answers MUST use \`record_user_input\` with open question IDs and the exact user answer so an artifact is saved. For No workflow, after every accepted answer, call revision-safe \`update_task\` to add the decision, constraint, acceptance criterion, and durable findings to the description. Do not use progress comments; do not leave findings only in the terminal.
+8. Reserve before writing — read-only stages never reserve writes or edit files. When the current stage allows writes, call \`reserve_work_paths\` for the exact checkout and paths; never edit through a collision. Never edit a conflicting path; narrow the reservation or use an isolated Git worktree.
+9. Persist every output — call \`create_artifact\` for every substantive non-question output. Every artifact must have exactly one coverage disposition for every active repository scope. For workflow tasks, submit required artifact IDs and roles through \`submit_workflow_stage\`; the database decides whether to advance or wait for review. Never write planning documents into a repository.
 10. Split only with approval — when work is too large, use \`ask_question\`; on approval create dependency-linked items with \`create_task\`, a shared feature tag, and matching board order.
-11. Keep the item self-sufficient — questions are persisted through \`ask_question\`; accepted answers and durable facts live in the description; substantive outputs live in artifacts. \`add_comment\` is not for routine progress. A fresh agent must need no terminal, chat, or subagent history.
+11. Keep the item self-sufficient — questions are persisted through \`ask_question\`; every accepted answer and durable fact lives in the description; substantive outputs live in artifacts. Do not use progress comments; \`add_comment\` is not for routine progress. A fresh agent must need no terminal, chat, or subagent history.
 12. End with proof — release finished reservations with \`release_work_paths\`, then call \`end_work\` with \`persistence_receipt = { final_task_revision, artifact_ids, outcome }\`. \`artifact_ids\` must exactly match every live artifact produced by this run and include the context-exploration artifact. Use outcome \`completed\` only for finished work, \`blocked\` for a persisted question or unavailable subagents, and \`aborted\` only when intentionally abandoning the run. A missing, stale, foreign, duplicate, or incomplete receipt is rejected; ending releases only this session's work.
 
 Full protocol: MCP prompt \`ctrl-spc-protocol\`. Tools live at ${mcpUrl}.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ctrl-spc/cli",
-  "version": "1.2.3",
+  "version": "1.3.0",
   "description": "CTRL+SPC CLI — per-machine agent for browser login, project linking, presence, and the local MCP server.",
   "engines": {
     "node": ">=22"