@orboto/mcp 0.195.1 → 0.197.0

package/dist/tools/spec-readiness.test.js

@@ -0,0 +1,85 @@
+import { specReleaseInfo } from './shared.js';
+import { makeWorkSessionsHandler } from './work-sessions.js';
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { z } from 'zod';
+import { OrbotoApiError, OrbotoClient } from '../orboto-client.js';
+import { makeWorkStartHandler, makeWorkSessionStartHandler, workStartToolConfig } from './work-sessions.js';
+import { makeClaimHandler } from './claim.js';
+import { specGateFailure, TicketSpecStateSchema } from './spec-schemas.js';
+import { updateProjectToolConfig } from './update-project.js';
+import { makeAssignHandler, updateTicketToolConfig } from './ticket-writes.js';
+afterEach(() => { vi.restoreAllMocks(); });
+describe('spec readiness tool contracts', () => {
+    it('keeps the isolated MCP state enum in sync with the API contract', () => {
+        const canonical = readFileSync(path.resolve(process.cwd(), '../../packages/shared-schema/src/spec-readiness.ts'), 'utf8');
+        const states = canonical.match(/TicketSpecStateSchema = z\.enum\(\[([^\]]+)\]/)?.[1].match(/'([^']+)'/g)?.map((value) => value.slice(1, -1));
+        expect(states).toEqual(TicketSpecStateSchema.options);
+    });
+    it.each([makeWorkStartHandler, makeWorkSessionStartHandler])('forwards a reasoned override and explains the server gate', async (factory) => {
+        const client = new OrbotoClient({ baseUrl: 'https://orboto.example.test', apiKey: 'test' });
+        vi.spyOn(client, 'get').mockResolvedValueOnce({ id: 'project', key: 'ORB' }).mockResolvedValueOnce({ id: 'ticket', projectId: 'project' });
+        const post = vi.spyOn(client, 'post').mockRejectedValue(new OrbotoApiError(409, JSON.stringify({ errorKey: 'errors.tickets.spec_not_ready', errorParams: { state: 'needs_spec' } }), 'test'));
+        const result = await factory(client)({ ticketKey: 'ORB-2098', override: true, reason: 'Approved recovery' });
+        expect(post.mock.calls[0][1]).toMatchObject({ ticketId: 'ticket', override: true, reason: 'Approved recovery' });
+        expect(result).toMatchObject({ isError: true, structuredContent: { specGate: true, errorKey: 'errors.tickets.spec_not_ready', errorParams: { state: 'needs_spec' } } });
+        expect(JSON.stringify(result.content)).toContain('release the specification');
+    });
+    it('stops a repeated sole claim at the gate before removing someone else', async () => {
+        const client = new OrbotoClient({ baseUrl: 'https://orboto.example.test', apiKey: 'test' });
+        vi.spyOn(client, 'get').mockResolvedValueOnce({ id: 'me' }).mockResolvedValueOnce({ id: 'project', key: 'ORB' }).mockResolvedValueOnce({ id: 'ticket', projectId: 'project', statusCategory: 'in_progress', assignees: [{ userId: 'me' }, { userId: 'other' }] });
+        vi.spyOn(client, 'post').mockRejectedValue(new OrbotoApiError(409, '{"errorKey":"errors.tickets.spec_not_ready"}', 'test'));
+        const remove = vi.spyOn(client, 'delete');
+        const patch = vi.spyOn(client, 'patch');
+        expect(await makeClaimHandler(client)({ ticketKey: 'ORB-2098', sole: true })).toMatchObject({ isError: true, structuredContent: { specGate: true } });
+        expect(remove).not.toHaveBeenCalled();
+        expect(patch).not.toHaveBeenCalled();
+    });
+    it.each([
+        ['errors.tickets.already_assigned', true],
+        ['errors.tickets.spec_not_ready', false],
+        ['errors.work_sessions.lease_held', false],
+    ])('only tolerates an already-assigned conflict: %s', async (errorKey, tolerated) => {
+        for (const kind of ['claim', 'assign']) {
+            const client = new OrbotoClient({ baseUrl: 'https://orboto.example.test', apiKey: 'test' });
+            const get = vi.spyOn(client, 'get');
+            if (kind === 'claim')
+                get.mockResolvedValueOnce({ id: 'me' });
+            get.mockResolvedValueOnce({ id: 'project', key: 'ORB' }).mockResolvedValueOnce({ id: 'ticket', projectId: 'project', statusCategory: 'in_progress', assignees: [{ userId: 'me' }] });
+            if (kind === 'assign')
+                get.mockResolvedValueOnce([{ userId: 'me', user: { id: 'me', email: 'me@spec.test' } }]);
+            const error = new OrbotoApiError(409, JSON.stringify({ errorKey }), 'test');
+            vi.spyOn(client, 'post').mockRejectedValue(error);
+            const result = kind === 'claim' ? makeClaimHandler(client)({ ticketKey: 'ORB-2098', noTimer: true }) : makeAssignHandler(client)({ ticketKey: 'ORB-2098', assigneeEmail: 'me@spec.test' });
+            if (tolerated)
+                expect(await result).not.toHaveProperty('isError', true);
+            else if (kind === 'claim' && errorKey === 'errors.tickets.spec_not_ready')
+                expect(await result).toHaveProperty('isError', true);
+            else
+                await expect(result).rejects.toBe(error);
+        }
+    });
+    it('exposes the settings, state and spec role and preserves unrelated conflict parsing', () => {
+        expect(z.object(workStartToolConfig.inputSchema).parse({ ticketKey: 'ORB-2098', role: 'spec' }).role).toBe('spec');
+        expect(z.object(updateTicketToolConfig.inputSchema).parse({ ticketKey: 'ORB-2098', patch: { specState: 'ready' } }).patch.specState).toBe('ready');
+        expect(z.object(updateProjectToolConfig.inputSchema).parse({ projectKey: 'ORB', patch: { spec: { enabled: true, requiredTypes: ['story'], releaseBy: 'author' } } }).patch.spec?.releaseBy).toBe('author');
+        expect(z.object(updateProjectToolConfig.inputSchema).parse({ projectKey: 'ORB', patch: { spec: { enabled: true } } }).patch.spec).toEqual({ enabled: true });
+        expect(specGateFailure('not json')).toBeUndefined();
+        expect(specGateFailure('{"errorKey":"errors.work_sessions.lease_held"}')).toBeUndefined();
+        expect(JSON.stringify(specGateFailure('{"errorKey":"errors.tickets.epic_not_claimable"}'))).toContain('child stories');
+    });
+});
+it('preserves release provenance without exposing the internal fingerprint', () => {
+    const ticket = { specReleasedBy: 'author', specReleasedByFullName: 'Alice', specReleasedAt: '2026-09-14T10:00:00Z', specReleasePolicy: 'author', specReleaseRole: 'author', specReleaseFingerprint: 'internal-proof' };
+    expect(specReleaseInfo(ticket)).toEqual({ specReleasedBy: 'author', specReleasedByFullName: 'Alice', specReleasedAt: '2026-09-14T10:00:00Z', specReleasePolicy: 'author', specReleaseRole: 'author' });
+});
+it('describes waiting tasks as parked sessions and preserves the question reference', async () => {
+    const client = new OrbotoClient({ baseUrl: 'https://orboto.example.test', apiKey: 'test' });
+    const row = { id: 'session', ticketId: 'ticket', ticketKey: 'ORB-2100', role: 'spec', status: 'finished', waitingForAnswers: true, taskId: 'task', waitingCommentId: 'question', leaseUntil: 'past' };
+    vi.spyOn(client, 'get').mockResolvedValue([row]);
+    const result = await makeWorkSessionsHandler(client)({});
+    expect(result.structuredContent).toEqual({ sessions: [row] });
+    expect(JSON.stringify(result.content)).toContain('waiting for answers; session finished; task task; question question');
+    expect(JSON.stringify(result.content)).not.toContain('lease until');
+});

