@orboto/mcp 0.193.0 → 0.194.1

package/dist/tools/phase-b-tools.test.js

@@ -31,9 +31,6 @@ function stub(responses) {
             ok: r.ok ?? true,
             status: r.status ?? 200,
             statusText: 'OK',
-            // `'json' in r` so an explicit `json: null` preserves null;
-            // `r.json ?? {}` would collapse null → {} and hide nullable
-            // endpoints (e.g. GET /time/timer returns the row or null).
             json: async () => ('json' in r ? r.json : {}),
             text: async () => '',
         };
@@ -48,7 +45,6 @@ describe('orboto_get_project', () => {
             { json: PROJ },
             { json: [{ id: 'm1', name: 'v1', status: 'active', startDate: '2026-01-01', endDate: '2026-03-01' }] },
             { json: [{ id: 'l1', name: 'bug', color: '#f00' }] },
-            // Members endpoint response: nested user + role objects per the real schema.
             { json: [{ userId: 'u1', projectId: 'p1', roleId: 'r1',
                         user: { id: 'u1', email: 'ada@acme', fullName: 'Ada', avatarUrl: null },
                         role: { id: 'r1', name: 'developer' } }] },
@@ -75,8 +71,19 @@ describe('orboto_list_tickets', () => {
         expect(calls[1]).toContain('statusCategory=in_progress');
         expect(calls[1]).toContain('limit=10');
     });
-    // ORB-1696 - the shared resolver contract: key, name, OR UUID; an
-    // ambiguous name errors listing candidates. One test per form.
+    it('passes unscheduled=true for the backlog', async () => {
+        const calls = stub([
+            { json: PROJ },
+            { json: { items: [], nextCursor: null } },
+        ]);
+        await makeListTicketsHandler(client)({ projectKey: 'ACME', unscheduled: true, statusCategory: 'todo' });
+        expect(calls[1]).toContain('unscheduled=true');
+        expect(calls[1]).toContain('statusCategory=todo');
+    });
+    it('refuses unscheduled together with milestone', async () => {
+        stub([{ json: PROJ }]);
+        await expect(makeListTicketsHandler(client)({ projectKey: 'ACME', unscheduled: true, milestone: 'ACME-M1' })).rejects.toThrow(/not both/);
+    });
     it('resolves milestone KEY (ORB-1696)', async () => {
         const calls = stub([
             { json: PROJ },
@@ -133,7 +140,6 @@ describe('orboto_list_tickets', () => {
         ]);
         await expect(makeListTicketsHandler(client)({ projectKey: 'ACME', milestone: 'ghost' })).rejects.toThrow(/Milestone "ghost" not found/);
     });
-    // ORB-1605 - the stalled-ingestion signal passes through into structuredContent.
     it('surfaces waitingForGitIngestion per ticket', async () => {
         stub([
             { json: PROJ },
@@ -157,8 +163,6 @@ describe('orboto_list_tickets', () => {
     });
 });
 describe('orboto_get_ticket', () => {
-    // Fixture: empty children page (children METADATA is always fetched; the
-    // rows only surface with include: ["children"] since ORB-1698).
     const NO_CHILDREN = { json: { items: [], nextCursor: null } };
     it('ORB-1698 default card: only enriched + children + attachments are fetched - comments/checklists/git untouched', async () => {
         const calls = stub([
@@ -174,7 +178,6 @@ describe('orboto_get_ticket', () => {
         expect(calls.some((c) => c.includes('/checklists'))).toBe(false);
         expect(calls.some((c) => c.includes('/git-activity'))).toBe(false);
         const sc = res.structuredContent;
-        // Counts always present; bodies absent by default - never silently.
         expect(sc.commentCount).toBe(3);
         expect(sc.checklistProgress).toEqual({ done: 1, total: 2 });
         expect(sc.attachmentCount).toBe(0);
@@ -230,8 +233,6 @@ describe('orboto_get_ticket', () => {
         expect(sc.commentsHasMore).toBe(true);
         expect(sc.parentTicket).toBeNull();
     });
-    // ORB-1605 - the stalled-ingestion signal surfaces in both the header
-    // text and structuredContent.
     it('surfaces waitingForGitIngestion in the header and structured content', async () => {
         stub([
             { json: PROJ },
@@ -279,9 +280,7 @@ describe('orboto_get_ticket', () => {
         stub([
             { json: PROJ },
             { json: { id: 't5', projectId: 'p1', ticketKey: 'ACME-5', title: 'Phase A', status: 'DONE', statusName: 'Done', statusCategory: 'done', type: 'task', priority: 'normal', gitActivityCount: 0, parentTicketId: 't1' } },
-            // Enriched by-id refetch
             { json: { id: 't5', projectId: 'p1', ticketKey: 'ACME-5', title: 'Phase A', status: 'DONE', statusName: 'Done', statusCategory: 'done', type: 'task', priority: 'normal' } },
-            // Parent ticket fetch
             { json: { id: 't1', projectId: 'p1', ticketKey: 'ACME-1', title: 'Epic foo', status: 'IN_PROGRESS', statusName: 'In Progress', statusCategory: 'in_progress' } },
             NO_CHILDREN,
             { json: [] },
@@ -316,10 +315,7 @@ describe('orboto_get_ticket', () => {
     it('ORB-1023: surfaces milestone (name, not UUID) + statusCategory from the enriched by-id refetch', async () => {
         stub([
             { json: PROJ },
-            // Bare by-key resolver row: milestoneId set, but no milestoneName /
-            // statusCategory - this is the shape that dropped the milestone.
             { json: { id: 't1', projectId: 'p1', ticketKey: 'ACME-9', title: 'Bug', status: 'DONE', milestoneId: 'm1', gitActivityCount: 0, parentTicketId: null } },
-            // Enriched by-id refetch: carries statusCategory + the resolved name.
             { json: { id: 't1', projectId: 'p1', ticketKey: 'ACME-9', title: 'Bug', status: 'DONE', statusName: 'Done', statusCategory: 'done', type: 'bug', priority: 'normal', milestoneId: 'm1', milestoneName: 'Sprint 7' } },
             NO_CHILDREN,
             { json: [] },
@@ -408,7 +404,6 @@ describe('milestone tools', () => {
             { json: { total: 12, byStatus: { TODO: 12 } } },
         ]);
         const res = await makeGetMilestoneHandler(client)({ projectKey: 'ACME', milestone: 'acme-m19' });
-        // The resolver spans closed milestones too.
         expect(calls[1]).toContain('includeClosed=true');
         const sc = res.structuredContent;
         expect(sc.milestone.name).toBe('Phase 35');
@@ -478,7 +473,6 @@ describe('orboto_get_checklists', () => {
                         id: 'cl1', title: 'Before ship', triggersDone: true,
                         progress: { done: 1, total: 2 },
                         items: [
-                            // One plain item, one linked-to-another-ticket item.
                             { id: 'i1', content: 'Docs updated', storedCompleted: true, effectiveCompleted: true,
                                 linkedTicketId: null, linkedTicketKey: null, linkedTicketTitle: null, linkedTicketStatusCategory: null, sortOrder: 0 },
                             { id: 'i2', content: 'Sub-task done', storedCompleted: false, effectiveCompleted: false,
@@ -517,11 +511,10 @@ describe('orboto_get_timer', () => {
         expect(res.structuredContent).toEqual({ timer: null });
     });
     it('computes totalSeconds including elapsed time since startedAt', async () => {
-        const startedAt = new Date(Date.now() - 120_000).toISOString(); // 2 min ago
+        const startedAt = new Date(Date.now() - 120_000).toISOString();
         stub([{ json: { id: 'tm1', userId: 'u1', ticketId: 't1', ticketTitle: 'Bug', startedAt, pausedAt: null, accumulatedSeconds: 300, description: 'debug' } }]);
         const res = await makeGetTimerHandler(client)();
         const sc = res.structuredContent;
-        // 300 accumulated + ~120 elapsed. Allow ±5s for test timing jitter.
         expect(sc.timer.totalSeconds).toBeGreaterThanOrEqual(418);
         expect(sc.timer.totalSeconds).toBeLessThanOrEqual(425);
         expect(sc.timer.paused).toBe(false);

package/dist/tools/primer-facts.js

@@ -1,33 +1,12 @@
 /**
  * ORB-510 / ORB-513 - primer-fact tools.
  *
- * Six tools that wrap the `/projects/:id/primer-facts` and
- * `/primer-facts/:id` REST surface from ORB-511. Agents call these to
- * record structured project facts - tech-stack details, conventions,
- * deployment quirks - that the AI primer (ORB-512) renders at the top
- * of every session. The skill rule (ORB-514) tells agents *when* to
- * record; these tools are the *how*.
- *
- * All tool descriptions and parameter `.describe()` strings are in
- * English so the international LLM tool-selection path is reliable.
- *
- * Wire order in server.ts:
- *   - orboto_primer_fact_list
- *   - orboto_primer_fact_add
- *   - orboto_primer_fact_update
- *   - orboto_primer_fact_supersede
- *   - orboto_primer_fact_verify
- *   - orboto_primer_fact_delete
+ * @see ORB-511, ORB-512, ORB-514
  */
 import { z } from 'zod';
 import { OrbotoApiError } from '../orboto-client.js';
 import { resolveProjectByKey, sizeBlockResult } from './shared.js';
-// ORB-1819 - the writing contract, verbatim in every write-tool
-// description so the writing agent sees it at the moment of writing.
 const FACT_WRITING_CONTRACT = ' Fact: <= 300 chars, one fact per key, the value is the fact - long material goes into a doc, the fact holds the doc key.';
-// ---------------------------------------------------------------------------
-// Shared types + helpers
-// ---------------------------------------------------------------------------
 const PRIMER_FACT_CATEGORIES = [
     'tech_stack',
     'conventions',
@@ -36,11 +15,7 @@ const PRIMER_FACT_CATEGORIES = [
     'integrations',
     'gotchas',
     'commands',
-    // ORB-1403 - explicit non-functional requirements (performance, security,
-    // DSGVO, operations, i18n, ...) for the Pflichtenheft NFR chapter.
     'non_functional',
-    // ORB-1413 - glossary/terminology facts for the Pflichtenheft glossary
-    // chapter (chapter 11) only, so they no longer double-render via `other`.
     'glossary',
     'other',
 ];
@@ -70,17 +45,12 @@ function summariseFact(f) {
     if (f.supersededById)
         markers.push('superseded');
     const tag = markers.length > 0 ? ` _(${markers.join(', ')})_` : '';
-    // Single-line preview of the value - multi-line bodies get truncated
-    // so the list output stays scannable.
     const valuePreview = f.value.length > 120 || f.value.includes('\n')
         ? `${f.value.replace(/\n/g, ' ').slice(0, 120)}…`
         : f.value;
     const scope = f.projectId === null ? '[workspace]' : '[project]';
     return `- ${scope} **${f.category}/${f.key}**: ${valuePreview}${tag}`;
 }
-// ---------------------------------------------------------------------------
-// orboto_primer_fact_list
-// ---------------------------------------------------------------------------
 export const primerFactListToolConfig = {
     title: 'List structured project primer facts',
     description: 'List structured project facts that feed the AI primer (tech stack, conventions, deployment, architecture, integrations, gotchas, commands). Use this to discover what the project has already documented before adding a new observation. Workspace-wide facts (applying to every project) are merged in by default; pass includeWorkspace=false to see only project-scoped rows.',
@@ -127,9 +97,6 @@ export function makePrimerFactListHandler(client) {
         };
     };
 }
-// ---------------------------------------------------------------------------
-// orboto_primer_fact_add
-// ---------------------------------------------------------------------------
 export const primerFactAddToolConfig = {
     title: 'Record a new project primer fact',
     description: 'Record a new structured fact about the project that future AI agents should see at session start. Use when you learn something during work that is missing from the primer (a library version, a convention, a deployment quirk, an architecture decision). Note: the auto-generated primer does NOT automatically include CLAUDE.md / AGENTS.md content unless the operator configured repo briefings and the API host can read those files from disk - most deployments cannot. Treat key conventions documented in CLAUDE.md / AGENTS.md as fair game to record here so they survive cross-deployment. Set observed=true when you are recording from a bot/agent context - the fact will land as agent_observed and require operator verification before losing the (observed) marker.'
@@ -182,9 +149,6 @@ export function makePrimerFactAddHandler(client) {
         };
     };
 }
-// ---------------------------------------------------------------------------
-// orboto_primer_fact_update
-// ---------------------------------------------------------------------------
 export const primerFactUpdateToolConfig = {
     title: 'Update an existing primer fact',
     description: 'Update an existing fact. Use this when the value has changed (e.g. version bumped) or you are renaming the key. Bumps last_verified_at automatically when the value changes; pure renames leave it untouched. To replace a fact while preserving history, use orboto_primer_fact_supersede instead.'
@@ -240,9 +204,6 @@ export function makePrimerFactUpdateHandler(client) {
         };
     };
 }
-// ---------------------------------------------------------------------------
-// orboto_primer_fact_supersede
-// ---------------------------------------------------------------------------
 export const primerFactSupersedeToolConfig = {
     title: 'Replace a primer fact while preserving history',
     description: 'Replace a fact with a corrected version, preserving the old one in history (linked via superseded_by_id). Use when you discover a previously recorded fact was wrong; do not just delete it. The old row gets a tombstoned key suffix so the partial unique index does not collide; the new row starts unverified and needs operator verification before losing the (observed) marker.'
@@ -284,9 +245,6 @@ export function makePrimerFactSupersedeHandler(client) {
         };
     };
 }
-// ---------------------------------------------------------------------------
-// orboto_primer_fact_verify
-// ---------------------------------------------------------------------------
 export const primerFactVerifyToolConfig = {
     title: 'Verify an agent-observed primer fact',
     description: 'Promote an agent-observed fact to verified. Operator-only action; bots without project:edit cannot self-verify. Removes the (observed) marker from the rendered primer and stamps verifiedBy / verifiedAt.',
@@ -314,9 +272,6 @@ export function makePrimerFactVerifyHandler(client) {
         };
     };
 }
-// ---------------------------------------------------------------------------
-// orboto_primer_fact_delete
-// ---------------------------------------------------------------------------
 export const primerFactDeleteToolConfig = {
     title: 'Delete a primer fact',
     description: 'Hard-delete a fact. Prefer orboto_primer_fact_supersede when the fact is being replaced; only delete when the fact was wrong from the start or no longer relevant. Writes an audit-log entry; the row itself is gone (no soft-delete).',
@@ -328,9 +283,6 @@ export const primerFactDeleteToolConfig = {
 };
 export function makePrimerFactDeleteHandler(client) {
     return async ({ factId, reason }) => {
-        // ORB-516 - pass the reason through so the audit-log entry
-        // captures it. Old API versions silently ignore the querystring
-        // so there's no compat risk.
         const path = reason
             ? `/primer-facts/${factId}?reason=${encodeURIComponent(reason)}`
             : `/primer-facts/${factId}`;

package/dist/tools/primer-facts.test.js

@@ -50,9 +50,6 @@ const factStub = {
     createdAt: '2026-04-30T10:00:00Z',
     updatedAt: '2026-04-30T10:00:00Z',
 };
-// ---------------------------------------------------------------------------
-// orboto_primer_fact_list
-// ---------------------------------------------------------------------------
 describe('orboto_primer_fact_list', () => {
     it('resolves projectKey then GETs /projects/<id>/primer-facts with filters', async () => {
         const calls = stub([
@@ -118,9 +115,6 @@ describe('orboto_primer_fact_list', () => {
         expect(result.success).toBe(false);
     });
 });
-// ---------------------------------------------------------------------------
-// orboto_primer_fact_add
-// ---------------------------------------------------------------------------
 describe('orboto_primer_fact_add', () => {
     it('observed=false (default) sends source=manual', async () => {
         const calls = stub([
@@ -189,9 +183,6 @@ describe('orboto_primer_fact_add', () => {
         expect(result.success).toBe(false);
     });
 });
-// ---------------------------------------------------------------------------
-// orboto_primer_fact_update
-// ---------------------------------------------------------------------------
 describe('orboto_primer_fact_update', () => {
     it('PATCHes /primer-facts/<id> with only the provided fields', async () => {
         const calls = stub([{ json: { ...factStub, value: 'pnpm 10' } }]);
@@ -211,9 +202,6 @@ describe('orboto_primer_fact_update', () => {
         await expect(makePrimerFactUpdateHandler(client)({ factId: 'missing', value: 'v' })).rejects.toThrow(/not found/);
     });
 });
-// ---------------------------------------------------------------------------
-// orboto_primer_fact_supersede
-// ---------------------------------------------------------------------------
 describe('orboto_primer_fact_supersede', () => {
     it('POSTs /primer-facts/<id>/supersede with category + key + value', async () => {
         const calls = stub([{ json: { ...factStub, id: 'new-uuid', value: 'pnpm 10' } }]);
@@ -237,9 +225,6 @@ describe('orboto_primer_fact_supersede', () => {
         expect(schema.safeParse({ oldFactId: 'x' }).success).toBe(false);
     });
 });
-// ---------------------------------------------------------------------------
-// orboto_primer_fact_verify
-// ---------------------------------------------------------------------------
 describe('orboto_primer_fact_verify', () => {
     it('POSTs /primer-facts/<id>/verify with empty body', async () => {
         const calls = stub([{ json: { ...factStub, verified: true, verifiedBy: 'u1', verifiedAt: 'now' } }]);
@@ -249,9 +234,6 @@ describe('orboto_primer_fact_verify', () => {
         expect(calls[0].body).toEqual({});
     });
 });
-// ---------------------------------------------------------------------------
-// orboto_primer_fact_delete
-// ---------------------------------------------------------------------------
 describe('orboto_primer_fact_delete', () => {
     it('DELETEs /primer-facts/<id>', async () => {
         const calls = stub([{ status: 204 }]);
@@ -275,8 +257,6 @@ describe('orboto_primer_fact_delete', () => {
         await expect(makePrimerFactDeleteHandler(client)({ factId: 'missing' })).rejects.toThrow(/not found/);
     });
 });
-// ORB-1819 - the writing-for-tokens size contract, passed through from the
-// REST route's warn (200/201 + sizeWarning) / block (422) responses.
 describe('ORB-1819 size contract', () => {
     it('add surfaces a soft-limit sizeWarning in the success text, not as an error', async () => {
         stub([

package/dist/tools/project-listings.js

@@ -1,26 +1,8 @@
 /**
  * ORB-799 - per-project metadata listings.
- *
- * Two cheap read tools that round-trip the project-scoped enum tables
- * agents repeatedly need:
- *
- * - orboto_list_ticket_statuses - the workflow's status rows with
- *     their IDs, categories, colors, and terminal flag. Needed for
- *     typed-transition flows where the standard `move_ticket` (which
- *     picks the first status per category) isn't precise enough.
- *
- * - orboto_list_labels - the per-project label catalogue with
- *     colors. Lets agents see what labels exist before calling
- *     `create_ticket` with a `labels` array (unknown names error).
- *
- * Both mirror the wrapper's `statuses <project>` / `labels <project>`
- * subcommands.
  */
 import { z } from 'zod';
 import { resolveProjectByKey } from './shared.js';
-// ---------------------------------------------------------------------------
-// orboto_list_ticket_statuses
-// ---------------------------------------------------------------------------
 export const listTicketStatusesToolConfig = {
     title: 'List a project\'s ticket statuses',
     description: 'Return the project\'s workflow rows - `{id, name, category, color, sortOrder, isTerminal}`. The `category` is the broad bucket (todo / in_progress / in_review / done / wont_fix); `name` is the workspace\'s display label (e.g. "Code Review"). Use the `id` to do typed transitions through `orboto_update_ticket` when the standard category-based move is too coarse.',
@@ -52,9 +34,6 @@ export function makeListTicketStatusesHandler(client) {
         };
     };
 }
-// ---------------------------------------------------------------------------
-// orboto_list_labels
-// ---------------------------------------------------------------------------
 export const listLabelsToolConfig = {
     title: 'List a project\'s labels',
     description: 'Return the project\'s label catalogue - `{id, name, color}`. Labels must be referenced by exact name when assigning via `orboto_create_ticket` (the API errors on unknown names rather than auto-creating); use this tool to discover what\'s available before assigning.',
@@ -79,9 +58,6 @@ export function makeListLabelsHandler(client) {
         };
     };
 }
-// ---------------------------------------------------------------------------
-// orboto_create_label - ORB-1041
-// ---------------------------------------------------------------------------
 export const createLabelToolConfig = {
     title: 'Create a project label',
     description: 'Create a label in a project so it can be assigned to tickets. Closes the gap where `orboto_create_ticket` errors on an unknown label name (labels are not auto-created). Idempotent: if a label with the same name already exists, it is returned instead of erroring. Needs project:edit.',
@@ -95,7 +71,6 @@ export const createLabelToolConfig = {
 export function makeCreateLabelHandler(client) {
     return async ({ projectKey, name, color }) => {
         const project = await resolveProjectByKey(client, projectKey);
-        // Idempotent: return an existing same-name label rather than erroring.
         const existing = await client.get(`/projects/${project.id}/labels`);
         const match = existing.find((l) => l.name.toLowerCase() === name.toLowerCase());
         if (match) {

package/dist/tools/query.js

@@ -1,17 +1,7 @@
 /**
  * ORB-273 Phase F - `orboto_query`.
  *
- * Lets the model reach for the OQL DSL when the per-entity list
- * tools (`orboto_list_tickets`, `orboto_my_tickets`) get too narrow:
- * combined `assignee + dueDate + label + statusCategory` filters
- * with explicit ORDER BY are awkward to express through tool
- * arguments but trivial in OQL. Falls back to JQL syntax via
- * `syntax: 'jql'` for migrants who copy-pasted a Jira query.
- *
- * The endpoint is `POST /query` (ORB-531) which honours PBAC,
- * cursor-paginates, and rate-limits at 60/min. We expose the
- * underlying envelope unchanged so a future "give me the next page"
- * tool can plumb the cursor through.
+ * @see ORB-531
  */
 import { z } from 'zod';
 import { ticketLine, agentTicketListRow } from './shared.js';
@@ -57,7 +47,6 @@ export function makeQueryHandler(client) {
             structuredContent: {
                 count: page.items.length,
                 nextCursor: page.nextCursor,
-                // ORB-1699 - shared lean row; verbose restores uuid/labels/minutes.
                 tickets: page.items.map((t) => agentTicketListRow(t, input.verbose ?? false)),
             },
         };

package/dist/tools/query.test.js

@@ -47,8 +47,6 @@ describe('tools/query', () => {
             body: JSON.stringify({ oql: 'project = ORB', syntax: 'oql', cursor: undefined, limit: 25 }),
         }));
         expect(result.content[0]).toMatchObject({ type: 'text', text: expect.stringContaining('ORB-1') });
-        // ORB-1699 - the default row is the shared lean projection: no uuid,
-        // no labels, no minutes; assignee NAMES (fullName || email).
         expect(result.structuredContent).toMatchObject({
             count: 1,
             nextCursor: null,
@@ -88,10 +86,6 @@ describe('tools/query', () => {
         }));
     });
 });
-// ORB-1699 - the ONE row builder, asserted from one place: the lean shape
-// omits uuid/timestamps/minutes; verbose restores them. list_tickets,
-// my_tickets and query all consume agentTicketListRow, so this single
-// test pins the row for all three.
 import { agentTicketListRow } from './shared.js';
 describe('agentTicketListRow (ORB-1699)', () => {
     const FULL = {
@@ -104,8 +98,6 @@ describe('agentTicketListRow (ORB-1699)', () => {
     };
     it('lean row: decision fields only, defaults omitted', () => {
         const row = agentTicketListRow(FULL);
-        // priority 'high' and dueDate present -> included; type stays only
-        // when it deviates from 'task'; status NAME is verbose-only.
         expect(Object.keys(row).sort()).toEqual(['assigneeNames', 'dueDate', 'key', 'priority', 'statusCategory', 'title']);
         expect(row.assigneeNames).toEqual(['Ada']);
     });

package/dist/tools/raci.js

@@ -17,9 +17,6 @@ async function resolveMemberId(client, projectId, email) {
         throw new Error(`No project member with email "${email}".`);
     return m.userId;
 }
-// ---------------------------------------------------------------------------
-// orboto_raci - read the matrix
-// ---------------------------------------------------------------------------
 export const raciToolConfig = {
     title: 'RACI matrix',
     description: "Read a project's RACI matrix (tickets x members, cells = R/A/C/I). `milestone` scopes to one milestone; `epicsOnly` narrows rows to epics. RACI is OPT-IN per project: only use this when the project has RACI enabled (check `raciEnabled` on orboto_get_project / the primer). Do NOT raise or suggest RACI on projects that haven't enabled it. Returns empty when RACI is off.",
@@ -35,8 +32,6 @@ export function makeRaciHandler(client) {
         const project = await resolveProjectByKey(client, input.projectKey);
         const qs = new URLSearchParams();
         if (input.milestone) {
-            // ORB-1696 - shared resolver: key (ORB-M3), name or UUID, ambiguous
-            // name -> explicit error. Matches create_ticket/set_milestone/OQL.
             const m = await resolveMilestoneByNameOrId(client, project.id, input.milestone);
             qs.set('milestoneId', m.id);
         }
@@ -49,7 +44,6 @@ export function makeRaciHandler(client) {
                 structuredContent: { raciEnabled: false, projectKey: project.key, members: [], rows: [] },
             };
         }
-        // Compact text rendering: one line per ticket listing each held role.
         const lines = data.rows.map((r) => {
             const byUser = new Map(data.members.map((m) => [m.userId, m.fullName]));
             const held = Object.entries(r.cells)
@@ -64,9 +58,6 @@ export function makeRaciHandler(client) {
         };
     };
 }
-// ---------------------------------------------------------------------------
-// orboto_set_raci - write a role
-// ---------------------------------------------------------------------------
 export const setRaciToolConfig = {
     title: 'Set a RACI role',
     description: "Set a person's RACI role on a ticket: R (Responsible), A (Accountable, max one per ticket), C (Consulted), or I (Informed). RACI is OPT-IN per project: only use this when the project has RACI enabled (`raciEnabled` true) - do NOT suggest or set RACI on projects that haven't opted in. Resolves the user by email within the ticket's project. Requires ticket:manage_raci. A second Accountable is rejected with the current holder's name.",
@@ -86,8 +77,6 @@ export function makeSetRaciHandler(client) {
         }
         catch (err) {
             if (err instanceof OrbotoApiError && err.status === 409) {
-                // Single-A violation or RACI-not-enabled - surface the clean message
-                // the API put in the response body.
                 let msg = err.body;
                 try {
                     msg = JSON.parse(err.body).error ?? err.body;

package/dist/tools/requirements-spec.js

@@ -1,18 +1,7 @@
 /**
  * ORB-1409 (epic ORB-1390) - `orboto_requirements_spec`.
  *
- * Generates the requirements specification (Pflichtenheft) as Markdown:
- * numbered functional requirements (FA-1, FA-1.1...) each traceable to its
- * ticket and tagged muss/soll/kann from priority, plus non-functional
- * requirements distilled from primer facts. `outlineVariant` picks the chapter
- * naming/order: `neutral` (default), `industry` (VDI-3694 style), or `software`
- * (IEEE-830 style). Private tickets/milestones are always excluded server-side.
- * Wraps `POST /projects/:id/requirements-spec/generate` with `format: 'markdown'`.
- * Money price mode needs budget:view on top of requirements_spec:generate (the
- * API returns 403 otherwise).
- *
- * The route existed since ORB-1391; ORB-1409 fills in the missing MCP + skill
- * surfaces (the Pflichtenheft feature shipped route + chat only).
+ * @see ORB-1391
  */
 import { z } from 'zod';
 import { OrbotoApiError } from '../orboto-client.js';

package/dist/tools/response-expand.js

@@ -1,20 +1,6 @@
 /**
  * ORB-1697 - `orboto_response_expand`: the way back from a truncated
  * response.
- *
- * The central response budget (`../response-budget.ts`) caps what a
- * single tool result may inject into the session, because a result is
- * re-sent on every later request and therefore costs its size times the
- * turns that follow it. A cap is only acceptable if nothing is lost, so
- * every truncated response carries a handle, and this tool serves the
- * omitted remainder from the in-process store in budget-sized chunks.
- *
- * Deliberately NOT a REST call: the handle addresses the payload the
- * ORIGINAL call already produced, so expanding cannot return anything
- * the caller was not already authorised to see, and it costs no
- * additional API round-trip. The store is per-process and short-lived
- * (15 min, 16 payloads) - an expired handle is answered with "re-run the
- * original tool", never with a wrong or stale chunk.
  */
 import { z } from 'zod';
 import { budgetFor, readPayload, resolvePath, } from '../response-budget.js';
@@ -48,8 +34,6 @@ export function makeResponseExpandHandler() {
         if (!stored)
             return expired(input.handle);
         const omitted = stored.omitted ?? [];
-        // No path - list what can be expanded. Cheap by construction: paths
-        // and counts only, never the content itself.
         if (!input.path) {
             const lines = [
                 `# Truncated content available for handle "${input.handle}"`,
@@ -77,9 +61,6 @@ export function makeResponseExpandHandler() {
             return { isError: true, content: [{ type: 'text', text }] };
         }
         const full = typeof raw === 'string' ? raw : JSON.stringify(raw, null, 1) ?? '';
-        // Leave room for the framing lines so a chunk plus its header still
-        // fits this tool's own budget - a continuation tool that gets
-        // truncated itself would be a loop, not a fix.
         const chunkSize = Math.max(500, budgetFor('orboto_response_expand') - 800);
         const cursor = Math.min(input.cursor ?? 0, full.length);
         const chunk = full.slice(cursor, cursor + chunkSize);

package/dist/tools/review-policy.js

@@ -1,26 +1,8 @@
 /**
  * ORB-1615 - structural review policy tools.
- *
- *   - orboto_review_fingerprint     - hash exact raw diff text into a
- *                                     canonical fingerprint (+ real size
- *                                     metrics), server-side (one algorithm,
- *                                     not one per client).
- *   - orboto_review_policy_check    - the consult-before-invoking-a-model
- *     call: what risk level does this ticket carry, and (if a fingerprint
- *     is supplied) is there already a valid approval for THIS exact diff.
- *   - orboto_review_approval_record - record an approve/reject decision
- *     against a ticket's diff fingerprint.
- *
- * Rule CONFIGURATION (path pattern / deliveryMode / size -> risk level)
- * stays out of the MCP surface, same call as approval_policies' CRUD in
- * tools/approvals.ts: it's project-settings admin config, not something an
- * autonomous agent tool should expose.
  */
 import { z } from 'zod';
 import { resolveTicketByKey } from './shared.js';
-// ---------------------------------------------------------------------------
-// orboto_review_fingerprint
-// ---------------------------------------------------------------------------
 export const reviewFingerprintToolConfig = {
     title: 'Compute a canonical diff fingerprint',
     description: 'Hash the exact submitted diff text server-side with sha256-diff-v2. Every text change, including indentation, blank lines, binary blob identities, mode/rename metadata and file order, changes the fingerprint. This is submitted-text identity, NOT independent repository attestation. Returns size/path metrics too. Preserve the complete opaque version-prefixed `fingerprint` for `orboto_review_policy_check` and `orboto_review_approval_record`; legacy v1 approvals remain history only and must be reviewed again.',
@@ -41,9 +23,6 @@ export function makeReviewFingerprintHandler(client) {
         };
     };
 }
-// ---------------------------------------------------------------------------
-// orboto_review_policy_check
-// ---------------------------------------------------------------------------
 export const reviewPolicyCheckToolConfig = {
     title: 'Check a ticket\'s review policy before invoking a reviewer',
     description: 'Consult a ticket\'s structural review policy BEFORE spawning a review session or invoking a model. Called with no diff context (the common case, right after picking up a ticket) it resolves the per-ticket override or a deliveryMode-only rule; passing `paths`/`linesChanged` (from `orboto_review_fingerprint`) additionally matches path/size-scoped rules and, if `fingerprint` is passed too, checks whether a VALID approval already covers this exact diff - so a low-risk ticket, or one already reviewed at this fingerprint, can close without spawning a reviewer. `riskLevel: "required"` with `source: "fail_safe"` means the policy engine itself errored - treat that as "review required", never as "no review needed".',
@@ -71,9 +50,6 @@ export function makeReviewPolicyCheckHandler(client) {
         };
     };
 }
-// ---------------------------------------------------------------------------
-// orboto_review_approval_record
-// ---------------------------------------------------------------------------
 export const reviewApprovalRecordToolConfig = {
     title: 'Record a review decision against a diff fingerprint',
     description: 'Record your review verdict (approve/reject) against the complete version-prefixed fingerprint from orboto_review_fingerprint. A current-algorithm approval is reusable only for identical submitted diff text; even whitespace or file-order changes require a fresh review. Legacy/unversioned records remain history only. This advisory review ledger does not itself enforce ticket closure. Requires ticket:record_review_approval.',

package/dist/tools/review-policy.test.js

@@ -66,8 +66,6 @@ describe('orboto_review_approval_record', () => {
         const res = await makeReviewApprovalRecordHandler(client)({ ticketKey: 'ACME-1', fingerprint: FINGERPRINT, decision: 'approved', note: 'looks good' });
         const record = calls.find((c) => c.method === 'POST' && c.url.includes('review-approvals'));
         expect(record?.body).toMatchObject({ fingerprint: FINGERPRINT, decision: 'approved', note: 'looks good' });
-        // ticketKey must NOT leak into the request body sent to the API - the
-        // route resolves the ticket from the URL, not the payload.
         expect(record?.body).not.toHaveProperty('ticketKey');
         expect(res.content[0].text).toContain('approved');
     });

package/dist/tools/search.js

@@ -1,17 +1,7 @@
 /**
  * ORB-244 Phase B - `orboto_search`.
  *
- * Unified full-text search across tickets, comments, and docs. Maps
- * to the existing `/search` route (Phase 21 global search) which
- * already respects PBAC visibility (private tickets, internal
- * comments, doc ACL).
- *
- * ORB-272: /search is cursor-paginated. Response shape is
- * `{items, nextCursor, total}`. We surface `total` so the model
- * knows how many hits exist globally, but don't expose `cursor` on
- * the tool input - repeat MCP tool calls to walk a search cursor is
- * an awkward UX. Users who need to see more narrow the query or
- * open the full-page /search in the web UI.
+ * @see ORB-272
  */
 import { z } from 'zod';
 import { resolveProjectByKey } from './shared.js';
@@ -49,8 +39,6 @@ export function makeSearchHandler(client) {
             ? `No hits for "${input.query}".`
             : `Hits${headerHint}${relaxedNote}:\n\n` + res.items.map((h) => {
                 const tag = h.type.toUpperCase();
-                // ORB-1084 - non-ticket hits carry the FULL id: the truncated
-                // form was unusable as input for the doc write tools.
                 const ident = h.ticketKey ?? h.id;
                 const project = h.projectName ? ` · ${h.projectName}` : '';
                 return `- [${tag} ${ident}${project}] ${h.title}\n  ${h.excerpt}`;