engineering-memory 1.11.9 → 1.11.10

package/runtime/dist/src/mcp/tool-definitions.js

@@ -1,7 +1,7 @@
 import * as z from 'zod/v4';
 import { validationIds } from '../runtime/bridge-service.js';
 import { hostAnswerSchema, questionnaireDefinitionSchema } from '../runtime/questionnaire-store.js';
-import { answerQuestionnaireFromHost, askQuestionnaire, resumeQuestionnaire, } from './questionnaire-tools.js';
+import { answerChoice, answerQuestionnaireFromHost, askQuestionnaire, resumeQuestionnaire, } from './questionnaire-tools.js';
 const optionalRepoRoot = z.string().min(1).optional();
 const stringList = z.array(z.string().min(1));
 const jsonValue = z.lazy(() => z.union([
@@ -149,7 +149,10 @@ const reconciliationEntry = z.object({
     resourceId: z.string().min(1),
     type: z.enum(['approved_revision', 'no_semantic_memory_change', 'scaffold_applied']),
     proposalId: z.string().optional(),
-    revisionId: z.string().optional(),
+    revisionId: z
+        .string()
+        .optional()
+        .describe('Optional for approved_revision; resolved from the approved proposal when omitted.'),
     reason: z.string().optional(),
 });
 export function registerQuestionnaireTools(server, service) {
@@ -191,10 +194,11 @@ export function registerQuestionnaireTools(server, service) {
         }
     });
     server.registerTool('questionnaire.ask', {
-        description: 'Persist a required decision before displaying a native questionnaire. Write the message and labels in the conversation language and set language (tr or en) for the native form help. Use a questionnaireId unique to this decision occurrence or task, and reuse it only for identical retries. A later decision or changed wording/options requires a new id. Only a schema-validated native acceptance answers it. Dismissal, timeout and missing replies remain pending without expiry. Never supply answers in questionnaire.ask arguments; use questionnaire.answer_from_host only after an actual permitted blocking native answer. Do not put personal information or secrets in the question or options. Free text is returned once and never stored; use explicit options for replayable decisions.',
+        description: 'Persist a required decision before displaying a native questionnaire. Write the message and labels in the conversation language and set language (tr or en) for the native form help. Use a questionnaireId unique to this decision occurrence or task, and reuse it only for identical retries. A later decision or changed wording/options requires a new id. Only a schema-validated native acceptance answers it. Dismissal, timeout and missing replies remain pending without expiry. Never supply answers in questionnaire.ask arguments; use questionnaire.answer_from_host only after an actual permitted blocking native answer. Do not put personal information or secrets in the question or options. Free text is returned once and never stored; use explicit options for replayable decisions. After the first decline in this session, pass presentation host_native to skip the doomed elicitation round trip.',
         inputSchema: questionnaireDefinitionSchema.extend({
             repoRoot: optionalRepoRoot,
             preparation: z.boolean().optional(),
+            presentation: z.literal('host_native').optional(),
         }),
     }, async (input, context) => await askQuestionnaire(server, service, input, context));
     server.registerTool('questionnaire.resume', {
@@ -259,14 +263,32 @@ export function registerEngineeringMemoryTools(server, service) {
         }),
     }, async (input) => toolResult(await service.sessionAnswerShadowNotice(input)));
     server.registerTool('session.bootstrap', {
-        description: 'Authenticate, resolve the repository project, open or resume a write or read-only task, and load mandatory engineering context before planning.',
+        description: 'Authenticate, resolve the repository project, open or resume a write or read-only task, and load mandatory engineering context before planning. objective is one line of at most 240 characters. contextPack holds only what fit the response budget; deferredResources lists what did not, each entry carrying its revisionId so it can be read directly with memory.read_revisions rather than looked up again through memory.catalog.',
         inputSchema: z.object({
             repoRoot: optionalRepoRoot,
             projectId: z.string().optional(),
-            externalTaskId: z.string().min(2),
-            objective: z.string().min(2),
-            taskKind: z.string().min(2),
-            workItemKey: z.string().min(1).optional(),
+            externalTaskId: z
+                .string()
+                .min(2)
+                .max(160)
+                .regex(/^[^\r\n]+$/, 'externalTaskId must be a single line of at most 160 characters.'),
+            objective: z
+                .string()
+                .min(2)
+                .max(240)
+                .regex(/^[^\r\n]+$/, 'objective must be a single line of at most 240 characters.')
+                .describe('One line, 2-240 characters: what this task delivers. Put detail in checkpoints, not here.'),
+            taskKind: z
+                .string()
+                .min(2)
+                .max(80)
+                .regex(/^[^\r\n]+$/, 'taskKind must be a single line of at most 80 characters.'),
+            workItemKey: z
+                .string()
+                .min(2)
+                .max(120)
+                .regex(/^[^\r\n]+$/, 'workItemKey must be a single line of at most 120 characters.')
+                .optional(),
             workItemId: z.string().uuid().optional(),
             mode: z.enum(['write', 'read_only', 'scaffold']).optional(),
             linkedSources: z
@@ -300,14 +322,14 @@ export function registerEngineeringMemoryTools(server, service) {
         }),
     }, async (input) => toolResult(await service.contextPrepareChange(input)));
     server.registerTool('context.refresh', {
-        description: 'Refresh pins within the task fixed code source after memory approval. Use the task repoRoot; source changes require a new task.',
+        description: 'Refresh pins within the task fixed code source after memory approval. Use the task repoRoot; source changes require a new task. contextPack carries only the revisions that changed since the session pinned them; unchangedResources lists the rest with the revisionId to reread one through memory.read_revisions, and deferredResources entries carry theirs too.',
         inputSchema: z.object({
             repoRoot: optionalRepoRoot,
             sessionId: z.string().min(1),
         }),
     }, async (input) => toolResult(await service.contextRefresh(input)));
     server.registerTool('memory.query', {
-        description: 'Read the smallest project memory pack needed for screens, components, services, navigation, localization or state work.',
+        description: 'Read the smallest project memory pack needed for screens, components, services, navigation, localization or state work. resources holds what fits one response; deferredResources lists the rest, each with the revisionId to read it through memory.read_revisions.',
         inputSchema: z.object({
             projectId: z.string().min(1),
             sessionId: z.string().min(1),
@@ -319,17 +341,19 @@ export function registerEngineeringMemoryTools(server, service) {
         }),
     }, async (input) => toolResult(await service.memoryQuery(input)));
     server.registerTool('memory.history', {
-        description: 'Read why the code you are about to change is the way it is: the revision history of the screen, component or contract records covering the given paths or keys, each revision with the task that produced it and the stated reason, plus the earlier tasks that touched those records and how many corrections each of them took. Also returns the task references found in the Git history of those paths. Verification refuses while a record with earlier work on it was never read.',
+        description: 'Read why the code you are about to change is the way it is: the revision history of the screen, component or contract records covering the given paths, keys or ids, each revision with the task that produced it and the stated reason, plus the earlier tasks that touched those records and how many corrections each of them took. Also returns the task references found in the Git history of those paths. Verification refuses while a record with earlier work on it was never read; required:true reads every such record of the current lease in one call. A path no record covers comes back in uncoveredPaths instead of an error.',
         inputSchema: z.object({
             repoRoot: optionalRepoRoot,
             sessionId: z.string().min(1),
             resourceKeys: z.array(z.string().min(1)).optional(),
+            resourceIds: z.array(z.string().uuid()).max(50).optional(),
             paths: z.array(z.string().min(1)).optional(),
+            required: z.boolean().optional(),
             depth: z.number().int().min(1).max(50).optional(),
         }),
     }, async (input) => toolResult(await service.memoryHistory(input)));
     server.registerTool('memory.propose_revision', {
-        description: 'Create an inactive, reviewable proposal for permanent product, organization or project memory. Do not block independent task work on drafting, submission or approval. Use authorized host background agents or concurrent tools and continue useful work; collect the result only before an operation needs its proposal or revision ID. Without concurrency, checkpoint the pending draft and defer this call until needed. Keep one writer per resource and preserve baseRevision and task/source identity. A response distinguishes stored (queued:false) from outbox-queued; neither means approved. Native user approval and task verification remain required.',
+        description: "Create an inactive, reviewable proposal for permanent product, organization or project memory. Do not block independent task work on drafting, submission or approval. Use authorized host background agents or concurrent tools and continue useful work; collect the result only before an operation needs its proposal or revision ID. Without concurrency, checkpoint the pending draft and defer this call until needed. Keep one writer per resource and preserve baseRevision and task/source identity. A response distinguishes stored (queued:false) from outbox-queued; neither means approved. A stored proposal reports reviewableByCaller: ask this user to approve it only when that is true; otherwise report it as submitted, with its id, to the reviewPath it names (product_release, organization_owner or project_maintainer). Task verification remains required. metadata carries only the structured fields the resource kind defines, such as a project profile's pathRoles, architecture and resourceDiscovery, appliesToStacks, or an architecture template's manifest; classification, containsPii, containsSecrets and resourceDescriptor are computed by the server and ignored when sent, so metadata copied from a served revision is accepted. A project profile's metadata.architecture, when present, is exactly {adopted: [{structure, pressure}], declined: [{structure, why}]} (structure up to 80 characters, pressure/why up to 600, at most 40 entries each) and no other key; a free-text style such as 'MVVM' is not that shape and goes in metadata.architectureStyle (a plain string) or the profile content instead.",
         inputSchema: z.object({
             repoRoot: optionalRepoRoot,
             sourceRunId: z.string().uuid().optional(),
@@ -374,10 +398,15 @@ export function registerEngineeringMemoryTools(server, service) {
         }),
     }, async (input) => toolResult(await service.memoryProposeRevision(input)));
     server.registerTool('memory.list_proposals', {
-        description: 'List the permanent memory proposals still waiting for review, so an authorized reviewer can find them without database access. Pass proposalId to read one proposal with its proposed content.',
+        description: "List the permanent memory proposals still waiting for review, so an authorized reviewer can find them without database access. Each entry carries a reasonPreview, not the full reason; pass proposalId to read one proposal in full, with its reason and proposed content. Narrow a long list with taskId, scope or status (defaults to pending); page through the rest with limit (default 50, max 100) and afterId, set to the response's nextAfterId to continue, which is null once nothing more is waiting. Each proposal reports reviewableByCaller; when it is false, the caller cannot approve it, so never ask this user for approval: report it as waiting on the reviewPath it names.",
         inputSchema: z.object({
             projectId: z.string().min(1),
             proposalId: z.string().min(1).optional(),
+            taskId: z.string().min(1).optional(),
+            scope: z.enum(['project', 'organization', 'product']).optional(),
+            status: z.enum(['pending', 'approved', 'rejected', 'superseded']).optional(),
+            afterId: z.string().min(1).optional(),
+            limit: z.number().int().min(1).max(100).optional(),
         }),
     }, async (input) => toolResult(await service.memoryListProposals(input)));
     server.registerTool('memory.review_proposal', {
@@ -415,21 +444,55 @@ export function registerEngineeringMemoryTools(server, service) {
         }),
     }, async (input) => toolResult(await service.taskRecordCorrection(input)));
     server.registerTool('task.self_review', {
-        description: 'Record that the changed code was read back against the rules that govern it, naming the knowledge resources reviewed and every conflict found with how it was resolved. Returns a durable pending receipt without waiting for backend delivery; continue independent local validation. task.verify waits for required delivery and refuses until this exists for the current diff, so any further edit requires reviewing again.',
+        description: 'Record that each changed file was read back against the rules that govern it: one entry per changed file (deleted files excepted), naming every rule context.prepare_change returned for that path in governingRules, and for a file no role maps, the engineering rules you read it against. Each rule gets an outcome: follows; fixed, with the issue and the change you made; or user_accepted_deviation, with the rule resourceKey and the issue. A rule conflict is a question for the user, never a judgment call: for every deviation this tool asks the user natively whether to keep the code, records the deviation only on their approval, and refuses the review when they choose to change the code. Matching the surrounding code is not an outcome; existing code is evidence, not authority. Set language to the conversation language (tr or en) for the question. Returns a durable pending receipt without waiting for backend delivery; task.verify refuses until a review covers the current diff, so any further edit requires reviewing again.',
         inputSchema: z.object({
             repoRoot: optionalRepoRoot,
             taskId: z.string().min(1),
-            reviewedResourceIds: z.array(z.string().min(1)),
-            findings: z.array(z.object({
-                path: z.string().min(1),
-                rule: z.string().min(1),
-                issue: z.string().min(8),
-                resolution: z.string().min(8),
-            })),
+            language: z.enum(['tr', 'en']).optional(),
+            files: z
+                .array(z.object({
+                path: z.string().min(1).max(512),
+                rules: z
+                    .array(z.discriminatedUnion('outcome', [
+                    z.object({
+                        resourceId: z.string().uuid(),
+                        outcome: z.literal('follows'),
+                    }),
+                    z.object({
+                        resourceId: z.string().uuid(),
+                        outcome: z.literal('fixed'),
+                        issue: z.string().min(8).max(2000),
+                        change: z.string().min(8).max(2000),
+                    }),
+                    z.object({
+                        resourceId: z.string().uuid(),
+                        outcome: z.literal('user_accepted_deviation'),
+                        resourceKey: z.string().min(1).max(240),
+                        issue: z.string().min(8).max(1000),
+                    }),
+                ]))
+                    .min(1)
+                    .max(50),
+            }))
+                .max(500),
         }),
-    }, async (input) => toolResult(await service.taskSelfReview(input)));
+    }, async (input, context) => {
+        let questions;
+        try {
+            questions = service.ruleDeviationQuestions(input);
+        }
+        catch {
+            return toolResult(await service.taskSelfReview(input));
+        }
+        for (const { definition, previousDefinitions } of questions) {
+            const form = await askQuestionnaire(server, service, { ...definition, repoRoot: input.repoRoot }, context, previousDefinitions);
+            if (!answerChoice(form))
+                return form;
+        }
+        return toolResult(await service.taskSelfReview(input));
+    });
     server.registerTool('task.reconcile', {
-        description: 'Reconcile changed screens and components with an approved revision or an explicit no-semantic-memory-change reason. Pass every record the task touched as `entries` in one call rather than calling once per record; the whole set is applied together and rejected together. A pending result is a durable local receipt; continue independent work without polling. Required delivery is checked before verification.',
+        description: 'Reconcile changed screens and components with an approved revision or an explicit no-semantic-memory-change reason. Pass every record the task touched as `entries` in one call rather than calling once per record; the whole set is applied together and rejected together. After memory.review_proposal approves a proposal, pass its reconcileEntry ({resourceId, type: approved_revision, proposalId, revisionId}) straight through here — revisionId is optional and is resolved from the approved proposal when omitted. A pending result is a durable local receipt; continue independent work without polling. Required delivery is checked before verification.',
         inputSchema: z
             .object({
             repoRoot: optionalRepoRoot,
@@ -464,10 +527,10 @@ export function registerEngineeringMemoryTools(server, service) {
                 return;
             }
             for (const entry of entries) {
-                if (entry.type === 'approved_revision' && (!entry.proposalId || !entry.revisionId)) {
+                if (entry.type === 'approved_revision' && !entry.proposalId) {
                     context.addIssue({
                         code: 'custom',
-                        message: 'Approved reconciliation requires proposalId and revisionId',
+                        message: 'Approved reconciliation requires proposalId',
                     });
                 }
                 if (entry.type === 'no_semantic_memory_change' &&
@@ -498,11 +561,15 @@ export function registerEngineeringMemoryTools(server, service) {
         }),
     }, async (input) => toolResult(await service.taskResolvePendingDelivery(input)));
     server.registerTool('task.verify', {
-        description: 'Verify a write task with its lease or a read-only task against its pinned Git baseline, mandatory checkpoints, structured validations and synchronized outbox.',
+        description: 'Verify a write task with its lease or a read-only task against its pinned Git baseline, mandatory checkpoints, structured validations and synchronized outbox. A refusal lists every unmet requirement at once. If the user decides a required check is not needed for this task, pass it in waivers; the tool asks them natively and records the answer.',
         inputSchema: z.object({
             repoRoot: optionalRepoRoot,
             taskId: z.string().min(1),
             sessionId: z.string().min(1),
+            language: z
+                .enum(['tr', 'en'])
+                .optional()
+                .describe('Language of the current conversation, for the waiver question.'),
             leaseId: z.string().min(1).optional(),
             changedPaths: stringList.min(1).optional(),
             validations: z
@@ -525,8 +592,61 @@ export function registerEngineeringMemoryTools(server, service) {
                 .max(20)
                 .optional()
                 .describe('Architectural structures this task adds that the project did not have: a cache, a broker, a read replica, a second deployable, a projection, an event store. Verification refuses any the project profile has not recorded under architecture.adopted with the pressure it relieves.'),
-        }),
-    }, async (input) => toolResult(await service.taskVerify(input)));
+            waivers: z
+                .array(z.object({
+                validationId: z.enum(['ui']),
+                reason: z.string().min(10).max(500),
+            }))
+                .max(3)
+                .optional()
+                .describe('Only when the user decides a required ui check is not needed for this change. Never inferred from prose; the tool asks the user and verifies only after they agree.'),
+        }),
+    }, async (input, context) => {
+        const { language = 'en', ...request } = input;
+        for (const waiver of request.waivers ?? []) {
+            const subject = await service.validationWaiverSubject({
+                repoRoot: request.repoRoot,
+                taskId: request.taskId,
+                sessionId: request.sessionId,
+                ...waiver,
+            });
+            if (!subject.ok)
+                return toolResult(subject);
+            const { questionnaireId, externalTaskId, paths, reason } = subject.data;
+            const listed = paths.slice(0, 20).join(', ') + (paths.length > 20 ? ` (+${paths.length - 20})` : '');
+            const definitions = [
+                {
+                    questionnaireId,
+                    language: 'tr',
+                    message: `${externalTaskId}: Bu görev için arayüz (UI) kontrolü atlansın mı? Değişen şu dosyalar ekranda görünen arayüzü oluşturuyor: ${listed}. Belirtilen gerekçe: ${reason}. Görev, bu dosyaların widget, golden veya ekran görüntüsü testi olmadan doğrulanır. Karar görevin denetim kaydına yazılır.`,
+                    options: [
+                        { id: 'waive', label: 'Bu dosyalar için UI kontrolünü atla' },
+                        { id: 'require', label: 'UI kontrolü zorunlu kalsın' },
+                    ],
+                },
+                {
+                    questionnaireId,
+                    language: 'en',
+                    message: `${externalTaskId}: skip the UI check for this task? These changed files render UI: ${listed}. Reason given: ${reason}. The task will verify without a widget, golden or screenshot check of them. The decision is stored in the task's audit trail.`,
+                    options: [
+                        { id: 'waive', label: 'Skip the UI check for these files' },
+                        { id: 'require', label: 'Keep the UI check required' },
+                    ],
+                },
+            ];
+            const form = await askQuestionnaire(server, service, {
+                ...definitions.find((definition) => definition.language === language),
+                repoRoot: request.repoRoot,
+            }, context, definitions);
+            const record = await service.questionnaireResume({
+                repoRoot: request.repoRoot,
+                questionnaireId,
+            });
+            if (record.status !== 'answered' || record.answer?.choice !== 'waive')
+                return form;
+        }
+        return toolResult(await service.taskVerify(request));
+    });
     server.registerTool('task.close', {
         description: 'Close a task only when backend verification still matches the current Git diff hash.',
         inputSchema: z.object({