package/dist/tools/spec-schemas.js

@@ -0,0 +1,34 @@
+import { z } from 'zod';
+export const TicketSpecStateSchema = z.enum(['none', 'needs_spec', 'in_spec', 'ready']);
+export const ProjectSpecSettingsSchema = z.object({
+    enabled: z.boolean().optional(),
+    requiredTypes: z.array(z.enum(['epic', 'story', 'task', 'bug'])).optional(),
+    releaseBy: z.enum(['agent', 'author']).optional(),
+}).strict();
+export function specGateFailure(body) {
+    let failure;
+    try {
+        failure = JSON.parse(body);
+    }
+    catch {
+        return undefined;
+    }
+    if (!failure || !['errors.tickets.spec_not_ready', 'errors.tickets.epic_not_claimable'].includes(failure.errorKey ?? ''))
+        return undefined;
+    return {
+        isError: true,
+        content: [{ type: 'text', text: failure.errorKey === 'errors.tickets.spec_not_ready'
+                    ? `Specification is ${failure.errorParams?.state ?? 'not ready'}. Complete and release the specification, or explicitly set override=true with a reason.`
+                    : 'Epics are task groups. Use the spec role to prepare child stories.' }],
+        structuredContent: { ...failure, specGate: true },
+    };
+}
+export function isAlreadyAssigned(body) {
+    try {
+        const error = JSON.parse(body);
+        return error?.errorKey === 'errors.tickets.already_assigned' || (!error?.errorKey && error?.error?.trim().toLowerCase() === 'already assigned');
+    }
+    catch {
+        return false;
+    }
+}

package/dist/tools/ticket-writes.js

