@motionode/cli 0.1.2 → 0.2.0

package/lib/inbox.js

@@ -0,0 +1,75 @@
+'use strict';
+
+/**
+ * The local signal inbox: <repo>/.motionode/inbox.json.
+ * `motionode signals watch` writes signals here the moment Motionode pushes them;
+ * the hook and the MCP server read it locally (instant, no network, no model).
+ * A signal leaves the inbox when it is acknowledged (MCP ack_signal).
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { execFileSync } = require('child_process');
+
+function repoRoot(dir = process.cwd()) {
+	try {
+		return execFileSync('git', ['rev-parse', '--show-toplevel'], { cwd: dir, stdio: ['ignore', 'pipe', 'ignore'] }).toString().trim() || dir;
+	} catch (_e) {
+		return dir;
+	}
+}
+
+function inboxPath(dir) {
+	return path.join(repoRoot(dir), '.motionode', 'inbox.json');
+}
+
+/** Keep .motionode/ out of git without touching the repo's tracked .gitignore. */
+function ensureExcluded(dir) {
+	try {
+		const root = repoRoot(dir);
+		const exclude = path.join(root, '.git', 'info', 'exclude');
+		if (!fs.existsSync(path.dirname(exclude))) return;
+		const current = fs.existsSync(exclude) ? fs.readFileSync(exclude, 'utf8') : '';
+		if (!/^\.motionode\/?$/m.test(current)) fs.appendFileSync(exclude, `${current.endsWith('\n') || !current ? '' : '\n'}.motionode/\n`);
+	} catch (_e) { /* best effort */ }
+}
+
+function read(dir) {
+	try {
+		const data = JSON.parse(fs.readFileSync(inboxPath(dir), 'utf8'));
+		return Array.isArray(data?.signals) ? data.signals : [];
+	} catch (_e) {
+		return [];
+	}
+}
+
+function write(dir, signals) {
+	const file = inboxPath(dir);
+	fs.mkdirSync(path.dirname(file), { recursive: true });
+	const tmp = `${file}.${process.pid}.tmp`;
+	fs.writeFileSync(tmp, JSON.stringify({ updatedAt: new Date().toISOString(), signals }, null, 2));
+	fs.renameSync(tmp, file);
+}
+
+function ticketRefOf(signal) {
+	if (signal?.toRoom?.kind === 'ticket') return signal.toRoom.uuid;
+	if (signal?.fromRoom?.kind === 'ticket') return signal.fromRoom.uuid;
+	return signal?.ticketRef || null;
+}
+
+function add(dir, signal) {
+	const list = read(dir);
+	if (list.some((s) => s.id === signal.id)) return false;
+	list.push({ ...signal, ticketRef: ticketRefOf(signal), receivedAt: new Date().toISOString() });
+	write(dir, list.slice(-200));
+	return true;
+}
+
+function remove(dir, id) {
+	const list = read(dir);
+	const next = list.filter((s) => Number(s.id) !== Number(id));
+	if (next.length !== list.length) write(dir, next);
+	return next.length !== list.length;
+}
+
+module.exports = { repoRoot, inboxPath, ensureExcluded, read, write, add, remove, ticketRefOf };

package/lib/mcp.js

