@ctrl-spc/cli 1.3.5 → 1.3.6

package/dist/commands/run.js

@@ -881,7 +881,7 @@ export async function run() {
         'release_work_paths, transfer_coordination, acknowledge_unavailable_checkout, record_context_exploration, ' +
         'set_task_role_slugs, ' +
         'ask_question, record_user_input, submit_workflow_stage, decide_workflow_review, ' +
-        'end_work, create_task, update_task, create_artifact, add_comment)');
+        'end_work, create_task, update_task, create_artifact, update_artifact, add_comment)');
     console.log(`Projects: ${projects.length > 0 ? projects.map((project) => project.name).join(', ') : 'none initialized on this machine'}`);
     console.log('Presence: available');
     const dispatch = createAgentDispatchController(client, machine.id, registeredAgents);

package/dist/mcp.js

@@ -437,7 +437,15 @@ export async function beginAgentRunHandler(deps, session, args) {
                 // 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()
+                const acceptedIntentDecisions = (await must(deps.client
+                    .from('decisions')
+                    .select('id')
+                    .eq('task_id', args.task_id)
+                    .eq('category', 'intent')
+                    .eq('state', 'decided')
+                    .order('decided_at', { ascending: false }))) ?? [];
+                session.run.noWorkflowIntent = persistedInstruction === '' &&
+                    !args.prompt_instruction?.trim() && acceptedIntentDecisions.length === 0
                     ? 'missing'
                     : 'provided';
             }
@@ -683,7 +691,7 @@ function explorationArtifactContent(args, orderedCoverage) {
  * mutation. The receipt is deliberately session-local while its evidence is a
  * durable analysis artifact tied to the exact task, run, and topology revision.
  */
-export async function recordContextExplorationHandler(deps, attribution, session, args) {
+export async function recordContextExplorationHandler(deps, _attribution, session, args) {
     const active = joinedRunOrError(session, 'record_context_exploration');
     if ('content' in active)
         return active;
@@ -742,20 +750,23 @@ export async function recordContextExplorationHandler(deps, attribution, session
                 return errorResult('Exploration coverage acknowledgement_id is required only for unavailable_acknowledged repositories.');
             }
         }
-        const artifactResult = await createArtifactHandler(bindProject(deps, active.projectId), attribution, {
-            task_id: active.taskId,
-            type: 'analysis',
-            format: 'md',
-            content: explorationArtifactContent(args, orderedCoverage),
-            coverage: orderedCoverage,
-        }, active);
-        if (artifactResult.isError)
-            return artifactResult;
-        const first = artifactResult.content[0];
-        if (!first || first.type !== 'text')
-            throw new Error('analysis artifact returned no text result');
-        const payload = JSON.parse(first.text);
-        const artifactId = typeof payload.artifact?.id === 'string' ? payload.artifact.id : null;
+        const content = explorationArtifactContent(args, orderedCoverage);
+        const existingContext = await must(deps.client
+            .from('artifacts')
+            .select('revision')
+            .eq('task_id', active.taskId)
+            .eq('system_kind', 'context')
+            .is('deleted_at', null)
+            .maybeSingle());
+        const artifact = await must(deps.client.rpc('record_context_exploration_artifact', {
+            p_run: active.runId,
+            p_claim_fencing_token: active.fencingToken,
+            p_topology_revision: active.topologyRevision,
+            p_expected_revision: existingContext ? Number(existingContext.revision) : null,
+            p_content: content,
+            p_coverage: orderedCoverage,
+        }));
+        const artifactId = typeof artifact?.id === 'string' ? artifact.id : null;
         if (!artifactId)
             throw new Error('analysis artifact returned no id');
         session.exploration = {
@@ -778,6 +789,10 @@ export async function recordContextExplorationHandler(deps, attribution, session
         });
     }
     catch (err) {
+        if (err instanceof Error && err.message === 'context_conflict') {
+            return errorResult('record_context_exploration found newer work-item context. Reload the work item, ' +
+                'reconcile the latest context with these reports, and retry so no findings are lost.');
+        }
         return coordinationError('record_context_exploration', err);
     }
 }