@@ -1,3 +1,5 @@
+import { specReleaseInfo } from './shared.js';
+import { TicketSpecStateSchema, isAlreadyAssigned } from './spec-schemas.js';
 /**
  * ORB-244 Phase C Group 1 - ticket mutation tools.
  *
@@ -42,6 +44,8 @@ function ticketStructured(t) {
         statusCategory: t.statusCategory ?? null,
         type: t.type,
         priority: t.priority,
+        specState: t.specState ?? 'none',
+        ...specReleaseInfo(t),
         deliveryMode: t.deliveryMode ?? 'implementation',
         dueDate: t.dueDate,
         isPrivate: t.isPrivate,
@@ -55,14 +59,17 @@ export const createTicketToolConfig = {
         projectKey: z.string().min(1).describe('Project key (e.g. "ACME").'),
         title: z.string().min(1).max(255),
         description: z.string().optional(),
-        type: z.enum(['task', 'bug', 'story', 'epic']).optional().describe('Default: task.'),
-        priority: z.enum(['blocker', 'high', 'normal', 'low', 'trivial']).optional().describe('Default: normal.'),
-        deliveryMode: z.enum(['implementation', 'docs', 'review', 'admin', 'epic']).optional().describe('Default: epic when type=epic, else implementation.'),
+        type: z.enum(['task', 'bug', 'story', 'epic']).optional(),
+        priority: z.enum(['blocker', 'high', 'normal', 'low', 'trivial']).optional(),
+        override: z.boolean().optional(),
+        reason: z.string().trim().min(1).max(2000).optional(),
+        specState: TicketSpecStateSchema.optional(),
+        deliveryMode: z.enum(['implementation', 'docs', 'review', 'admin', 'epic']).optional(),
         milestone: z.string().optional().describe('Key ("ORB-M3"), name, or UUID.'),
         assigneeEmails: z.array(z.string().email()).optional().describe('Project-member emails.'),
-        labels: z.array(z.string()).optional().describe('Existing label names.'),
+        labels: z.array(z.string()).optional(),
         parentTicketKey: z.string().optional().describe('Parent key - makes this a sub-ticket.'),
-        dueDate: z.string().regex(/^\d{4}-\d{2}-\d{2}$/).optional().describe('YYYY-MM-DD.'),
+        dueDate: z.string().regex(/^\d{4}-\d{2}-\d{2}$/).optional(),
         isPrivate: z.boolean().optional(),
         allowLanguageMismatch: z.boolean().optional().describe('Override the language block.'),
         allowDuplicate: z.boolean().optional().describe('Override the duplicate block.'),
@@ -79,6 +86,9 @@ export function makeCreateTicketHandler(client) {
             type: input.type ?? 'task',
             priority: input.priority ?? 'normal',
             isPrivate: input.isPrivate ?? false,
+            ...(input.override !== undefined ? { override: input.override } : {}),
+            ...(input.reason ? { reason: input.reason } : {}),
+            ...(input.specState ? { specState: input.specState } : {}),
             ...(input.deliveryMode ? { deliveryMode: input.deliveryMode } : {}),
         };
         if (input.allowDuplicate && input.duplicateJustification)
@@ -236,22 +246,23 @@ function formatSimilarity(w) {
 }
 export const updateTicketToolConfig = {
     title: 'Update a ticket',
-    description: 'Patch one or more fields on a ticket. Patchable: title, description, customerSummary, type, priority, deliveryMode, dueDate, startDate, isPrivate, estimatedTimeMinutes. `customerSummary` is the customer-facing text shown in the customer project report instead of the internal description; null or empty falls back to an AI distillation or the title. `deliveryMode` is the role-aware commit policy (ORB-1608) - see `orboto_create_ticket` for the mode semantics. Use `orboto_move_ticket` for status, `orboto_set_milestone` for milestone, and `orboto_assign` / `orboto_unassign` for members.',
+    description: 'Patch one or more fields on a ticket. Patchable: title, description, customerSummary, type, priority, specState, deliveryMode, dueDate, startDate, isPrivate, estimatedTimeMinutes. `customerSummary` is the customer-facing text shown in the customer project report instead of the internal description; null or empty falls back to an AI distillation or the title. `deliveryMode` is the role-aware commit policy (ORB-1608) - see `orboto_create_ticket` for the mode semantics. Use `orboto_move_ticket` for status, `orboto_set_milestone` for milestone, and `orboto_assign` / `orboto_unassign` for members.',
     inputSchema: z.object({
         ticketKey: z.string().min(3),
         patch: z.object({
             title: z.string().min(1).max(255).optional(),
             description: z.string().optional(),
-            customerSummary: z.string().max(2000).nullable().optional().describe('Customer-facing report text; null falls back to AI/title.'),
+            customerSummary: z.string().max(2000).nullable().optional().describe('Report text; null uses AI/title.'),
             type: z.enum(['task', 'bug', 'story', 'epic']).optional(),
             priority: z.enum(['blocker', 'high', 'normal', 'low', 'trivial']).optional(),
-            deliveryMode: z.enum(['implementation', 'docs', 'review', 'admin', 'epic']).optional().describe('Commit policy; see orboto_create_ticket.'),
+            specState: TicketSpecStateSchema.optional(),
+            deliveryMode: z.enum(['implementation', 'docs', 'review', 'admin', 'epic']).optional(),
             dueDate: z.string().regex(/^\d{4}-\d{2}-\d{2}$/).nullable().optional(),
             startDate: z.string().regex(/^\d{4}-\d{2}-\d{2}$/).nullable().optional(),
             isPrivate: z.boolean().optional(),
             estimatedTimeMinutes: z.number().int().nonnegative().optional(),
         }).refine((p) => Object.keys(p).length > 0, { message: 'patch must include at least one field' }),
-        allowLanguageMismatch: z.boolean().optional().describe('Override the language block; only after a call was blocked.'),
+        allowLanguageMismatch: z.boolean().optional().describe('Retry a language block.'),
     }).shape,
     annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true },
 };
@@ -417,25 +428,19 @@ export const assignToolConfig = {
     inputSchema: z.object({
         ticketKey: z.string().min(3),
         assigneeEmail: z.string().email(),
+        override: z.boolean().optional(),
+        reason: z.string().trim().min(1).max(2000).optional(),
     }).shape,
     annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true },
 };
 export function makeAssignHandler(client) {
-    return async ({ ticketKey, assigneeEmail }) => {
+    return async ({ ticketKey, assigneeEmail, override, reason }) => {
         const ticket = await resolveTicketByKey(client, ticketKey);
         const userId = await resolveAssigneeId(client, ticket.projectId, assigneeEmail);
-        try {
-            await client.post(`/projects/${ticket.projectId}/tickets/${ticket.id}/assignees/${userId}`, {});
-        }
-        catch (err) {
-            if (err instanceof OrbotoApiError && err.status === 409) {
-                return {
-                    content: [{ type: 'text', text: `[${ticket.ticketKey}] already assigned to ${assigneeEmail}.` }],
-                    structuredContent: { ticketKey: ticket.ticketKey, alreadyAssigned: true },
-                };
-            }
-            throw err;
-        }
+        await client.post(`/projects/${ticket.projectId}/tickets/${ticket.id}/assignees/${userId}`, { override, reason }).catch((error) => {
+            if (!(error instanceof OrbotoApiError) || error.status !== 409 || !isAlreadyAssigned(error.body))
+                throw error;
+        });
         return {
             content: [{ type: 'text', text: `Assigned ${assigneeEmail} to [${ticket.ticketKey}].` }],
             structuredContent: { ticketKey: ticket.ticketKey, assignedEmail: assigneeEmail },

package/dist/tools/ticket-writes.test.js

@@ -27,7 +27,7 @@ function stub(responses) {
             status: r.status ?? 200,
             statusText: 'OK',
             json: async () => ('json' in r ? r.json : {}),
-            text: async () => '',
+            text: async () => r.json === undefined ? '' : JSON.stringify(r.json),
         };
     });
     return calls;
@@ -449,15 +449,14 @@ describe('orboto_assign / orboto_unassign', () => {
         expect(calls[3].method).toBe('POST');
         expect(calls[3].url).toContain('/assignees/u1');
     });
-    it('assign treats 409 as idempotent already-assigned', async () => {
+    it('assign tolerates legacy already-assigned responses', async () => {
         stub([
             { json: PROJ },
             { json: TICKET },
             { json: MEMBERS },
             { ok: false, status: 409, json: { error: 'already assigned' } },
         ]);
-        const res = await makeAssignHandler(client)({ ticketKey: 'ACME-1', assigneeEmail: 'ada@acme' });
-        expect(res.content[0].text).toContain('already assigned');
+        expect(await makeAssignHandler(client)({ ticketKey: 'ACME-1', assigneeEmail: 'ada@acme' })).toMatchObject({ structuredContent: { assignedEmail: 'ada@acme' } });
     });
     it('unassign treats 404 as idempotent already-unassigned', async () => {
         stub([

package/dist/tools/update-project.js

@@ -1,3 +1,5 @@
+import { ProjectReadinessSchema } from './project-readiness-schema.js';
+import { ProjectSpecSettingsSchema } from './spec-schemas.js';
 /**
  * ORB-885 - `orboto_update_project`.
  * ORB-830 - `orboto_create_project` + `orboto_archive_project`.
@@ -13,18 +15,19 @@ export const updateProjectToolConfig = {
     title: 'Update a project\'s metadata',
     description: 'Patch a project (`name`, `description`, `key`, `status`, `branchTemplate`, `customerId`, `language`). At least one field must be set. Use `status: "archived"` or `"closed"` to take a project out of active rotation. Renaming the `key` also rewrites every ticket\'s `PROJ-N` reference - handle with care. `language` sets the project\'s expected ticket language (one of the 18 supported locales); pass null to inherit the workspace language.',
     inputSchema: z.object({
-        projectKey: z.string().min(1).describe('Current project key (e.g. "ACME"). Case-insensitive.'),
+        projectKey: z.string().min(1).describe('Current project key.'),
         patch: z.object({
+            spec: ProjectSpecSettingsSchema.optional(),
             name: z.string().min(1).max(255).optional(),
-            description: z.string().nullable().optional().describe('Pass null to clear the description.'),
+            description: z.string().nullable().optional().describe('Null clears.'),
             key: z.string().min(2).max(10).regex(PROJECT_KEY_RE).optional()
-                .describe('New project key. A-Z0-9 only, 2-10 chars. Rewrites every ticket reference.'),
+                .describe('New key; rewrites ticket references.'),
             status: z.enum(['draft', 'active', 'archived', 'closed']).optional(),
             branchTemplate: z.string().max(100).nullable().optional(),
             customerId: z.string().regex(UUID_RE).nullable().optional()
-                .describe('UUID of a customer record, or null to detach.'),
+                .describe('Customer UUID; null detaches.'),
             language: z.enum(LOCALE_CODES).nullable().optional()
-                .describe('Project content language (ORB-994). Wins over the workspace language for this project. null = inherit workspace.'),
+                .describe('Content language; null inherits workspace.'),
         }).refine((p) => Object.keys(p).length > 0, { message: 'patch must include at least one field' }),
     }).shape,
     annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true },
@@ -46,22 +49,23 @@ export function makeUpdateProjectHandler(client) {
                 description: updated.description,
                 status: updated.status,
                 language: updated.language ?? null,
+                spec: updated.spec,
             },
         };
     };
 }
 export const createProjectToolConfig = {
     title: 'Create a new project',
-    description: 'Create a new project in the workspace. `name` is required; `key` is optional and the API auto-derives one from the name when omitted (uppercase initials). Returns the new project\'s id + key + status (`active` by default). Caller must have `admin:project:create` or be a super-admin. Note: a new project is auto-provisioned with a general doc space (slug `<key>-general`, system-generated, for the AI primer + notes) - don\'t create a separate doc space for its docs, reuse that one (orboto_list_doc_spaces).',
+    description: 'Create a project with an optional key (auto-derived if omitted). Requires project:create or super-admin. Returns identity, status and the measured readiness checklist with fix actions. Reuse its auto-created doc space via orboto_list_doc_spaces.',
     inputSchema: z.object({
-        name: z.string().min(1).max(255).describe('Display name for the project.'),
+        name: z.string().min(1).max(255).describe('Project name.'),
         key: z.string().min(2).max(10).regex(PROJECT_KEY_RE).optional()
-            .describe('Optional explicit key (e.g. "ACME"). A-Z0-9 only, 2-10 chars. Auto-derived from name when omitted.'),
-        description: z.string().nullable().optional().describe('Optional free-text description.'),
+            .describe('Key; auto-derived if omitted.'),
+        description: z.string().nullable().optional().describe('Description.'),
         customerId: z.string().regex(UUID_RE).nullable().optional()
-            .describe('Optional UUID of a customer record to attach the project to.'),
+            .describe('Customer UUID.'),
         language: z.enum(LOCALE_CODES).nullable().optional()
-            .describe('Optional project content language (ORB-994), one of the 18 supported locales. Omit/null = inherit the workspace language.'),
+            .describe('Content language; null/omitted inherits workspace.'),
     }).shape,
     annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false },
 };
@@ -77,12 +81,15 @@ export function makeCreateProjectHandler(client) {
         if (language !== undefined)
             body.language = language;
         const created = await client.post('/projects', body);
+        const parsed = ProjectReadinessSchema.safeParse(created.readiness);
+        const readiness = parsed.success ? parsed.data : undefined;
         return {
             content: [{
                     type: 'text',
-                    text: `Created project ${created.key} - ${created.name} (status: ${created.status}).`,
+                    text: `Created project ${created.key} - ${created.name} (status: ${created.status}).${readiness ? ` Setup: ${readiness.ready ? 'ready' : 'incomplete; inspect readiness items and fix actions'}.` : ''}`,
                 }],
             structuredContent: {
+                readiness,
                 id: created.id,
                 key: created.key,
                 name: created.name,

package/dist/tools/update-project.test.js

@@ -86,10 +86,19 @@ describe('orboto_update_project', () => {
         })).rejects.toThrow(/Project "GHOST" not found/);
     });
 });
+const readiness = { projectId: '11111111-2222-4333-8444-555555555555', projectKey: 'ACME', language: 'en', ready: false, ticketScope: 'visible', items: [] };
 describe('orboto_create_project', () => {
+    it.each([undefined, null, {}])('retains successful creation when readiness is absent or unsupported: %s', async (unsupported) => {
+        const calls = stub([{ json: { readiness: unsupported, id: 'older', key: 'OLD', name: 'Older API', status: 'active' } }]);
+        const result = await makeCreateProjectHandler(client)({ name: 'Older API' });
+        expect(result.structuredContent).toMatchObject({ id: 'older', key: 'OLD' });
+        expect(result.structuredContent?.readiness).toBeUndefined();
+        expect(result.content[0]).toMatchObject({ type: 'text', text: expect.stringContaining('Created project OLD') });
+        expect(calls).toHaveLength(1);
+    });
     it('POSTs name + key when both supplied', async () => {
         const calls = stub([
-            { json: { id: 'new1', key: 'ACME', name: 'Acme', description: null, status: 'active' } },
+            { json: { readiness, id: 'new1', key: 'ACME', name: 'Acme', description: null, status: 'active' } },
         ]);
         const res = await makeCreateProjectHandler(client)({ name: 'Acme', key: 'ACME' });
         expect(calls[0]).toMatchObject({
@@ -97,18 +106,18 @@ describe('orboto_create_project', () => {
             url: 'https://orboto.example.com/projects',
             body: { name: 'Acme', key: 'ACME' },
         });
-        expect(res.structuredContent).toMatchObject({ key: 'ACME', name: 'Acme', status: 'active' });
+        expect(res.structuredContent).toMatchObject({ key: 'ACME', name: 'Acme', status: 'active', readiness });
     });
     it('omits optional fields when not supplied so the API auto-derives the key', async () => {
         const calls = stub([
-            { json: { id: 'new2', key: 'NN', name: 'No Name', description: null, status: 'active' } },
+            { json: { readiness, id: 'new2', key: 'NN', name: 'No Name', description: null, status: 'active' } },
         ]);
         await makeCreateProjectHandler(client)({ name: 'No Name' });
         expect(calls[0].body).toEqual({ name: 'No Name' });
     });
     it('passes description + customerId through verbatim', async () => {
         const calls = stub([
-            { json: { id: 'new3', key: 'CUS', name: 'Custom', description: 'hello', status: 'active' } },
+            { json: { readiness, id: 'new3', key: 'CUS', name: 'Custom', description: 'hello', status: 'active' } },
         ]);
         await makeCreateProjectHandler(client)({
             name: 'Custom', description: 'hello', customerId: '11111111-2222-3333-4444-555555555555',

package/dist/tools/work-next.js

@@ -28,7 +28,7 @@ export const workNextToolConfig = {
         projectKey: z.string().min(1).describe('Project key (e.g. "ACME") or UUID.'),
         agentTag: z.string().min(1).max(64).optional()
             .describe('ORB-1772 - preferred-not-exclusive routing tag: tickets labeled `agent:<tag>` rank first for a matching caller, foreign `agent:*` tags rank last but stay eligible. Lowercased server-side. Set it to this worker\'s routing tag (often the model or fleet lane name).'),
-        role: z.enum(['implementation', 'review', 'preflight', 'integration']).optional()
+        role: z.enum(['implementation', 'review', 'preflight', 'integration', 'spec']).optional()
             .describe('Default `implementation`. The dispatcher only reserves a ticket whose (ticket, role) lease is free for THIS role.'),
         leaseSeconds: z.number().int().min(60).max(86_400).optional()
             .describe('How long the lease should hold without renewal. Default 900 (15 min).'),

package/dist/tools/work-sessions-next.test.js

@@ -88,6 +88,29 @@ describe('orboto_work_next', () => {
         stub([{ json: { ...peekResponse, ...patch } }]);
         await expect(makeWorkNextHandler(client)({ projectKey: 'ACME', peek: true })).rejects.toMatchObject({ reason: 'invalid_response' });
     });
+    it('preserves the spec bundle, queued ownership and landed work across pause and reservation', async () => {
+        const landedIdle = [{ ticketId: 'old', ticketKey: 'ACME-7', title: 'Already implemented', idleWorkingDays: 3, lastActivityAt: '2026-09-10', commitCount: 2 }];
+        const reserved = {
+            ...RESERVED, session: { ...SESSION, role: 'spec', activeTimerId: null },
+            ticket: { ...RESERVED.ticket, type: 'story', specState: 'in_spec' },
+            queued: [{ claim: { kind: 'path', value: 'src/**', mode: 'write' }, position: 2 }],
+            checklists: [{ title: 'Build order', triggersDone: true, progress: { done: 1, total: 2 }, items: [{ content: 'Reviewed requirement', effectiveCompleted: true, linkedTicketKey: 'ACME-8', linkedTicketStatusCategory: 'done' }, { content: 'Open question', effectiveCompleted: false }] }],
+            dependencies: { blockedBy: [{ ticketKey: 'ACME-9', title: 'Design', statusName: 'Done' }], blocks: [{ resolved: false }] },
+            gitHealth: [{ name: 'Repository', provider: 'forgejo', healthy: false, reason: 'missing_token' }],
+            siblingSessions: [{ ...SESSION, role: 'review', userEmail: 'reviewer@example.test' }],
+        };
+        const calls = stub([{ json: { reserved: null, reason: 'autonomy_paused', retryAfterSeconds: null, earliestFreeAt: null, candidatesConsidered: 0, landedIdle } }, { json: { reserved, reason: null, retryAfterSeconds: null, earliestFreeAt: null, candidatesConsidered: 1, landedIdle } }]);
+        const handler = makeWorkNextHandler(client);
+        const paused = await handler({ projectKey: 'ACME', role: 'spec' });
+        expect(JSON.stringify(paused.content)).toContain('PAUSED');
+        expect(paused.structuredContent).toMatchObject({ landedIdle, retryAfterSeconds: null });
+        const result = await handler({ projectKey: 'ACME', role: 'spec' });
+        expect(calls[1].body?.role).toBe('spec');
+        expect(result.structuredContent).toMatchObject({ reserved: { ticket: { specState: 'in_spec' }, queued: reserved.queued }, landedIdle });
+        const text = JSON.stringify(result.content);
+        for (const content of ['Build order', 'Open question', 'Repository', 'reviewer@example.test', 'Already implemented', 'position 2', 'No timer started'])
+            expect(text).toContain(content);
+    });
     it('reserves the winning candidate and renders the full bundle, sending projectKey straight through', async () => {
         const calls = stub([{ json: { reserved: RESERVED, reason: null, retryAfterSeconds: null, earliestFreeAt: null, candidatesConsidered: 3, landedIdle: [] } }]);
         const res = await makeWorkNextHandler(client)({ projectKey: 'ACME' });

package/dist/tools/work-sessions.js

@@ -1,3 +1,4 @@
+import { specGateFailure } from './spec-schemas.js';
 /**
  * ORB-1609 - work-session tools.
  */