@@ -0,0 +1,327 @@
+'use strict';
+
+/**
+ * `motionode mcp`: a stdio MCP server so Claude Code, Cursor or any MCP client
+ * can work a Motionode ticket as a first-class worker (team-coordination spec §4.3).
+ * Every tool calls Motionode's /api/v1/agent as the connected person; Motionode
+ * applies the same permission checks as the web app.
+ *
+ * Transport: newline-delimited JSON-RPC 2.0 on stdin/stdout. Logs go to stderr only.
+ */
+
+const readline = require('readline');
+const pkg = require('../package.json');
+const { agentClient } = require('./agent_api');
+const Inbox = require('./inbox');
+
+const FALLBACK_PROTOCOL = '2025-06-18';
+const DISCOVER_VERSIONS = ['2026-07-28'];
+
+const TOOLS = [
+	{
+		name: 'my_work',
+		description: 'Tickets assigned to me in Motionode, with their current step and how many signals are waiting.',
+		inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+		run: (api) => api.get('/my_work'),
+	},
+	{
+		name: 'get_ticket',
+		description: 'One ticket: description, acceptance criteria, current step, branches per service, and pending signals. ref = ticket id like T11-604 or its uuid.',
+		inputSchema: { type: 'object', properties: { ref: { type: 'string' } }, required: ['ref'], additionalProperties: false },
+		run: (api, a) => api.get(`/ticket/${encodeURIComponent(a.ref)}`),
+	},
+	{
+		name: 'get_signals',
+		description: 'Signals for a ticket that I have not resolved yet (requirement changes, questions answered, overlaps, conflicts, failed checks). Check these at every task boundary.',
+		inputSchema: { type: 'object', properties: { ref: { type: 'string' } }, required: ['ref'], additionalProperties: false },
+		run: (api, a) => api.get(`/ticket/${encodeURIComponent(a.ref)}/signals`),
+	},
+	{
+		name: 'ack_signal',
+		description: 'Acknowledge a signal. Set incorporated=true (with how = one sentence) only once your work actually reflects it.',
+		inputSchema: {
+			type: 'object',
+			properties: { ref: { type: 'string' }, id: { type: 'number' }, incorporated: { type: 'boolean' }, how: { type: 'string' } },
+			required: ['ref', 'id'],
+			additionalProperties: false,
+		},
+		run: async (api, a) => {
+			const out = await api.post(`/ticket/${encodeURIComponent(a.ref)}/signals/${Number(a.id)}/ack`, { incorporated: !!a.incorporated, how: a.how || null });
+			Inbox.remove(process.cwd(), a.id);
+			return out;
+		},
+	},
+	{
+		name: 'start_step',
+		description: 'Start my assigned step on the ticket and register this session as its worker.',
+		inputSchema: { type: 'object', properties: { ref: { type: 'string' } }, required: ['ref'], additionalProperties: false },
+		run: (api, a) => api.post(`/ticket/${encodeURIComponent(a.ref)}/start_step`, {}),
+	},
+	{
+		name: 'report_progress',
+		description: 'One short line about what you are doing now (shown to the team; not a log).',
+		inputSchema: { type: 'object', properties: { ref: { type: 'string' }, text: { type: 'string' }, percent: { type: 'number' } }, required: ['ref', 'text'], additionalProperties: false },
+		run: (api, a) => api.post(`/ticket/${encodeURIComponent(a.ref)}/progress`, { text: a.text, percent: a.percent ?? null }),
+	},
+	{
+		name: 'ask_question',
+		description: 'Ask a question you cannot answer from the ticket. Motionode routes it (rules, the project manager, or the client) and the answer arrives as a signal.',
+		inputSchema: { type: 'object', properties: { ref: { type: 'string' }, question: { type: 'string' } }, required: ['ref', 'question'], additionalProperties: false },
+		run: (api, a) => api.post(`/ticket/${encodeURIComponent(a.ref)}/question`, { question: a.question }),
+	},
+	{
+		name: 'report_discovery',
+		description: 'You found something that may affect other work (a changed contract, a new status, a shared function). Motionode tells the tickets that change the same files, and the topic the work came from.',
+		inputSchema: { type: 'object', properties: { ref: { type: 'string' }, text: { type: 'string' }, files: { type: 'array', items: { type: 'string' } } }, required: ['ref', 'text'], additionalProperties: false },
+		run: (api, a) => api.post(`/ticket/${encodeURIComponent(a.ref)}/discovery`, { text: a.text, files: a.files || [] }),
+	},
+	{
+		name: 'request_review',
+		description: 'You finished the step: propose completion with a short summary. A person accepts it in Motionode.',
+		inputSchema: { type: 'object', properties: { ref: { type: 'string' }, summary: { type: 'string' } }, required: ['ref', 'summary'], additionalProperties: false },
+		run: (api, a) => api.post(`/ticket/${encodeURIComponent(a.ref)}/review`, { summary: a.summary }),
+	},
+	// ---- C1 coordination records: claims, observations, decisions, blockers, evidence (team-coordination C1) ----
+	{
+		name: 'claim_step',
+		description: 'Claim the ticket\'s current step before working on it (and start it). Exclusive: if another worker holds it you get who and until when. The claim is a lease (30 min default) that every call you make on the ticket renews; release it when you stop. Needs MOTIONODE_AGENT (your agent name).',
+		inputSchema: { type: 'object', properties: { ref: { type: 'string' }, lease_min: { type: 'number' }, note: { type: 'string' } }, required: ['ref'], additionalProperties: false },
+		run: (api, a) => api.post(`/ticket/${encodeURIComponent(a.ref)}/claim`, { lease_min: a.lease_min ?? null, note: a.note || null }),
+	},
+	{
+		name: 'release_step',
+		description: 'Release your claim on the ticket\'s step: reason "done" (your part is finished) or "handoff" (someone else should take it; say why in note).',
+		inputSchema: { type: 'object', properties: { ref: { type: 'string' }, reason: { type: 'string', enum: ['done', 'handoff'] }, note: { type: 'string' } }, required: ['ref', 'reason'], additionalProperties: false },
+		run: (api, a) => api.post(`/ticket/${encodeURIComponent(a.ref)}/release`, { reason: a.reason, note: a.note || null }),
+	},
+	{
+		name: 'report_observation',
+		description: 'Record something you or a tester SAW (a symptom), with its evidence: steps, env, sha, screenshots, preview url. It stays on this ticket; the coordinator links it to the one root-cause ticket.',
+		inputSchema: { type: 'object', properties: { ref: { type: 'string' }, text: { type: 'string' }, title: { type: 'string' }, evidence: { type: 'object' } }, required: ['ref', 'text'], additionalProperties: false },
+		run: (api, a) => api.post(`/ticket/${encodeURIComponent(a.ref)}/observation`, { text: a.text, title: a.title || null, evidence: a.evidence || null }),
+	},
+	{
+		name: 'report_finding',
+		description: 'Record a cause. verified=true only when established by evidence that holds (not suspected); root_cause=true when it names the one accountable problem.',
+		inputSchema: { type: 'object', properties: { ref: { type: 'string' }, text: { type: 'string' }, title: { type: 'string' }, verified: { type: 'boolean' }, root_cause: { type: 'boolean' }, evidence: { type: 'object' } }, required: ['ref', 'text'], additionalProperties: false },
+		run: (api, a) => api.post(`/ticket/${encodeURIComponent(a.ref)}/finding`, { text: a.text, title: a.title || null, verified: a.verified === true, root_cause: a.root_cause === true, evidence: a.evidence || null }),
+	},
+	{
+		name: 'link_observation',
+		description: 'Coordinator/manager: this ticket is the root cause of that observation (its uuid, on any ticket of the project). note = why. undo=true reverses it.',
+		inputSchema: { type: 'object', properties: { ref: { type: 'string' }, observation: { type: 'string' }, note: { type: 'string' }, undo: { type: 'boolean' } }, required: ['ref', 'observation', 'note'], additionalProperties: false },
+		run: (api, a) => api.post(`/ticket/${encodeURIComponent(a.ref)}/link_observation`, { observation: a.observation, note: a.note, undo: a.undo === true }),
+	},
+	{
+		name: 'relate_work',
+		description: 'Coordinator/manager: kind "duplicate_of" (this ticket is the same problem as other ticket) or "affects" (this root cause also affects other: a ticket, request or topic, whose people are told). note = why. undo=true reverses it.',
+		inputSchema: {
+			type: 'object',
+			properties: { ref: { type: 'string' }, kind: { type: 'string', enum: ['duplicate_of', 'affects'] }, other_type: { type: 'string', enum: ['ticket', 'request', 'topic'] }, other_ref: { type: 'string' }, note: { type: 'string' }, undo: { type: 'boolean' } },
+			required: ['ref', 'kind', 'other_type', 'other_ref', 'note'],
+			additionalProperties: false,
+		},
+		run: (api, a) => api.post(`/ticket/${encodeURIComponent(a.ref)}/relate`, { kind: a.kind, other: { type: a.other_type, ref: a.other_ref }, note: a.note, undo: a.undo === true }),
+	},
+	{
+		name: 'ask_decision',
+		description: 'A decision only a person can take, with at least two options (label + consequence). One owner (a user uuid; default the project manager), due in due_hours (default 24). Past due it is re-sent. The choice arrives as a "decided" signal.',
+		inputSchema: {
+			type: 'object',
+			properties: {
+				ref: { type: 'string' },
+				question: { type: 'string' },
+				options: { type: 'array', items: { type: 'object', properties: { key: { type: 'string' }, label: { type: 'string' }, consequence: { type: 'string' } }, required: ['label'] } },
+				owner: { type: 'string' },
+				backup: { type: 'string' },
+				due_hours: { type: 'number' },
+			},
+			required: ['ref', 'question', 'options'],
+			additionalProperties: false,
+		},
+		run: (api, a) => api.post(`/ticket/${encodeURIComponent(a.ref)}/decision`, { question: a.question, options: a.options, owner: a.owner || null, backup: a.backup || null, due_hours: a.due_hours ?? null }),
+	},
+	{
+		name: 'choose_decision',
+		description: 'Record the option taken on a decision (its uuid) -- only its owner, an addressee or a project decider may.',
+		inputSchema: { type: 'object', properties: { decision: { type: 'string' }, option: { type: 'string' }, note: { type: 'string' } }, required: ['decision', 'option'], additionalProperties: false },
+		run: (api, a) => api.post(`/decision/${encodeURIComponent(a.decision)}/choose`, { option: a.option, note: a.note || null }),
+	},
+	{
+		name: 'report_blocker',
+		description: 'The current step cannot go on. It goes Waiting with your reason. Say what it waits on: blocking_ticket (another ticket, a real dependency) or decision {question, options} (a person\'s choice). category: CLIENT, VENDOR, INTERNAL, DEPENDENCY or OTHER.',
+		inputSchema: {
+			type: 'object',
+			properties: {
+				ref: { type: 'string' },
+				reason: { type: 'string' },
+				category: { type: 'string', enum: ['CLIENT', 'VENDOR', 'INTERNAL', 'DEPENDENCY', 'OTHER'] },
+				blocking_ticket: { type: 'string' },
+				decision: { type: 'object', properties: { question: { type: 'string' }, options: { type: 'array' }, owner: { type: 'string' }, due_hours: { type: 'number' } }, required: ['question', 'options'] },
+			},
+			required: ['ref', 'reason'],
+			additionalProperties: false,
+		},
+		run: (api, a) => api.post(`/ticket/${encodeURIComponent(a.ref)}/blocker`, { reason: a.reason, category: a.category || null, ticket: a.blocking_ticket || null, decision: a.decision || null }),
+	},
+	{
+		name: 'submit_evidence',
+		description: 'Evidence your fix rests on, bound to a commit. kind fails_without: data {test, command, without:{sha, output}, with:{sha, output}}. suite_baseline: sha + data {suites, before:{passed,failed}, after:{passed,failed}}. preview_check: record = the browser-check run id. tester_recheck: record = a person\'s QA result id (you cannot be the tester). Returns the ticket\'s readiness.',
+		inputSchema: {
+			type: 'object',
+			properties: { ref: { type: 'string' }, kind: { type: 'string', enum: ['fails_without', 'suite_baseline', 'preview_check', 'tester_recheck'] }, sha: { type: 'string' }, record: { type: 'string' }, note: { type: 'string' }, data: { type: 'object' } },
+			required: ['ref', 'kind'],
+			additionalProperties: false,
+		},
+		run: (api, a) => api.post(`/ticket/${encodeURIComponent(a.ref)}/evidence`, { kind: a.kind, sha: a.sha || null, ref: a.record || null, note: a.note || null, data: a.data || null }),
+	},
+	{
+		name: 'open_hotfix',
+		description: 'Project manager / owner only: ship one verified fix to staging ahead of the batch (a one-member release, built at once). reason = why it cannot wait. Needs fails_without + a clean suite_baseline; the person\'s re-check may follow the ship.',
+		inputSchema: { type: 'object', properties: { ref: { type: 'string' }, reason: { type: 'string' } }, required: ['ref', 'reason'], additionalProperties: false },
+		run: (api, a) => api.post(`/ticket/${encodeURIComponent(a.ref)}/hotfix`, { reason: a.reason }),
+	},
+	// C1-031: file work and keep project notes (project = uuid or exact name).
+	{
+		name: 'list_deliverables',
+		description: 'A project\'s deliverables (display id, title, uuid), to file work under. project = its uuid or exact name.',
+		inputSchema: { type: 'object', properties: { project: { type: 'string' } }, required: ['project'], additionalProperties: false },
+		run: (api, a) => api.get(`/project/${encodeURIComponent(a.project)}/deliverables`),
+	},
+	{
+		name: 'create_work_item',
+		description: 'File a work item (a ticket in setup; nothing starts). An open ticket with the same title refuses with that ticket: add to it instead, or pass confirmed_new if this is genuinely separate. Related open work comes back as similar. deliverable = display id, uuid or title (default: the project\'s Interrupt deliverable); new_deliverable = a deliverable by name (reused if the project has one).',
+		inputSchema: {
+			type: 'object',
+			properties: { project: { type: 'string' }, title: { type: 'string' }, description: { type: 'string' }, deliverable: { type: 'string' }, new_deliverable: { type: 'string' }, acceptance_criteria: { type: 'array', items: { type: 'string' } }, confirmed_new: { type: 'boolean' } },
+			required: ['project', 'title'],
+			additionalProperties: false,
+		},
+		run: (api, a) => api.post(`/project/${encodeURIComponent(a.project)}/work_items`, {
+			title: a.title, description: a.description || '', deliverable: a.deliverable || null, newDeliverable: a.new_deliverable || null,
+			acceptanceCriteria: a.acceptance_criteria || [], confirmedNew: a.confirmed_new === true,
+		}),
+	},
+	{
+		name: 'update_work_item',
+		description: 'Change a work item\'s title and/or description, as me (I need edit rights on its project). ref = its code (T2-21) or uuid. Status changes aren\'t available yet: Motionode has no cancel or close for a work item.',
+		inputSchema: {
+			type: 'object',
+			properties: { project: { type: 'string' }, ref: { type: 'string' }, title: { type: 'string' }, description: { type: 'string' } },
+			required: ['project', 'ref'],
+			additionalProperties: false,
+		},
+		run: (api, a) => api.patch(`/project/${encodeURIComponent(a.project)}/work_items/${encodeURIComponent(a.ref)}`, {
+			...(typeof a.title === 'string' ? { title: a.title } : {}),
+			...(typeof a.description === 'string' ? { description: a.description } : {}),
+		}),
+	},
+	{
+		name: 'list_notes',
+		description: 'The project notes I may read: uuid, title (first line), where attached, size.',
+		inputSchema: { type: 'object', properties: { project: { type: 'string' } }, required: ['project'], additionalProperties: false },
+		run: (api, a) => api.get(`/project/${encodeURIComponent(a.project)}/notes`),
+	},
+	{
+		name: 'read_note',
+		description: 'One project note: its text and HTML.',
+		inputSchema: { type: 'object', properties: { project: { type: 'string' }, uuid: { type: 'string' } }, required: ['project', 'uuid'], additionalProperties: false },
+		run: (api, a) => api.get(`/project/${encodeURIComponent(a.project)}/notes/${encodeURIComponent(a.uuid)}`),
+	},
+	{
+		name: 'write_note',
+		description: 'Create a project note from markdown, or replace one (uuid given; you must have written it or have it shared with you). deliverable or ticket makes it a team note the project team sees; otherwise it is a board note, shared with share_with (emails or user uuids of the project).',
+		inputSchema: {
+			type: 'object',
+			properties: { project: { type: 'string' }, uuid: { type: 'string' }, markdown: { type: 'string' }, category: { type: 'string' }, deliverable: { type: 'string' }, ticket: { type: 'string' }, share_with: { type: 'array', items: { type: 'string' } } },
+			required: ['project', 'markdown'],
+			additionalProperties: false,
+		},
+		run: (api, a) => (a.uuid
+			? api.patch(`/project/${encodeURIComponent(a.project)}/notes/${encodeURIComponent(a.uuid)}`, { markdown: a.markdown, category: a.category || null })
+			: api.post(`/project/${encodeURIComponent(a.project)}/notes`, { markdown: a.markdown, category: a.category || null, deliverable: a.deliverable || null, ticket: a.ticket || null, shareWith: a.share_with || [] })),
+	},
+];
+
+/** Tools a Motionode older than the CLI may not serve yet (a 404 from them means "not offered", not "not found"). */
+const NEWER_TOOLS = new Set(TOOLS.map((t) => t.name).filter((n) => !['my_work', 'get_ticket', 'get_signals', 'ack_signal'].includes(n)));
+
+function send(msg) {
+	process.stdout.write(`${JSON.stringify(msg)}\n`);
+}
+
+async function handle(msg, api) {
+	const { id, method, params } = msg || {};
+	if (method === 'initialize') {
+		return {
+			protocolVersion: params?.protocolVersion || FALLBACK_PROTOCOL,
+			capabilities: { tools: {} },
+			serverInfo: { name: 'motionode', version: pkg.version },
+			instructions: 'Motionode tickets. claim_step before working a step and release_step when you stop. Call get_signals at every task boundary and before finishing; ack_signal with incorporated=true once your work reflects a change. Report what you saw with report_observation, causes with report_finding, blockers with report_blocker, and back every fix with submit_evidence (fails_without + suite_baseline).',
+		};
+	}
+	// Newer MCP handshake (protocol 2026-07-28): server/discover instead of initialize.
+	if (method === 'server/discover') {
+		return {
+			resultType: 'complete',
+			supportedVersions: DISCOVER_VERSIONS,
+			capabilities: { tools: {} },
+			_meta: { 'io.modelcontextprotocol/serverInfo': { name: 'motionode', version: pkg.version } },
+		};
+	}
+	if (method === 'ping') return {};
+	if (method === 'tools/list') {
+		return { resultType: 'complete', tools: TOOLS.map(({ name, description, inputSchema }) => ({ name, description, inputSchema })) };
+	}
+	if (method === 'tools/call') {
+		const tool = TOOLS.find((t) => t.name === params?.name);
+		if (!tool) return { resultType: 'complete', content: [{ type: 'text', text: `Unknown tool ${params?.name}.`, isError: true }], isError: true };
+		try {
+			const out = await tool.run(api, params?.arguments || {});
+			const pending = Inbox.read(process.cwd()).length;
+			const text = JSON.stringify({ ...out, signals_pending: pending }, null, 2);
+			return { resultType: 'complete', content: [{ type: 'text', text }] };
+		} catch (err) {
+			const newer = NEWER_TOOLS.has(tool.name);
+			const msgText = err.status === 404 && newer && /cannot (get|post)|not found$/i.test(err.message || '')
+				? 'This Motionode does not offer that yet.'
+				: err.message;
+			return { resultType: 'complete', content: [{ type: 'text', text: msgText, isError: true }], isError: true };
+		}
+	}
+	if (id === undefined || id === null) return undefined; // notification (e.g. notifications/initialized)
+	const e = new Error(`Method not found: ${method}`);
+	e.code = -32601;
+	throw e;
+}
+
+function serve(config) {
+	const api = agentClient(config);
+	const rl = readline.createInterface({ input: process.stdin, terminal: false });
+	const inflight = new Set();
+	rl.on('line', (line) => {
+		const job = onLine(line);
+		inflight.add(job);
+		job.finally(() => inflight.delete(job));
+	});
+	async function onLine(line) {
+		const trimmed = line.trim();
+		if (!trimmed) return;
+		let msg;
+		try { msg = JSON.parse(trimmed); } catch (_e) {
+			send({ jsonrpc: '2.0', id: null, error: { code: -32700, message: 'Parse error' } });
+			return;
+		}
+		try {
+			const result = await handle(msg, api);
+			if (msg.id !== undefined && msg.id !== null && result !== undefined) send({ jsonrpc: '2.0', id: msg.id, result });
+		} catch (err) {
+			if (msg.id !== undefined && msg.id !== null) send({ jsonrpc: '2.0', id: msg.id, error: { code: err.code || -32603, message: err.message } });
+		}
+	}
+	// Input closed: answer what is still running, then exit.
+	rl.on('close', async () => { await Promise.allSettled([...inflight]); process.exit(0); });
+	process.stderr.write(`motionode mcp ${pkg.version} serving ${api.base}\n`);
+}
+
+module.exports = { serve, handle, TOOLS };