@@ -793,92 +808,82 @@ function isPersistedAgentQuestion(row, taskId, agentRunId) {
         QUESTION_CATEGORIES.includes(match[1]) &&
         isRealQuestion(match[2]));
 }
-export async function askQuestionHandler(deps, attribution, args, agentRun) {
+export async function askQuestionHandler(deps, _attribution, args, agentRun) {
     if (args.task_id !== agentRun.taskId) {
         return errorResult(`ask_question must stay on this agent run's task (${agentRun.taskId}).`);
     }
     if (!QUESTION_CATEGORIES.includes(args.category))
         return errorResult('ask_question requires a supported category.');
+    if (!args.context?.trim())
+        return errorResult('ask_question requires concise context for the decision.');
     if (!isRealQuestion(args.question)) {
         return errorResult('ask_question requires real question text containing a question mark.');
     }
     const question = args.question.trim();
-    const result = await addCommentHandler(bindProject(deps, agentRun.projectId), attribution, { task_id: agentRun.taskId, body: `[question:${args.category}] ${question}` }, agentRun.runId);
-    if (result.isError)
-        return result;
-    const first = result.content[0];
-    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', {
+    let opened;
+    try {
+        opened = await must(deps.client.rpc('ask_agent_question', {
             p_run: agentRun.runId,
-            p_comment: commentId,
             p_category: args.category,
+            p_context: args.context.trim(),
             p_question: question,
+            p_related_artifact: args.related_artifact_id ?? null,
         }));
+    }
+    catch (err) {
+        return coordinationError('ask_question', err);
+    }
+    if (!opened)
+        return errorResult('ask_question returned no persisted question.');
+    const comment = opened?.comment && typeof opened.comment === 'object'
+        ? opened.comment
+        : null;
+    const commentId = typeof comment?.id === 'string' ? comment.id : null;
+    if (!commentId)
+        return errorResult('ask_question returned no persisted comment id for the decision.');
+    const decisionId = typeof opened?.decision_id === 'string' ? opened.decision_id : null;
+    const workflowQuestionId = typeof opened?.workflow_question_id === 'string' ? opened.workflow_question_id : null;
+    if (!decisionId)
+        return errorResult('ask_question returned no persisted decision id.');
+    if (agentRun.workflow?.enabled) {
         agentRun.workflow = await loadWorkflowContext(deps.client, agentRun.taskId);
     }
     return textResult({
         question: {
             category: args.category,
             text: question,
+            context: args.context.trim(),
             comment_id: commentId,
+            decision_id: decisionId,
             workflow_question_id: workflowQuestionId,
+            related_artifact_id: args.related_artifact_id ?? null,
         },
-        comment: payload.comment ?? null,
+        comment,
         ...(agentRun.workflow?.enabled ? { workflow: agentRun.workflow } : {}),
     });
 }
-export async function recordUserInputHandler(deps, attribution, session, args) {
+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.');
+    const decisionIds = args.decision_ids ?? args.question_ids;
+    if (!Array.isArray(decisionIds) || decisionIds.length === 0) {
+        return errorResult('record_user_input requires at least one decision id returned by ask_question.');
     }
     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', {
+        active.workflow = normalizeWorkflowContext(await must(deps.client.rpc('record_task_decisions', {
             p_run: active.runId,
-            p_question_ids: args.question_ids,
-            p_artifact: artifactId,
+            p_decision_ids: decisionIds,
+            p_answer: args.answer,
         })));
         return textResult({
             recorded: true,
-            artifact_id: artifactId,
-            question_ids: args.question_ids,
+            decision_ids: decisionIds,
             workflow: active.workflow,
         });
     }
@@ -934,27 +939,6 @@ export async function decideWorkflowReviewHandler(deps, session, args) {
         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,
@@ -963,17 +947,15 @@ export async function decideWorkflowReviewHandler(deps, session, args) {
             p_source: 'agent_conversation',
             p_evidence: args.user_message.trim(),
             p_agent_run: active.runId,
-            p_evidence_artifact: evidenceArtifactId,
+            p_evidence_artifact: null,
             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.'
@@ -991,11 +973,9 @@ 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 && !reviewEvidenceArtifactId) || !receipt) {
-                return errorResult('end_work requires a persistence_receipt and this session\'s persisted context or review evidence artifact.');
-            }
+            if (!receipt)
+                return errorResult('end_work requires a persistence_receipt for this session.');
             const outcome = receipt.outcome ?? 'completed';
             if (exploration?.status === 'blocked' && !['blocked', 'aborted'].includes(outcome)) {
                 return errorResult('A subagents_unavailable session may end only with outcome blocked or aborted.');
@@ -1018,16 +998,15 @@ export async function endAgentRunHandler(deps, session, args = {}, options = {})
             if (!Number.isInteger(receipt.final_task_revision) || receipt.final_task_revision < 1) {
                 return errorResult('end_work persistence_receipt requires a positive final_task_revision.');
             }
-            if (!Array.isArray(receipt.artifact_ids) || receipt.artifact_ids.length === 0) {
-                return errorResult('end_work persistence_receipt requires persisted artifact ids.');
-            }
+            if (!Array.isArray(receipt.artifact_ids))
+                return errorResult('end_work persistence_receipt requires artifact_ids.');
             const artifactIds = [...new Set(receipt.artifact_ids)];
             if (artifactIds.length !== receipt.artifact_ids.length) {
                 return errorResult('end_work persistence_receipt artifact_ids must be unique.');
             }
-            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 requiredContextArtifactId = exploration?.artifactId ?? null;
+            if (requiredContextArtifactId && !artifactIds.includes(requiredContextArtifactId)) {
+                return errorResult('end_work persistence_receipt must include this session\'s context artifact id.');
             }
             const task = await must(deps.client
                 .from('tasks')
@@ -1040,25 +1019,29 @@ export async function endAgentRunHandler(deps, session, args = {}, options = {})
             }
             const artifactRows = (await must(deps.client
                 .from('artifacts')
-                .select('id,task_id,agent_run_id,deleted_at')
+                .select('id,task_id,agent_run_id,updated_by_agent_run_id,deleted_at')
                 .eq('task_id', active.taskId)
-                .eq('agent_run_id', active.runId)
                 .is('deleted_at', null)
                 .order('created_at', { ascending: true })
                 .order('id', { ascending: true }))) ?? [];
             const artifactsById = new Map(artifactRows.map((artifact) => [artifact.id, artifact]));
-            const persistedArtifactIds = artifactRows.map((artifact) => artifact.id);
+            const persistedArtifactIds = artifactRows
+                .filter((artifact) => (artifact.agent_run_id === active.runId || artifact.updated_by_agent_run_id === active.runId))
+                .map((artifact) => artifact.id);
+            if (requiredContextArtifactId && !persistedArtifactIds.includes(requiredContextArtifactId)) {
+                persistedArtifactIds.push(requiredContextArtifactId);
+            }
             const missingArtifactIds = persistedArtifactIds.filter((id) => !artifactIds.includes(id));
-            const foreignArtifactIds = artifactIds.filter((id) => !artifactsById.has(id));
+            const persistedArtifactIdSet = new Set(persistedArtifactIds);
+            const foreignArtifactIds = artifactIds.filter((id) => !persistedArtifactIdSet.has(id));
             if (missingArtifactIds.length > 0 || foreignArtifactIds.length > 0) {
                 return errorResult('end_work persistence_receipt artifact_ids must exactly match every non-deleted artifact persisted by ' +
                     `this task run. Missing: ${missingArtifactIds.join(', ') || 'none'}. ` +
                     `Foreign or deleted: ${foreignArtifactIds.join(', ') || 'none'}.`);
             }
-            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 contextArtifact = requiredContextArtifactId ? artifactsById.get(requiredContextArtifactId) : null;
+            if (requiredContextArtifactId && (!contextArtifact || contextArtifact.task_id !== active.taskId)) {
+                return errorResult('end_work could not verify this session\'s context artifact.');
             }
         }
         const ended = await must(deps.client.rpc('end_agent_run', {
@@ -1067,7 +1050,6 @@ 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,
@@ -1172,7 +1154,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, workflow] = await Promise.all([
+        const [rawComments, rawArtifacts, rawDecisions, rawVersions, rawAgentRuns, rawTaskClaims, collaborationDocument, topology, workflow] = await Promise.all([
             must(client
                 .from('comments')
                 .select(COMMENT_SELECT)
@@ -1186,6 +1168,12 @@ export async function getTaskHandler(deps, _attribution, args, machineId) {
                 .is('deleted_at', null)
                 .order('created_at', { ascending: true })
                 .order('id', { ascending: true })),
+            must(client
+                .from('decisions')
+                .select('*')
+                .eq('task_id', row.id)
+                .order('asked_at', { ascending: true })
+                .order('id', { ascending: true })),
             must(client
                 .from('task_versions')
                 .select(TASK_VERSION_SELECT)
@@ -1222,12 +1210,19 @@ export async function getTaskHandler(deps, _attribution, args, machineId) {
         ]);
         const comments = sortRecords((rawComments ?? []).map(normalizeComment), 'created_at', 'id');
         const normalizedArtifacts = sortRecords((rawArtifacts ?? []).map(normalizeArtifact), 'created_at', 'id');
+        const hiddenArtifactKinds = new Set([
+            'superseded_context',
+            'legacy_decision_evidence',
+            'legacy_review_evidence',
+        ]);
+        const visibleArtifacts = normalizedArtifacts.filter((artifact) => (artifact.id === highlightArtifactId || !hiddenArtifactKinds.has(String(artifact.system_kind ?? ''))));
         const artifacts = highlightArtifactId
             ? [
-                ...normalizedArtifacts.filter((artifact) => artifact.id === highlightArtifactId),
-                ...normalizedArtifacts.filter((artifact) => artifact.id !== highlightArtifactId),
+                ...visibleArtifacts.filter((artifact) => artifact.id === highlightArtifactId),
+                ...visibleArtifacts.filter((artifact) => artifact.id !== highlightArtifactId),
             ]
-            : normalizedArtifacts;
+            : visibleArtifacts;
+        const decisions = sortRecords(rawDecisions ?? [], 'asked_at', 'id');
         const taskVersions = sortRecords(rawVersions ?? [], 'seq', 'id');
         const now = Date.now();
         const leaseIsLive = (value) => typeof value === 'string' && Number.isFinite(new Date(value).getTime()) && new Date(value).getTime() > now;
@@ -1270,6 +1265,7 @@ export async function getTaskHandler(deps, _attribution, args, machineId) {
             dependent_edges: task.dependent_edges,
             comments,
             artifacts,
+            decisions,
             task_versions: taskVersions,
             active_agent_runs: activeAgentRuns,
             active_task_claims: activeTaskClaims,
@@ -1408,6 +1404,9 @@ export async function createArtifactHandler(deps, attribution, args, agentRun) {
             return errorResult('create_artifact requires task_id.');
         if (!args.content)
             return errorResult('create_artifact requires content.');
+        if (args.purpose_key?.trim().startsWith('context:')) {
+            return errorResult('Context is a reserved work-item artifact. Use record_context_exploration instead.');
+        }
         if (agentRun) {
             if (agentRun.state !== 'joined') {
                 return errorResult('create_artifact is blocked while repositories are unavailable. Fetch or acknowledge them, then call begin_work again.');
@@ -1415,6 +1414,11 @@ export async function createArtifactHandler(deps, attribution, args, agentRun) {
             if (args.task_id !== agentRun.taskId) {
                 return errorResult(`create_artifact task_id must match this agent run's task (${agentRun.taskId}).`);
             }
+            if (!args.title?.trim())
+                return errorResult('create_artifact requires a title for agent artifacts.');
+            if (!args.purpose_key?.trim()) {
+                return errorResult('create_artifact requires a stable purpose_key for agent artifacts.');
+            }
             if (!Array.isArray(args.coverage) || args.coverage.length === 0) {
                 return errorResult('create_artifact requires repository coverage for every active project scope.');
             }
@@ -1433,6 +1437,8 @@ export async function createArtifactHandler(deps, attribution, args, agentRun) {
                 p_topology_revision: agentRun.topologyRevision,
                 p_type: args.type,
                 p_format: args.format ?? 'md',
+                p_title: args.title.trim(),
+                p_purpose_key: args.purpose_key.trim(),
                 p_content: args.content,
                 p_storage_path: null,
                 p_coverage: args.coverage.map((coverage) => ({
@@ -1459,12 +1465,14 @@ export async function createArtifactHandler(deps, attribution, args, agentRun) {
             task_id: args.task_id,
             type: args.type,
             format: args.format ?? 'md',
+            ...(args.title?.trim() ? { title: args.title.trim() } : {}),
+            ...(args.purpose_key?.trim() ? { purpose_key: args.purpose_key.trim() } : {}),
             content: args.content,
             created_by: deps.userId,
             from_agent: null,
             agent_run_id: null,
         })
-            .select('id,task_id,type,format,content,storage_path,created_by,from_agent,created_at')
+            .select('id,task_id,type,format,title,purpose_key,system_kind,content,storage_path,created_by,from_agent,created_at')
             .single());
         if (!row)
             throw new Error('Artifact insert returned no row.');
@@ -1476,6 +1484,63 @@ export async function createArtifactHandler(deps, attribution, args, agentRun) {
         return errorResult(`create_artifact failed: ${err.message}`);
     }
 }
+export async function updateArtifactHandler(deps, args, agentRun) {
+    try {
+        if (agentRun.state !== 'joined') {
+            return errorResult('update_artifact is blocked while repositories are unavailable. Fetch or acknowledge them, then call begin_work again.');
+        }
+        if (!args.id)
+            return errorResult('update_artifact requires an artifact id.');
+        if (!Number.isInteger(args.expected_revision) || args.expected_revision < 1) {
+            return errorResult('update_artifact requires the current positive artifact revision from get_task.');
+        }
+        if (!args.title?.trim())
+            return errorResult('update_artifact requires a title.');
+        if (!args.purpose_key?.trim())
+            return errorResult('update_artifact requires a stable purpose_key.');
+        if (args.purpose_key.trim().startsWith('context:')) {
+            return errorResult('Context is a reserved work-item artifact. Use record_context_exploration instead.');
+        }
+        if (!args.content)
+            return errorResult('update_artifact requires content.');
+        if (!Array.isArray(args.coverage) || args.coverage.length === 0) {
+            return errorResult('update_artifact requires repository coverage for every active project scope.');
+        }
+        for (const coverage of args.coverage) {
+            if (!coverage.repository_scope_id || !coverage.reason?.trim()) {
+                return errorResult('Every update_artifact coverage entry requires repository_scope_id and a non-empty reason.');
+            }
+            const unavailable = coverage.disposition === 'unavailable_acknowledged';
+            if (unavailable !== Boolean(coverage.acknowledgement_id)) {
+                return errorResult('update_artifact coverage acknowledgement_id is required only for unavailable_acknowledged repositories.');
+            }
+        }
+        const artifact = await must(deps.client.rpc('update_agent_artifact', {
+            p_run: agentRun.runId,
+            p_claim_fencing_token: agentRun.fencingToken,
+            p_topology_revision: agentRun.topologyRevision,
+            p_artifact: args.id,
+            p_expected_revision: args.expected_revision,
+            p_type: args.type,
+            p_format: args.format,
+            p_title: args.title.trim(),
+            p_purpose_key: args.purpose_key.trim(),
+            p_content: args.content,
+            p_coverage: args.coverage.map((coverage) => ({
+                repository_scope_id: coverage.repository_scope_id,
+                disposition: coverage.disposition,
+                reason: coverage.reason.trim(),
+                acknowledgement_id: coverage.acknowledgement_id ?? null,
+            })),
+        }));
+        if (!artifact)
+            throw new Error('update_agent_artifact returned no artifact');
+        return textResult({ artifact, repository_coverage: args.coverage });
+    }
+    catch (err) {
+        return coordinationError('update_artifact', err);
+    }
+}
 export async function addCommentHandler(deps, attribution, args, agentRunId) {
     try {
         if (!args.task_id)
@@ -1648,7 +1713,7 @@ export async function startMcpServer(deps) {
         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.'));
+                : 'Wait for the user to answer the decision in the web app, or record their conversational answer with record_user_input.'));
     }
     function buildServer(session) {
         const server = new McpServer({ name: 'ctrl-spc', version: BROKER_VERSION });
@@ -1783,7 +1848,7 @@ export async function startMcpServer(deps) {
                 reason: z.string().optional(),
                 persistence_receipt: z.object({
                     final_task_revision: z.number().int().positive(),
-                    artifact_ids: z.array(z.string()).min(1),
+                    artifact_ids: z.array(z.string()),
                     outcome: z.enum(['completed', 'blocked', 'aborted']).optional(),
                 }),
             },
@@ -1836,29 +1901,22 @@ export async function startMcpServer(deps) {
             if (missing)
                 return missing;
             const run = session.context.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 intent = requireNoWorkflowIntent(session, 'update_task');
+            if (intent)
+                return intent;
             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;
+            return updateTaskHandler(bindProject(handlerDeps, run.projectId), attribution(), args, run);
         });
         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.',
+            description: 'Create a titled analysis/plan/spec/diagram/mock/wireframe for a new stable purpose. Use update_artifact when that purpose already exists; a different purpose creates a different artifact.',
             inputSchema: {
                 task_id: z.string(),
                 type: z.enum(['analysis', 'plan', 'spec', 'diagram', 'mock', 'wireframe']),
                 format: z.enum(['md', 'html', 'json', 'svg']).optional().describe('Defaults to md'),
+                title: z.string().min(1),
+                purpose_key: z.string().min(1).describe('Stable machine-readable identity for this artifact purpose'),
                 content: z.string(),
                 coverage: z.array(z.object({
                     repository_scope_id: z.string(),
@@ -1880,12 +1938,44 @@ export async function startMcpServer(deps) {
                 return workflowError;
             return createArtifactHandler(bindProject(handlerDeps, run.projectId), attribution(), args, run);
         });
+        server.registerTool('update_artifact', {
+            description: 'Update the existing artifact for the same purpose. Pass its latest revision; stale updates conflict instead of creating a duplicate or overwriting newer work.',
+            inputSchema: {
+                id: z.string(),
+                expected_revision: z.number().int().positive(),
+                type: z.enum(['analysis', 'plan', 'spec', 'diagram', 'mock', 'wireframe']),
+                format: z.enum(['md', 'html', 'json', 'svg']),
+                title: z.string().min(1),
+                purpose_key: z.string().min(1),
+                content: 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).describe('Exactly one disposition for every active repository scope returned by get_task'),
+            },
+        }, async (args) => {
+            const missing = requireExploredSessionRun(session, 'update_artifact');
+            if (missing)
+                return missing;
+            const intent = requireNoWorkflowIntent(session, 'update_artifact');
+            if (intent)
+                return intent;
+            const run = session.context.run;
+            const workflowError = workflowCapabilityError(run, 'create_artifact', 'update_artifact');
+            if (workflowError)
+                return workflowError;
+            return updateArtifactHandler(bindProject(handlerDeps, run.projectId), args, run);
+        });
         server.registerTool('ask_question', {
             description: 'Persist a categorized, actionable question after complete context exploration. Questions are comments on the current work item.',
             inputSchema: {
                 task_id: z.string(),
                 category: z.enum(['clarification', 'reproduction', 'intent', 'dependency', 'checkout', 'collision', 'split']),
+                context: z.string().min(1).describe('Why this decision is needed and what it affects'),
                 question: z.string(),
+                related_artifact_id: z.string().nullable().optional(),
             },
         }, async (args) => {
             const missing = requireExploredSessionRun(session, 'ask_question');
@@ -1908,22 +1998,22 @@ export async function startMcpServer(deps) {
             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.',
+            description: 'Persist the user\'s exact answer on first-class decision records returned by ask_question. This creates no answer or approval artifact.',
             inputSchema: {
-                question_ids: z.array(z.string()).min(1),
+                decision_ids: z.array(z.string()).min(1).optional(),
+                question_ids: z.array(z.string()).min(1).optional().describe('Compatibility alias for decision_ids'),
                 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);
+            const result = await recordUserInputHandler(handlerDeps, attribution(), session.context, args);
+            const run = session.context.run;
+            if (!result.isError && run?.state === 'joined' && !run.workflow?.enabled && run.noWorkflowIntent === 'intent_question_asked') {
+                run.noWorkflowIntent = 'provided';
+            }
+            return result;
         });
         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.',
@@ -1972,6 +2062,7 @@ export async function startMcpServer(deps) {
             return askQuestionHandler(handlerDeps, attribution(), {
                 task_id: args.task_id,
                 category: 'clarification',
+                context: 'Legacy question recorded from add_comment.',
                 question: args.body,
             }, run);
         });

package/dist/protocol.js

@@ -87,7 +87,9 @@ is saved to the work item. I am applying the task's explicit intent gate now.”
    run acknowledgement ID. 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.
+   unpersisted facts. Context has a stable purpose for the current workflow stage (or work
+   item without a workflow): repeat exploration updates that artifact instead of creating
+   another card.
 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
@@ -108,11 +110,11 @@ 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.** 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.
+7. **Persist every accepted answer and durable finding.** \`ask_question\` creates a
+   first-class decision and returns its decision ID for the web app to display and answer.
+   When the user answers in the agent conversation instead, call \`record_user_input\` with
+   those decision IDs and the user's exact answer. Decisions
+   are not answer artifacts and are not copied into the task description.
    Never leave an accepted answer or finding only in terminal, chat, or a subagent report.
 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
@@ -124,16 +126,20 @@ 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 and submit every substantive non-question output.** Use \`create_artifact\` for every
+10. **Persist and submit every substantive non-question output.** Give each artifact a clear
+   title and stable \`purpose_key\`. Use \`create_artifact\` when that purpose does not exist and
+   \`update_artifact\` with the latest revision when the same purpose already exists; a
+   different purpose creates a different artifact. Persist 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. 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.
+   database alone decides whether the next stage starts or a review gate opens. Workflow
+   approval is displayed on the submitted plan; it is not a decision artifact.
 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
+   \`ask_question\`; accepted answers live in first-class decisions; substantive
    outputs live in artifacts. No progress comments. Never leave useful
    context only in terminal, chat history, a subagent report, or a repository planning file.
    If work is too large, ask through \`ask_question\`; after approval use \`create_task\` to
@@ -148,10 +154,10 @@ is saved to the work item. I am applying the task's explicit intent gate now.”
    rejected. Ending releases only this session's work.`;
 export const PROTOCOL_SHORT = 'ctrl-spc protocol (compact — full text: MCP prompt `ctrl-spc-protocol`): ' +
     '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. ' +
+    'No-workflow unclear feature: MUST ask_question, then end blocked; never infer from findings or call update_task/create_artifact/reserve_work_paths first. Improve, coordinate, prepare, 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) 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. ' +
+    '5) record_context_exploration revises one task context across stages/agents. ask_question creates decisions answered in web; chat answers use record_user_input and create no answer artifact. Same purpose: update_artifact; different purpose: create_artifact. Plan approval stays on the plan, not in Decisions. Cover every active scope. 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

@@ -48,13 +48,13 @@ Before the context artifact exists, never state or imply a requested deliverable
 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 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.
+5. Persist context before deciding — the parent consolidates every child report and MUST call \`record_context_exploration\` to create or update the work item's stable-purpose context artifact before deciding what to do, asking a task question, planning, reserving, or editing. Every agent and workflow stage revises the same task-level context artifact instead of creating another card. 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.
+7. Persist every accepted answer and finding — \`ask_question\` creates first-class decisions and returns decision IDs for the web app to display and answer. When the user answers in the agent conversation instead, use \`record_user_input\` with those decision IDs and the exact user answer. Decisions create no answer artifact and are not copied into the task 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.
+9. Persist every substantive non-question output — give every artifact a clear title and stable \`purpose_key\`. Call \`create_artifact\` for a new purpose and \`update_artifact\` with the latest revision when the same purpose already exists; a different purpose creates a different artifact. 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. Plan approval is displayed on the submitted plan and is not a decision artifact. 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\`; 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.
+11. Keep the item self-sufficient — questions and accepted answers are persisted as first-class decisions through \`ask_question\` and \`record_user_input\`; 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.3.5",
+  "version": "1.3.6",
   "description": "CTRL+SPC CLI — per-machine agent for browser login, project linking, presence, and the local MCP server.",
   "engines": {
     "node": ">=22"