@@ -28,17 +29,21 @@ function describeClaimConflicts(conflicts) {
 function describe(s) {
     const key = s.ticketKey ?? s.ticketId.slice(0, 8);
     const who = s.userFullName ?? s.userEmail ?? 'unknown';
+    if (s.waitingForAnswers)
+        return `  - ${key} [${s.role}] ${who} - waiting for answers; session ${s.status}; task ${s.taskId}; question ${s.waitingCommentId}`;
     return `  - ${key} [${s.role}] ${who} - lease until ${s.leaseUntil}${s.commitSha ? ` (commit ${s.commitSha.slice(0, 8)})` : ''}`;
 }
 export const workStartToolConfig = {
     title: 'Start a work session and load the full context bundle',
-    description: 'ORB-1611 - the one-call ticket pickup. Acquires the (ticket, role) work lease with the exact same guarantees as orboto_work_session_start (exactly ONE active session per ticket+role workspace-wide, a conflict names the holder, resourceClaims apply atomically with the lease), AND in the SAME response returns the rules-hash ack (same semantics as orboto_session_start), the project primer, the ticket enriched with its description/status/priority, its checklists, its dependencies, that project\'s git connection health, and any other live sessions already on the ticket. This replaces the 8-15 separate calls (orboto_session_start, orboto_get_project_primer, orboto_get_ticket, orboto_get_checklists, orboto_list_ticket_dependencies, ...) a normal ticket pickup used to cost. Prefer this over orboto_work_session_start for picking up a ticket; use the plain tool only when you deliberately do not want the bundle (e.g. a mid-task lease renewal where you already have fresh context). A conflict never leaves a partial session behind - same rollback-on-conflict guarantee as orboto_work_session_start.',
+    description: 'Claim a ticket lease with its rules and work context. Includes the primer, enriched ticket, checklists, dependencies, git health and live sessions. Exactly one active lease per ticket and role across the workspace. Resource claims are atomic with the lease; conflicts name the holder and leave no partial session. Prefer this for pickup; use orboto_work_session_start for renewal when context is already loaded. Spec-tagged bots may use role=spec to prepare the build order. Worker bots need a ready specification, or override=true with a reason; enabled epics cannot be overridden.',
     inputSchema: z.object({
         ticketKey: z.string().min(3).describe('Ticket key like "ACME-42".'),
-        role: z.enum(['implementation', 'review', 'preflight', 'integration']).optional()
-            .describe('Default `implementation`. Use `review` for a review pass, `preflight` for a pre-work check, `integration` for merge/release work - those attach without reassigning the ticket.'),
+        role: z.enum(['implementation', 'review', 'preflight', 'integration', 'spec']).optional()
+            .describe('Default implementation; other roles attach without reassignment. Spec prepares build orders; bots need the spec tag.'),
         leaseSeconds: z.number().int().min(60).max(86_400).optional()
             .describe('How long the lease should hold without renewal. Default 900 (15 min).'),
+        override: z.boolean().optional().describe("Bypass the spec gate; reason required. Never epics."),
+        reason: z.string().trim().min(1).max(2000).optional(),
         takeover: z.boolean().optional()
             .describe('Displace the current holder of this (ticket, role) lease. Their session is cancelled and their tracked time booked.'),
         startTimer: z.boolean().optional()
@@ -69,6 +74,8 @@ export function makeWorkStartHandler(client) {
                 ticketId,
                 ...(args.role ? { role: args.role } : {}),
                 ...(args.leaseSeconds ? { leaseSeconds: args.leaseSeconds } : {}),
+                ...(args.override !== undefined ? { override: args.override } : {}),
+                ...(args.reason ? { reason: args.reason } : {}),
                 ...(args.takeover ? { takeover: true } : {}),
                 ...(args.startTimer !== undefined ? { startTimer: args.startTimer } : {}),
                 ...(args.resourceClaims && args.resourceClaims.length > 0 ? { resourceClaims: args.resourceClaims } : {}),
@@ -153,6 +160,9 @@ export function makeWorkStartHandler(client) {
         }
         catch (err) {
             if (err instanceof OrbotoApiError && err.status === 409) {
+                const specFailure = specGateFailure(err.body);
+                if (specFailure)
+                    return specFailure;
                 const claimConflicts = parseClaimConflicts(err);
                 if (claimConflicts && claimConflicts.length > 0) {
                     return {
@@ -192,13 +202,15 @@ export function makeWorkStartHandler(client) {
 }
 export const workSessionStartToolConfig = {
     title: 'Start (or renew) a work session on a ticket',
-    description: 'Take the work lease on a ticket in a given role and start its timer. This is the coordination primitive: exactly ONE active session per (ticket, role) exists workspace-wide, so a second agent attempting the same role gets a conflict naming the current holder instead of silently colliding. Re-calling with the same agent instance renews your own lease and is a no-op otherwise - safe to call defensively. Roles other than `implementation` (review / preflight / integration) attach to the ticket WITHOUT reassigning it or moving its status, so a reviewing agent no longer has to fake a claim. The lease expires on its own (default 15 min, renewed automatically by your subsequent calls), so a crashed agent never wedges a ticket. Pass `takeover: true` only when you have decided to displace the current holder - their session is closed and their time booked, and the takeover is visible in history.',
+    description: 'Take the work lease on a ticket in a given role and start its timer. This is the coordination primitive: exactly ONE active session per (ticket, role) exists workspace-wide, so a second agent attempting the same role gets a conflict naming the current holder instead of silently colliding. Re-calling with the same agent instance renews your own lease and is a no-op otherwise - safe to call defensively. Roles other than `implementation` (review / preflight / integration / spec) attach to the ticket WITHOUT reassigning it or moving its status, so a reviewing agent no longer has to fake a claim. The lease expires on its own (default 15 min, renewed automatically by your subsequent calls), so a crashed agent never wedges a ticket. Pass `takeover: true` only when you have decided to displace the current holder - their session is closed and their time booked, and the takeover is visible in history.',
     inputSchema: z.object({
         ticketKey: z.string().min(3).describe('Ticket key like "ACME-42".'),
-        role: z.enum(['implementation', 'review', 'preflight', 'integration']).optional()
-            .describe('Default `implementation`. Use `review` for a review pass, `preflight` for a pre-work check, `integration` for merge/release work - those attach without reassigning the ticket.'),
+        role: z.enum(['implementation', 'review', 'preflight', 'integration', 'spec']).optional()
+            .describe('Default implementation; other roles attach without reassignment. Spec prepares build orders; bots need the spec tag.'),
         leaseSeconds: z.number().int().min(60).max(86_400).optional()
             .describe('How long the lease should hold without renewal. Default 900 (15 min).'),
+        override: z.boolean().optional().describe("Bypass the spec gate; reason required. Never epics."),
+        reason: z.string().trim().min(1).max(2000).optional(),
         takeover: z.boolean().optional()
             .describe('Displace the current holder of this (ticket, role) lease. Their session is cancelled and their tracked time booked.'),
         startTimer: z.boolean().optional()
@@ -206,9 +218,9 @@ export const workSessionStartToolConfig = {
         agentSessionToken: z.string().optional()
             .describe('Stable per-agent-instance token. Omit to use this MCP connection\'s own instance id.'),
         resourceClaims: z.array(z.object(ResourceClaimShape)).max(50).optional()
-            .describe('ORB-1610 - resource claims to acquire alongside the lease. `kind: "path"` takes a glob relative to the repo root (`src/**`, `apps/api/src/routes/tickets.ts`); `kind: "named"` takes an opaque exclusive-resource id (`unity-editor:main`, `git-push:orboto#develop`), compared by exact string equality. `mode: "write"` conflicts with any OVERLAPPING active write claim workspace-wide (across tickets and accounts) - editor refresh clobbering uncommitted changes and concurrent pushes staging each other\'s files are exactly what this prevents. `mode: "read"` never conflicts with anything, including another read.'),
+            .describe('Atomic resource claims: path values are repo-relative globs, named values are exact ids. Overlapping writes conflict across the workspace; reads never conflict.'),
         onConflict: z.enum(['reject', 'queue']).optional()
-            .describe('Only matters when `resourceClaims` is set. Default `reject`: a conflicting write claim fails the WHOLE call with the conflicting holder(s) named - if this call would have created a brand-new session, that session is rolled back rather than left holding the lease without its claims. `queue`: the conflicting claim is accepted as `state: "waiting"` instead of failing; it is promoted automatically once the conflict clears (release, finish, or the next orboto_work_sessions read).'),
+            .describe('reject rolls back a new session on claim conflict; queue keeps it with waiting claims, promoted when conflicts clear.'),
     }).shape,
     annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true },
 };
@@ -221,6 +233,8 @@ export function makeWorkSessionStartHandler(client) {
                 ticketId: ticket.id,
                 ...(args.role ? { role: args.role } : {}),
                 ...(args.leaseSeconds ? { leaseSeconds: args.leaseSeconds } : {}),
+                ...(args.override !== undefined ? { override: args.override } : {}),
+                ...(args.reason ? { reason: args.reason } : {}),
                 ...(args.takeover ? { takeover: true } : {}),
                 ...(args.startTimer !== undefined ? { startTimer: args.startTimer } : {}),
                 ...(args.resourceClaims && args.resourceClaims.length > 0 ? { resourceClaims: args.resourceClaims } : {}),
@@ -248,6 +262,9 @@ export function makeWorkSessionStartHandler(client) {
         }
         catch (err) {
             if (err instanceof OrbotoApiError && err.status === 409) {
+                const specFailure = specGateFailure(err.body);
+                if (specFailure)
+                    return specFailure;
                 const claimConflicts = parseClaimConflicts(err);
                 if (claimConflicts && claimConflicts.length > 0) {
                     return {
@@ -294,6 +311,8 @@ export const workSessionFinishToolConfig = {
             .describe('`finished` (default) = the work completed. `cancelled` = abandoned attempt; time is still booked, history stays honest.'),
         commitSha: z.string().optional().describe('The commit this session produced, when it produced one.'),
         verification: z.object({
+            reviewOfSessionId: z.string().uuid().optional().describe('Exact independent implementation work session this review examined.'),
+            reviewVerdict: z.enum(['approved', 'rework']).optional().describe('Explicit review outcome, paired with reviewOfSessionId; never inferred from later ticket status.'),
             build: z.boolean().optional(),
             tests: z.boolean().optional(),
             lint: z.boolean().optional(),
@@ -327,6 +346,8 @@ export const workFinishToolConfig = {
             .describe('`finished` (default) drives the ticket transition below. `cancelled` = abandoned attempt; time is still booked, the ticket is left untouched.'),
         commitSha: z.string().optional().describe('The commit this session produced. Recorded as an attestation immediately, verified asynchronously once git ingestion catches up - never blocks this call.'),
         verification: z.object({
+            reviewOfSessionId: z.string().uuid().optional().describe('Exact independent implementation work session this review examined.'),
+            reviewVerdict: z.enum(['approved', 'rework']).optional().describe('Explicit review outcome, paired with reviewOfSessionId; never inferred from later ticket status.'),
             build: z.boolean().optional(),
             tests: z.boolean().optional(),
             lint: z.boolean().optional(),
@@ -377,7 +398,7 @@ export function makeWorkFinishHandler(client) {
 }
 export const workSessionsToolConfig = {
     title: 'List live work sessions (who is working on what)',
-    description: 'The coordination view: every live work lease you can see, or the sessions on one ticket. Call this BEFORE picking up work in a fleet - a ticket with a live `implementation` lease is already being worked, and starting on it anyway is how two agents produce conflicting commits. Unlike agent presence (which reports who is online), this reports who OWNS what, across accounts.',
+    description: 'Visible work leases and specification tasks waiting for ticket replies. Check before picking up work. An active implementation lease owns the ticket; a finished session with waitingForAnswers is parked, not a live lease. Includes task and question ids across accounts.',
     inputSchema: z.object({
         ticketKey: z.string().optional().describe('Scope to one ticket. Omit to list every live session you can see.'),
         scope: z.enum(['mine', 'all']).optional().describe('`mine` = only my own sessions. Default `all`. Ignored when ticketKey is set.'),

package/dist/tools/work-sessions.test.js

@@ -351,3 +351,17 @@ describe('ORB-1610 - orboto_work_session_claims_release', () => {
         expect(res.content[0].text).toContain('Released every claim');
     });
 });
+describe('review evidence binding', () => {
+    it('forwards the explicit implementation reference and verdict through both finish surfaces', async () => {
+        const verification = { reviewOfSessionId: '11111111-1111-4111-8111-111111111111', reviewVerdict: 'rework', tests: false };
+        const calls = stub([
+            { json: { session: { ...SESSION, status: 'finished' }, durationMinutes: 0, changed: true } },
+            { json: { session: { ...SESSION, status: 'finished' }, durationMinutes: 0, changed: true } },
+        ]);
+        await makeWorkSessionFinishHandler(client)({ sessionId: SESSION.id, verification });
+        await makeWorkFinishHandler(client)({ sessionId: SESSION.id, verification });
+        expect(calls).toHaveLength(2);
+        for (const call of calls)
+            expect(call.body?.verification).toEqual(verification);
+    });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@orboto/mcp",
-  "version": "0.195.1",
+  "version": "0.197.0",
   "description": "Model Context Protocol server for orboto - exposes tickets, projects, milestones, time, docs, primer-facts, alerts and absences as MCP tools for Claude Desktop / Cursor / Copilot Chat / any MCP-aware AI client.",
   "license": "MIT",
   "type": "module",