package/lib/project_cmds.js

@@ -0,0 +1,116 @@
+'use strict';
+
+/**
+ * C1-031: file work and keep project notes from the terminal, as the connected person (same machine token as the rest
+ * of the CLI, or MOTIONODE_TOKEN). The project is --project <uuid or exact name>, or MOTIONODE_PROJECT.
+ *
+ *   motionode deliverables --project P
+ *   motionode work-item create --project P --title T [--description D | --description-file F]
+ *                               [--deliverable R2-1 | --new-deliverable "Name"] [--criteria "a | b"] [--confirmed-new]
+ *   motionode work-item update <code> --project P [--title T] [--description D | --description-file F]   (C1-032)
+ *   motionode notes list --project P
+ *   motionode notes get <uuid> --project P [--html]
+ *   motionode notes create --project P --file F.md [--deliverable R | --ticket T] [--share a@x,b@y] [--category C]
+ *   motionode notes update <uuid> --project P --file F.md
+ */
+
+const fs = require('fs');
+const { agentClient } = require('./agent_api');
+
+function projectOf(args) {
+	const p = (typeof args.project === 'string' && args.project) || process.env.MOTIONODE_PROJECT || '';
+	if (!p) throw new Error('Say which project: --project <uuid or name> (or set MOTIONODE_PROJECT).');
+	return encodeURIComponent(p);
+}
+
+function readText(file) {
+	if (typeof file !== 'string' || !file) throw new Error('Give the content with --file <path>.');
+	return fs.readFileSync(file, 'utf8');
+}
+
+const list = (value) => (typeof value === 'string' ? value.split('|').map((s) => s.trim()).filter(Boolean) : []);
+
+async function deliverables(config, args, { api = agentClient(config), out = console.log } = {}) {
+	const res = await api.get(`/project/${projectOf(args)}/deliverables`);
+	for (const d of res.deliverables || []) out(`${d.displayId || '-'}\t${d.title}${Number(d.isInterrupt) ? ' (Interrupt)' : ''}\t${d.uuid}`);
+	return res;
+}
+
+async function createWorkItem(config, args, { api = agentClient(config), out = console.log } = {}) {
+	if (typeof args.title !== 'string' || !args.title.trim()) throw new Error('Give the work item a --title.');
+	const description = typeof args['description-file'] === 'string' ? readText(args['description-file']) : (typeof args.description === 'string' ? args.description : '');
+	try {
+		const res = await api.post(`/project/${projectOf(args)}/work_items`, {
+			title: args.title,
+			description,
+			deliverable: typeof args.deliverable === 'string' ? args.deliverable : null,
+			newDeliverable: typeof args['new-deliverable'] === 'string' ? args['new-deliverable'] : null,
+			acceptanceCriteria: list(args.criteria),
+			confirmedNew: args['confirmed-new'] === true,
+		});
+		out(`✓ ${res.workItem.displayId || res.workItem.uuid} "${res.workItem.title}" in ${res.deliverable.displayId || ''} ${res.deliverable.title}${res.deliverable.created ? ' (new deliverable)' : ''} — in setup, nothing started`);
+		for (const s of res.similar || []) out(`  similar open work: ${s.displayId || s.uuid} "${s.title}"${s.why ? ` (${s.why})` : ''}`);
+		return res;
+	} catch (err) {
+		// 409: open work already has this title -- the API names it.
+		if (err.status === 409) out('  (pass --confirmed-new if this is genuinely separate)');
+		throw err;
+	}
+}
+
+/** C1-032: change a work item's title and/or description, as the connected person (their edit rights on the project). */
+async function updateWorkItem(config, args, { api = agentClient(config), out = console.log } = {}) {
+	const ref = args._[1];
+	if (!ref) throw new Error('Which work item? motionode work-item update <code> --title T');
+	const patch = {};
+	if (typeof args.title === 'string') patch.title = args.title;
+	if (typeof args['description-file'] === 'string') patch.description = readText(args['description-file']);
+	else if (typeof args.description === 'string') patch.description = args.description;
+	if (typeof args.status === 'string') patch.status = args.status;
+	if (!Object.keys(patch).length) throw new Error('Say what to change: --title and/or --description (or --description-file).');
+	const res = await api.patch(`/project/${projectOf(args)}/work_items/${encodeURIComponent(ref)}`, patch);
+	out(res.changed && res.changed.length
+		? `✓ ${res.workItem.displayId || res.workItem.uuid} "${res.workItem.title}": changed ${res.changed.join(' and ')}`
+		: `= ${res.workItem.displayId || res.workItem.uuid} "${res.workItem.title}": nothing to change`);
+	return res;
+}
+
+async function notes(config, args, { api = agentClient(config), out = console.log } = {}) {
+	const sub = args._[0] || 'list';
+	const project = projectOf(args);
+	if (sub === 'list') {
+		const res = await api.get(`/project/${project}/notes`);
+		for (const n of res.notes || []) out(`${n.uuid}\t${n.title || '(untitled)'}\t${n.entityType}${n.category ? `/${n.category}` : ''}\t${n.chars} chars`);
+		return res;
+	}
+	const uuid = args._[1];
+	if (sub === 'get') {
+		if (!uuid) throw new Error('Which note? motionode notes get <uuid>');
+		const res = await api.get(`/project/${project}/notes/${encodeURIComponent(uuid)}`);
+		out(args.html ? (res.note.html || '') : (res.note.text || ''));
+		return res;
+	}
+	if (sub === 'create') {
+		const res = await api.post(`/project/${project}/notes`, {
+			markdown: readText(args.file),
+			category: typeof args.category === 'string' ? args.category : null,
+			deliverable: typeof args.deliverable === 'string' ? args.deliverable : null,
+			ticket: typeof args.ticket === 'string' ? args.ticket : null,
+			shareWith: typeof args.share === 'string' ? args.share.split(',').map((s) => s.trim()).filter(Boolean) : [],
+		});
+		out(`✓ note ${res.note.uuid} "${res.note.title || ''}" (${res.note.entityType})`);
+		return res;
+	}
+	if (sub === 'update') {
+		if (!uuid) throw new Error('Which note? motionode notes update <uuid> --file F.md');
+		const res = await api.patch(`/project/${project}/notes/${encodeURIComponent(uuid)}`, {
+			markdown: readText(args.file),
+			category: typeof args.category === 'string' ? args.category : null,
+		});
+		out(`✓ updated note ${res.note.uuid} "${res.note.title || ''}"`);
+		return res;
+	}
+	throw new Error(`Unknown: motionode notes ${sub} (list | get | create | update)`);
+}
+
+module.exports = { deliverables, createWorkItem, updateWorkItem, notes, _internals: { projectOf, list } };

