engineering-memory 1.11.11 → 1.11.13

package/runtime/dist/src/runtime/task-start.js

@@ -1,4 +1,44 @@
 import { sha256, stableStringify } from '../utilities/hash.js';
+const startCopy = {
+    en: {
+        start: (task) => `${task}: how should this task start?`,
+        context: 'A task works on its own branch so that unfinished work never mixes with what is already open in this folder. Nothing is created, checked out or reserved until you answer. Your answer is kept, so asking for the same task again does not ask you twice.',
+        example: 'Choosing a separate worktree creates the branch in a folder of its own and leaves this folder on the branch and the files you have open right now.',
+        keepContext: 'This task continues on the branch this folder is already on. Nothing is created, checked out or reserved until you answer. Your answer is kept, so asking for the same task again does not ask you twice.',
+        roles: { development: 'development', production: 'production', test: 'test' },
+        holder: (task, branch, when) => `${task} holds this folder (branch ${branch}, last activity ${when}). If it moves out it stays open, keeps its own branch and continues in a separate worktree when it is resumed.`,
+        unknown: 'unknown',
+        separate: 'A managed folder of its own is prepared and the new branch is created there. This folder is left on its branch and its files are not touched.',
+        inPlace: 'The new branch is created here and this folder is switched to it.',
+        moveOut: (task) => `${task} keeps its branch and its work and continues in a separate worktree later. The new branch is checked out here.`,
+        stay: (source) => `Nothing new is created. The work continues on ${source} in this folder, so every commit lands on that branch.`,
+        later: 'Nothing is created or reserved. The task waits until you ask to start it.',
+        fetched: (role, source) => `The project's ${role} branch ${source} is fetched from the remote and the new branch starts from that exact commit.`,
+        pinned: (source) => `The new branch starts where this folder is right now, ${source}. Nothing is fetched.`,
+        typedBranch: 'Write a branch name on origin below. It is fetched and the new branch starts from it.',
+        suggested: 'The branch is created with this name.',
+        typedName: 'Write the name below. A name that already exists is refused and the form is asked again.',
+    },
+    tr: {
+        start: (task) => `${task} nasıl başlasın?`,
+        context: 'Her görev kendi dalında çalışır; böylece yarım kalan iş, bu klasörde açık olan işe karışmaz. Sen cevaplayana kadar hiçbir klasör açılmaz, hiçbir dal oluşturulmaz, hiçbir yer ayrılmaz. Verdiğin cevap saklanır; aynı görev için ikinci kez sorulmaz.',
+        example: 'Ayrı worktree’yi seçersen yeni dal kendi klasöründe açılır; bu klasör şu anki dalında ve açık dosyalarıyla olduğu gibi kalır.',
+        keepContext: 'Bu görev, klasörün zaten üzerinde olduğu dalda devam eder. Sen cevaplayana kadar hiçbir şey oluşturulmaz, hiçbir yer ayrılmaz. Verdiğin cevap saklanır; aynı görev için yeniden sorulmaz.',
+        roles: { development: 'geliştirme', production: 'canlı', test: 'test' },
+        holder: (task, branch, when) => `${task} görevi bu klasörü tutuyor (dal ${branch}, son etkinlik ${when}). Buradan çıkarılırsa görev kapanmaz; kendi dalını ve işini korur, devam ettiğinde ayrı bir worktree’de açılır.`,
+        unknown: 'bilinmiyor',
+        separate: 'Görev için ayrı bir klasör hazırlanır ve yeni dal orada açılır. Bu klasör kendi dalında kalır, dosyalarına dokunulmaz.',
+        inPlace: 'Yeni dal burada açılır ve bu klasör o dala geçer.',
+        moveOut: (task) => `${task} dalını ve işini korur, sonra ayrı bir worktree’de devam eder. Yeni dal burada açılır.`,
+        stay: (source) => `Yeni bir şey oluşturulmaz. İş bu klasörde ${source} üzerinde sürer; her commit o dala gider.`,
+        later: 'Hiçbir şey oluşturulmaz, hiçbir yer ayrılmaz. Görev sen isteyene kadar beklemede kalır.',
+        fetched: (role, source) => `Projenin ${role} dalı ${source} uzak sunucudan çekilir ve yeni dal tam o commit’ten başlar.`,
+        pinned: (source) => `Yeni dal, bu klasörün şu an üzerinde olduğu ${source} noktasından başlar. Hiçbir şey çekilmez.`,
+        typedBranch: 'origin üzerindeki dal adını aşağıya yaz. O dal çekilir ve yeni dal ondan başlar.',
+        suggested: 'Dal bu adla açılır.',
+        typedName: 'Adı aşağıya yaz. Zaten var olan bir ad kabul edilmez, form yeniden sorulur.',
+    },
+};
 export function suggestedBranchNames(externalTaskId) {
     const slug = externalTaskId
         .replace(/[^A-Za-z0-9._-]+/g, '-')
@@ -34,6 +74,7 @@ export function configuredBase(preferences, role) {
 }
 export function taskStartDefinition(facts) {
     const tr = facts.language === 'tr';
+    const copy = startCopy[tr ? 'tr' : 'en'];
     const folder = facts.folder;
     const keepOnly = facts.keepCurrent === true || !facts.currentCommit;
     const here = !keepOnly && !folder.managed && !folder.heldBy && folder.clean;
@@ -46,14 +87,26 @@ export function taskStartDefinition(facts) {
         currentCommit: facts.currentCommit,
         holder,
     };
+    const heldNotice = here && folder.holder
+        ? copy.holder(folder.holder.externalTaskId, folder.holder.branch ?? 'detached HEAD', readableTime(folder.holder.lastCheckpointAt, tr) ?? copy.unknown)
+        : null;
+    const withheldNotice = withheld(folder, keepOnly, tr);
+    const locationContext = [heldNotice, withheldNotice].filter(Boolean).join(' ');
     const questions = [
         {
             id: 'location',
             message: tr ? 'Nerede başlasın?' : 'Where should it start?',
+            ...(locationContext ? { context: locationContext } : {}),
             options: [
                 ...(keepOnly
                     ? []
-                    : [{ id: 'worktree', label: tr ? 'Ayrı bir worktree’de' : 'In a separate worktree' }]),
+                    : [
+                        {
+                            id: 'worktree',
+                            label: tr ? 'Ayrı bir worktree’de' : 'In a separate worktree',
+                            description: copy.separate,
+                        },
+                    ]),
                 ...(here
                     ? [
                         {
@@ -65,6 +118,7 @@ export function taskStartDefinition(facts) {
                                 : tr
                                     ? 'Bu klasörde yeni branch olarak'
                                     : 'In this folder, as a new branch',
+                            description: holder ? copy.moveOut(holder.externalTaskId) : copy.inPlace,
                         },
                     ]
                     : []),
@@ -75,10 +129,11 @@ export function taskStartDefinition(facts) {
                             label: tr
                                 ? 'Burada, ' + currentLabel + ' üzerinde, yeni branch açmadan'
                                 : 'Here on ' + currentLabel + ', without a new branch',
+                            description: copy.stay(currentLabel),
                         },
                     ]
                     : []),
-                { id: 'defer', label: tr ? 'Şimdilik başlatma' : 'Not now' },
+                { id: 'defer', label: tr ? 'Şimdilik başlatma' : 'Not now', description: copy.later },
             ],
         },
     ];