package/lib/signals_hook.js

@@ -0,0 +1,58 @@
+'use strict';
+
+/**
+ * `motionode signals hook <event>`: run by Claude Code hooks (no model, no network;
+ * reads the local inbox that `motionode signals watch` keeps). It puts pending
+ * Motionode signals in front of the agent at a safe point:
+ *   PostToolUse / UserPromptSubmit → add them to the agent's context;
+ *   Stop → refuse to finish while a signal that needs action is unacknowledged
+ *          (never twice in a row: Claude Code's stop_hook_active).
+ * The agent clears a signal with the MCP tool ack_signal.
+ */
+
+const Inbox = require('./inbox');
+
+function readStdin() {
+	return new Promise((resolve) => {
+		if (process.stdin.isTTY) return resolve({});
+		let data = '';
+		process.stdin.setEncoding('utf8');
+		process.stdin.on('data', (c) => { data += c; });
+		process.stdin.on('end', () => { try { resolve(JSON.parse(data || '{}')); } catch (_e) { resolve({}); } });
+		setTimeout(() => resolve({}), 1500);
+	});
+}
+
+function describe(signals) {
+	const lines = signals.slice(0, 8).map((s) => `- [#${s.id} · ${s.kind}${s.requiresAction ? ' · needs action' : ''} · ticket ${s.ticketRef || '?'}] ${String(s.summary || '').replace(/\s+/g, ' ').slice(0, 300)}`);
+	const more = signals.length > 8 ? `\n…and ${signals.length - 8} more (call get_signals).` : '';
+	return `Motionode signals for this work (acknowledge each with the motionode ack_signal tool; set incorporated=true only once your work reflects it):\n${lines.join('\n')}${more}`;
+}
+
+async function run(event) {
+	const input = await readStdin();
+	const dir = input.cwd || process.cwd();
+	const pending = Inbox.read(dir);
+	if (event === 'Stop') {
+		if (input.stop_hook_active) return; // already blocked once; let the agent stop
+		const critical = pending.filter((s) => s.requiresAction);
+		if (!critical.length) return;
+		process.stdout.write(JSON.stringify({
+			decision: 'block',
+			reason: `${describe(critical)}\nBefore finishing: handle these, or acknowledge them with ack_signal and say why they don't apply.`,
+		}));
+		return;
+	}
+	if (!pending.length) return;
+	process.stdout.write(JSON.stringify({
+		hookSpecificOutput: { hookEventName: event, additionalContext: describe(pending) },
+	}));
+}
+
+function printPending() {
+	const pending = Inbox.read(process.cwd());
+	if (!pending.length) { console.log('No Motionode signals waiting for this repository.'); return; }
+	console.log(describe(pending));
+}
+
+module.exports = { run, printPending, describe };