@@ -92,6 +147,7 @@ export function taskStartDefinition(facts) {
         const roleOption = ({ role, base }) => ({
             id: role,
             label: base.remote + '/' + base.branch + ' (' + role + ')',
+            description: copy.fetched(copy.roles[role], base.remote + '/' + base.branch),
         });
         binding.bases = {
             current: {
@@ -108,9 +164,14 @@ export function taskStartDefinition(facts) {
                 {
                     id: 'current',
                     label: tr ? 'Bu klasörün dalı: ' + currentLabel : 'This folder’s branch: ' + currentLabel,
+                    description: copy.pinned(currentLabel),
                 },
                 ...roles.slice(1).map(roleOption),
-                { id: 'other', label: tr ? 'Başka bir uzak dal' : 'Another remote branch' },
+                {
+                    id: 'other',
+                    label: tr ? 'Başka bir uzak dal' : 'Another remote branch',
+                    description: copy.typedBranch,
+                },
             ],
             otherAsText: true,
             textField: {
@@ -128,8 +189,8 @@ export function taskStartDefinition(facts) {
             id: 'name',
             message: tr ? 'Yeni branch’in adı ne olsun?' : 'What should the new branch be called?',
             options: [
-                { id: 'suggested', label: facts.suggestedName },
-                { id: 'custom', label: tr ? 'Başka bir ad' : 'Another name' },
+                { id: 'suggested', label: facts.suggestedName, description: copy.suggested },
+                { id: 'custom', label: tr ? 'Başka bir ad' : 'Another name', description: copy.typedName },
             ],
             textField: {
                 title: tr ? 'Branch adı' : 'Branch name',
@@ -140,24 +201,7 @@ export function taskStartDefinition(facts) {
     }
     else if (!keepOnly)
         binding.name = facts.name;
-    const fixed = [
-        ...(here && folder.holder
-            ? [
-                tr
-                    ? folder.holder.externalTaskId +
-                        ' bu klasörü tutuyor (branch ' +
-                        (folder.holder.branch ?? 'detached HEAD') +
-                        ', son etkinlik ' +
-                        (folder.holder.lastCheckpointAt ?? 'bilinmiyor') +
-                        '). Çıkarılırsa görev açık kalır ve devam ederken ayrı bir worktree’de açılır.'
-                    : folder.holder.externalTaskId +
-                        ' holds this folder (branch ' +
-                        (folder.holder.branch ?? 'detached HEAD') +
-                        ', last activity ' +
-                        (folder.holder.lastCheckpointAt ?? 'unknown') +
-                        '). If it moves out, it stays open and continues in a separate worktree when resumed.',
-            ]
-            : []),
+    const chosen = [
         ...(binding.base
             ? [
                 tr
@@ -168,25 +212,57 @@ export function taskStartDefinition(facts) {
         ...(binding.name
             ? [tr ? 'Yeni branch: ' + binding.name + '.' : 'New branch: ' + binding.name + '.']
             : []),
-        ...(withheld(folder, keepOnly, tr) ? [withheld(folder, keepOnly, tr)] : []),
     ];
-    const content = {
+    const shared = {
+        language: facts.language,
+        terminalChoices: [
+            { questionId: 'location', choice: 'defer' },
+            ...(keep ? [{ questionId: 'location', choice: 'keep_current' }] : []),
+        ],
+        binding: JSON.parse(JSON.stringify(binding)),
+    };
+    const previous = {
         message: [
             tr
                 ? facts.externalTaskId + ' nasıl başlasın? Sen cevaplayana kadar hiçbir şey oluşturulmaz.'
                 : facts.externalTaskId +
                     ': how should this task start? Nothing is created until you answer.',
-            ...fixed,
+            ...(here && folder.holder
+                ? [
+                    tr
+                        ? folder.holder.externalTaskId +
+                            ' bu klasörü tutuyor (branch ' +
+                            (folder.holder.branch ?? 'detached HEAD') +
+                            ', son etkinlik ' +
+                            (folder.holder.lastCheckpointAt ?? 'bilinmiyor') +
+                            '). Çıkarılırsa görev açık kalır ve devam ederken ayrı bir worktree’de açılır.'
+                        : folder.holder.externalTaskId +
+                            ' holds this folder (branch ' +
+                            (folder.holder.branch ?? 'detached HEAD') +
+                            ', last activity ' +
+                            (folder.holder.lastCheckpointAt ?? 'unknown') +
+                            '). If it moves out, it stays open and continues in a separate worktree when resumed.',
+                ]
+                : []),
+            ...chosen,
+            ...(withheldNotice ? [withheldNotice] : []),
         ].join(' '),
-        language: facts.language,
+        ...shared,
+        questions: questions.map(({ context: _why, options, ...question }) => ({
+            ...question,
+            options: options.map(({ description: _next, ...option }) => option),
+        })),
+    };
+    const questionnaireId = 'task-start-' + sha256(stableStringify(previous));
+    return {
+        questionnaireId,
+        message: [copy.start(facts.externalTaskId), ...chosen].join(' '),
+        context: keepOnly ? copy.keepContext : copy.context,
+        example: keepOnly ? copy.stay(currentLabel) : copy.example,
+        ...shared,
         questions,
-        terminalChoices: [
-            { questionId: 'location', choice: 'defer' },
-            ...(keep ? [{ questionId: 'location', choice: 'keep_current' }] : []),
-        ],
-        binding: JSON.parse(JSON.stringify(binding)),
+        previous: { questionnaireId, ...previous },
     };
-    return { questionnaireId: 'task-start-' + sha256(stableStringify(content)), ...content };
 }
 export function taskStartChoice(record) {
     if (record.status !== 'answered' ||
@@ -264,6 +340,12 @@ function holderIdentity(holder) {
         generation: holder.generation,
     };
 }
+function readableTime(value, tr) {
+    const [, date, time] = /^(\d{4}-\d{2}-\d{2})T(\d{2}:\d{2})/.exec(value ?? '') ?? [];
+    if (!date || !time)
+        return null;
+    return (tr ? date.split('-').reverse().join('.') : date) + ' ' + time + ' UTC';
+}
 function withheld(folder, keepOnly, tr) {
     if (keepOnly || folder.managed || (!folder.heldBy && folder.clean))
         return null;

package/skill/references/questionnaires.md

@@ -6,7 +6,11 @@ Use the host's native questionnaire for every question to the user, including im
 
 Use `questionnaire.ask` for a required decision. It records the question before opening a native MCP form. Use a stable question identifier belonging to the current task and decision, so a retry returns to the same question instead of creating another one. A new decision needs its own identifier; an answer to an earlier proposal, branch or delivery does not approve a later one.
 
-Pass `repoRoot`, `questionnaireId`, `message` and two to twelve `options`, each with an `id` and `label`. Identifiers use letters, digits, underscores or hyphens. Set `allowFreeText` only when the user needs to give an answer outside those options. `questionnaire.resume` takes the same `repoRoot` and `questionnaireId`. These tools collect decisions; they do not commit, publish, bind a project or perform the selected action. Apply the accepted answer through the relevant lifecycle tool, checking the current target and version first.
+Pass `repoRoot`, `questionnaireId`, `message` and two to twelve `options`, each with an `id` and `label`. Identifiers use letters, digits, underscores or hyphens.
+
+A question has to be answerable by someone who has not followed the work. Say in `context` why it is being asked, give in `example` one concrete thing the decision changes, and give every option a `description` of what happens next if it is chosen. Show a record, a branch or a project by its title or name; an identifier or a hash in the visible text is refused, and one that really has to be shown goes inside backticks. Write all of it in the language the user is writing in and pass that language as `language`, a BCP-47 tag such as `tr`, `en` or `pt-BR`. The tag is remembered for the account and the computer, so it is asked for once: `session.entry` and every tool that opens a form take the same argument, and `questionnaire.ask` is refused while no language is known.
+
+Every form carries one more choice, "I did not understand; explain in more detail first". It is never recorded as an answer. When a call returns `needs_explanation`, explain in chat why the question is asked, what each option leads to and one example, then show the same question again with `questionnaire.resume`. A free-text reply that says the question was not understood is handled the same way and is not passed on as the decision. Set `allowFreeText` only when the user needs to give an answer outside those options. `questionnaire.resume` takes the same `repoRoot` and `questionnaireId`. These tools collect decisions; they do not commit, publish, bind a project or perform the selected action. Apply the accepted answer through the relevant lifecycle tool, checking the current target and version first.
 
 Fixed-choice answers can be replayed from the local receipt. Free text is returned only in the accepting call and is never stored. If a later receipt says the answer is unavailable, recover it from the user's actual answer in the conversation; never reconstruct it from the options. If it cannot be recovered, explain that it must be requested again using a new question identifier.
 
@@ -324,8 +328,9 @@ Saving a profile does not authorize filesystem initialization.
 ## Inspection confirmation language
 
 For memory.sync_start, pass language: tr in a Turkish conversation and language: en in an English
-conversation. Use the conversation language, never the computer locale. Legacy calls without language
-use English. The form shows a short source reference, scope, the treatment of uncommitted changes and
+conversation. Use the conversation language, never the computer locale. A call without language uses
+the language remembered from an earlier call, and English when none is known. The bridge's own forms
+have Turkish and English text; any other language opens them in English. The form shows a short source reference, scope, the treatment of uncommitted changes and
 the separate approval needed for permanent memory. Full commit and request hashes stay in the durable
 approval binding, not in the visible question. Generic questionnaire.ask messages and option labels
 are written by the agent in the same language; pass language for the native help and field labels.