@straiffi/archon 1.0.0

package/dist/server/workers/plan.js

@@ -0,0 +1,1130 @@
+import { spawn } from 'child_process';
+import { randomUUID } from 'crypto';
+import Database from 'better-sqlite3';
+import db from '../db.js';
+import config from '../lib/config.js';
+import { JiraApiError } from '../lib/integrations/jira.js';
+import { JiraPlanningReferenceError, resolveJiraPlanningDescription } from '../lib/integrations/planning.js';
+import { resolveExistingWorktreePath } from '../lib/git.js';
+import { normalizeModelId } from '../lib/models.js';
+import { persistProjectMemorySuggestions } from '../lib/projectMemory.js';
+import { getProjectMemoryPromptBlock } from '../lib/projectMemoryPrompt.js';
+import { normalizeProjectMemorySuggestions, PROJECT_MEMORY_SUGGESTION_COMMON_RULE_LINES } from '../lib/projectMemorySuggestions.js';
+import { prependSkillPromptBlock } from '../lib/promptSkills.js';
+import { registerBundleActivity, unregisterBundleActivity } from '../lib/bundleActivity.js';
+import { enqueue, isRunning } from '../lib/queue.js';
+import { getEffectiveProject, getProjectById, listLinkedProjects } from '../lib/projects.js';
+import { resolveOpencodeDbPath } from '../lib/runtimePaths.js';
+import { createTicketMessage, upsertTicketDescriptionMessage } from '../lib/ticketMessages.js';
+import { getTicket, resolveTicketBranch, resolveTicketTool, resolveTicketWorkerKey } from '../lib/tickets.js';
+const extractLeadingJsonObject = (line) => {
+    if (!line.startsWith('{')) {
+        return null;
+    }
+    let depth = 0;
+    let inString = false;
+    let escaping = false;
+    for (let index = 0; index < line.length; index += 1) {
+        const char = line[index];
+        if (inString) {
+            if (escaping) {
+                escaping = false;
+                continue;
+            }
+            if (char === '\\') {
+                escaping = true;
+                continue;
+            }
+            if (char === '"') {
+                inString = false;
+            }
+            continue;
+        }
+        if (char === '"') {
+            inString = true;
+            continue;
+        }
+        if (char === '{') {
+            depth += 1;
+            continue;
+        }
+        if (char === '}') {
+            depth -= 1;
+            if (depth === 0) {
+                return line.slice(0, index + 1);
+            }
+        }
+    }
+    return null;
+};
+const formatPlannerToolCall = (name, input) => {
+    const value = {
+        Read: input?.file_path,
+        Write: input?.file_path,
+        Edit: input?.file_path,
+        Bash: input?.command,
+        Glob: input?.pattern,
+        Grep: input?.pattern,
+        WebFetch: input?.url,
+        WebSearch: input?.query,
+        Task: input?.description,
+        NotebookEdit: input?.notebook_path,
+    }[name] ?? Object.values(input ?? {}).find(entry => typeof entry === 'string');
+    if (typeof value !== 'string' || value.length === 0) {
+        return `_${name}_`;
+    }
+    const display = value.length > 100 ? value.slice(0, 100) + '…' : value;
+    return `_${name}_ \`${display}\``;
+};
+const parseClaudePlannerStreamJsonLine = (line) => {
+    const trimmedLine = line.trim();
+    if (!trimmedLine) {
+        return { logFragment: null, responseFragment: null };
+    }
+    let event;
+    try {
+        event = JSON.parse(trimmedLine);
+    }
+    catch {
+        return { logFragment: trimmedLine, responseFragment: trimmedLine };
+    }
+    if (event.type === 'assistant' && Array.isArray(event.message?.content)) {
+        const logParts = [];
+        const responseParts = [];
+        for (const block of event.message.content) {
+            if (block.type === 'text' && block.text) {
+                const text = block.text.trim();
+                if (text) {
+                    logParts.push(text);
+                    responseParts.push(text);
+                }
+                continue;
+            }
+            if (block.type === 'tool_use' && block.name) {
+                logParts.push(formatPlannerToolCall(block.name, block.input));
+            }
+        }
+        return {
+            logFragment: logParts.length > 0 ? logParts.join('\n\n') : null,
+            responseFragment: responseParts.length > 0 ? responseParts.join('\n\n') : null,
+        };
+    }
+    return { logFragment: null, responseFragment: null };
+};
+const formatPlannerOpencodeToolUse = (event) => {
+    const toolName = event.part?.tool;
+    if (!toolName) {
+        return null;
+    }
+    return formatPlannerToolCall(toolName, event.part?.state?.input);
+};
+const formatPlannerStepTitle = (event) => {
+    const title = event.part?.title?.trim();
+    return title || null;
+};
+const parseOpencodePlannerJsonLine = (line) => {
+    const trimmedLine = line.trim();
+    if (!trimmedLine) {
+        return { logFragment: null, responseFragment: null };
+    }
+    const jsonLine = extractLeadingJsonObject(trimmedLine);
+    if (!jsonLine) {
+        return { logFragment: trimmedLine, responseFragment: trimmedLine };
+    }
+    let event;
+    try {
+        event = JSON.parse(jsonLine);
+    }
+    catch {
+        return { logFragment: trimmedLine, responseFragment: trimmedLine };
+    }
+    if (event.type === 'text' && event.part?.type === 'text' && event.part.text) {
+        const text = event.part.text.trim();
+        const phase = event.part.metadata?.openai?.phase;
+        return {
+            logFragment: text || null,
+            responseFragment: text && (!phase || phase === 'final_answer') ? text : null,
+        };
+    }
+    if (event.type === 'reasoning' && event.part?.type === 'reasoning') {
+        const text = event.part.text?.trim() ?? '';
+        return {
+            logFragment: text || null,
+            responseFragment: null,
+        };
+    }
+    if (event.type === 'tool_use') {
+        return {
+            logFragment: formatPlannerOpencodeToolUse(event),
+            responseFragment: null,
+        };
+    }
+    if (event.type === 'step_start') {
+        return {
+            logFragment: formatPlannerStepTitle(event),
+            responseFragment: null,
+        };
+    }
+    return { logFragment: null, responseFragment: null };
+};
+const stripSystemReminderBlocks = (output) => {
+    return output.replace(/<system-reminder>[\s\S]*?<\/system-reminder>/g, '').trim();
+};
+export const IMPLEMENTATION_READY_DESCRIPTION_SECTION_HEADINGS = [
+    'Problem Statement',
+    'Acceptance Criteria',
+    'Implementation Approach',
+    'Edge Cases and Error Handling',
+    'Constraints and Things to Avoid',
+];
+const IMPLEMENTATION_READY_DESCRIPTION_REQUIREMENTS = [
+    '- A clear problem statement or goal',
+    '- Specific acceptance criteria as a checklist',
+    '- Concrete implementation approach (files to touch, patterns to follow, APIs to use, etc.)',
+    '- Edge cases and error handling to consider',
+    '- Any relevant constraints or things to avoid',
+].join('\n');
+const IMPLEMENTATION_READY_DESCRIPTION_SECTION_TEMPLATE = [
+    'Use exactly these markdown sections, in order:',
+    ...IMPLEMENTATION_READY_DESCRIPTION_SECTION_HEADINGS.map(heading => `- ## ${heading}`),
+].join('\n');
+const INDENTED_IMPLEMENTATION_READY_DESCRIPTION_SECTION_TEMPLATE = IMPLEMENTATION_READY_DESCRIPTION_SECTION_TEMPLATE
+    .split('\n')
+    .map(line => `  ${line}`)
+    .join('\n');
+const MULTI_TICKET_MAX_COUNT = 6;
+const OUTLINE_DETAIL_REQUIREMENTS = [
+    '- `summary`: 1-3 sentences describing scope and why the ticket exists',
+    '- `goal`: one sentence describing the intended end state',
+    '- `repo_context`: the most relevant existing area, component, module, API, or workflow the implementer should inspect first',
+    '- `likely_files`: 1-5 likely file paths when they can be inferred; otherwise an empty array',
+    '- `test_scope`: concrete tests, checks, or verification the implementer should run or update',
+    '- `constraints`: 2-5 short strings describing important limits, things to preserve, or things to avoid',
+].join('\n');
+const IMPLEMENTATION_DETAIL_RULES = [
+    '- Include at least 3 checklist items in `## Acceptance Criteria`.',
+    '- Include at least 2 concrete implementation bullets or numbered steps in `## Implementation Approach`.',
+    '- Mention specific files, components, modules, or APIs when they can be inferred from the repository.',
+    '- Include explicit testing or verification guidance, not just generic quality-check reminders.',
+    '- Carry forward the outline ticket\'s goal, repo context, likely files, test scope, and constraints into the final description.',
+].join('\n');
+const PLANNING_QUESTIONS_RULES = [
+    '- Always write the best complete implementation-ready description first, using your strongest reasonable assumptions.',
+    '- If a material assumption affects scope, implementation details, constraints, or acceptance criteria, also surface it as an item in `open_questions`.',
+    '- Use `open_questions` only for unresolved ticket-local refinements that would improve the plan further.',
+    '- Every `open_questions` entry must be written as a direct question ending with `?`.',
+    '- Keep `open_questions` to 0-3 short strings.',
+    '- Do not use `open_questions` for issues that would require changing the ticket split or dependency graph. In those cases, make the strongest reasonable assumption in the plan text and continue.',
+    '- Return an empty `open_questions` array when the ticket is already clear enough to implement.',
+].join('\n');
+const MEMORY_SUGGESTION_RULES = [
+    ...PROJECT_MEMORY_SUGGESTION_COMMON_RULE_LINES,
+    '- Do not suggest planner assumptions as project memory.',
+    '- Use the exact shape `{ "kind": "decision", "title": "...", "scope": "optional scope", "decision": "...", "rationale": "optional why", "implications": ["optional implication"] }` for decisions.',
+    '- Use the exact shape `{ "kind": "convention", "title": "...", "scope": "relevant area", "instruction": "...", "rationale": "optional why", "stages": ["build"], "priority": "normal" }` for conventions.',
+].join('\n');
+const ENGLISH_OUTPUT_RULES = [
+    '- Always write the output in English regardless of the language used in the source description, ticket, or linked materials.',
+    '- Translate or restate non-English input into clear natural English for titles, summaries, descriptions, constraints, acceptance criteria, implementation steps, and open questions.',
+].join('\n');
+const EXPANDED_TICKET_EXAMPLE = [
+    '{',
+    '  "key": "header-hello-world",',
+    '  "title": "Add hello world header label",',
+    '  "description": "## Problem Statement\\nThe header currently lacks the requested label, so implementers need to add it without disturbing the existing header layout.\\n\\n## Acceptance Criteria\\n- [ ] A \\\"Hello World\\\" label is visible next to the existing header title.\\n- [ ] The label uses the requested pink Tailwind styling and remains readable in the current theme.\\n- [ ] The change does not regress the existing project controls or header layout on smaller screens.\\n\\n## Implementation Approach\\n1. Update \\`client/src/App.tsx\\` where the header title is rendered so the new label sits beside the existing title block.\\n2. Reuse the current Tailwind header styling patterns for spacing and typography instead of introducing custom CSS.\\n3. Verify the header still wraps cleanly and that the existing project controls remain unchanged.\\n\\n## Edge Cases and Error Handling\\n- Ensure the added label does not wrap awkwardly or overlap adjacent header controls on narrow screens.\\n- Preserve the existing title and control rendering when projects are absent or the layout wraps.\\n\\n## Constraints and Things to Avoid\\n- Do not add a new dependency or a separate feature-specific component unless reuse is clearly justified.\\n- Do not change unrelated header behavior or styling while adding the new label."',
+    '}',
+].join('\n');
+const MAX_LINKED_RESEARCH_REQUESTS = 2;
+const normalizeLinkedResearchConfidence = (value) => {
+    return value === 'low' || value === 'medium' || value === 'high' ? value : 'medium';
+};
+const buildLinkedProjectSelectionPrompt = (taskDescription, project, linkedProjects) => {
+    const linkedProjectList = linkedProjects
+        .map(linkedProject => `- ${linkedProject.name} (id: ${linkedProject.id})`)
+        .join('\n');
+    return `You are deciding whether planning this task requires read-only research in linked repositories.
+
+Primary implementation project: ${project.name}
+
+Linked projects are token-expensive to inspect, so only request linked-project research when the user explicitly asks to inspect, read, or check a linked project, or when planning the current project would otherwise require guessing about external contracts.
+
+Return ONLY a JSON object with this exact shape:
+{
+  "requests": [
+    {
+      "project_id": "linked-project-id",
+      "question": "Specific research question",
+      "rationale": "Why this linked repo must be inspected"
+    }
+  ]
+}
+
+Rules:
+- Return an empty requests array when the current project repo is sufficient.
+- Request at most ${MAX_LINKED_RESEARCH_REQUESTS} linked-project investigations.
+- Only use project ids from the linked project list below.
+- Honor explicit user requests to inspect, read, or check a linked project when the request can be turned into a concrete contract question.
+- Only request research for concrete contract questions such as API payloads, auth expectations, stored data shape, events, or shared type definitions.
+- Do not request implementation guidance from linked repos.
+- Do not request broad repository exploration.
+- Do not include any text before or after the JSON object.
+
+Linked projects:
+${linkedProjectList}
+
+Task to plan:
+${taskDescription}`;
+};
+const buildLinkedProjectResearchPrompt = (primaryProject, linkedProject, request) => {
+    const question = typeof request.question === 'string' ? request.question.trim() : '';
+    const rationale = typeof request.rationale === 'string' ? request.rationale.trim() : '';
+    return `You are performing narrow, read-only repository research for planning work in another repo.
+
+Primary implementation project: ${primaryProject.name}
+Reference project: ${linkedProject.name}
+
+Research question:
+${question}
+
+Why this linked repo was selected:
+${rationale || 'Answer the question only if this repo contains the relevant contract details.'}
+
+Return ONLY a JSON object with this exact shape:
+{
+  "summary": "1-2 sentence answer",
+  "files_checked": ["path/to/file.ts"],
+  "findings": ["Concrete finding", "Concrete finding"],
+  "implementation_details": ["Exact external fact the downstream implementer must follow"],
+  "exact_snippet": "Optional short verbatim snippet or example payload",
+  "confidence": "low"
+}
+
+Rules:
+- This is read-only research. Do not edit files or propose making changes in this repo.
+- Keep the investigation narrow and directly tied to the question.
+- Check only the files needed to answer the question.
+- Assume downstream build agents will not inspect this linked repo.
+- Put the exact external facts the downstream implementer must receive into \`implementation_details\`.
+- If the answer depends on exact field names, field ordering, example payloads, schemas, or text and the relevant content is short enough, copy it verbatim into \`exact_snippet\`.
+- Use confidence values low, medium, or high.
+- If the answer is uncertain, say so in the summary or findings.
+- Do not include any text before or after the JSON object.`;
+};
+export const buildLinkedResearchContext = (project, linkedResearch) => {
+    if (linkedResearch.length === 0) {
+        return `
+
+Primary implementation scope:
+- The active implementation target is project \`${project.name}\` only.
+- Do not plan changes in any other repository unless those changes are split into separate tickets owned by their own projects.`;
+    }
+    const researchBlocks = linkedResearch.map(result => {
+        const filesChecked = result.filesChecked.length > 0
+            ? result.filesChecked.map(filePath => `  - ${filePath}`).join('\n')
+            : '  - None recorded';
+        const findings = result.findings.length > 0
+            ? result.findings.map(finding => `  - ${finding}`).join('\n')
+            : '  - No concrete findings recorded';
+        const implementationDetails = result.implementationDetails.length > 0
+            ? result.implementationDetails.map(detail => `  - ${detail}`).join('\n')
+            : '  - No implementation details recorded';
+        const exactSnippet = result.exactSnippet
+            ? ['  - Exact snippet:', '```', result.exactSnippet, '```'].join('\n')
+            : '  - Exact snippet: None provided';
+        return [
+            `- Linked project: ${result.projectName}`,
+            `  - Question: ${result.question}`,
+            `  - Why requested: ${result.rationale}`,
+            `  - Summary: ${result.summary}`,
+            `  - Confidence: ${result.confidence}`,
+            '  - Files checked:',
+            filesChecked,
+            '  - Findings:',
+            findings,
+            '  - Implementation details to copy into the ticket:',
+            implementationDetails,
+            exactSnippet,
+        ].join('\n');
+    }).join('\n');
+    return `
+
+Primary implementation scope:
+- The active implementation target is project \`${project.name}\` only.
+- The linked-project findings below are read-only reference material.
+- Do not create tickets or implementation steps that modify linked repositories as part of this planning output.
+- Use linked findings only to describe contracts, constraints, or behaviors the current project must follow.
+- Assume downstream build agents cannot inspect linked repositories.
+- If linked-project findings are needed, copy all required external facts directly into the ticket description.
+- Do not tell implementers to inspect linked projects or linked files.
+- When linked research includes exact snippets, schemas, payloads, or field ordering, embed those details directly in the ticket instead of paraphrasing them away.
+
+Linked project findings:
+${researchBlocks}`;
+};
+const buildPlanPrompt = (title, description, linkedResearchContext = '') => `You are helping plan a software development ticket. Based on the title and brief description below, write a detailed ticket description that is specific enough for a separate AI agent to implement the feature end-to-end without needing any further context or clarification.
+
+Include:
+${IMPLEMENTATION_READY_DESCRIPTION_REQUIREMENTS}
+
+${IMPLEMENTATION_READY_DESCRIPTION_SECTION_TEMPLATE}
+
+Title: ${title}
+Brief description: ${description}
+${linkedResearchContext}
+
+Additional rules:
+- Language rules:
+${ENGLISH_OUTPUT_RULES}
+- The downstream build agent will only work in the active project repo.
+- If linked-project findings are relevant, embed the required external contract details directly in the ticket.
+- Do not instruct the implementer to inspect linked projects or linked files.
+- Preserve any user-provided URLs, Figma links, docs, tickets, or other external resources that are needed during implementation.
+- Include those resources verbatim in the final ticket description instead of replacing them with vague summaries.
+
+Write only the expanded description in markdown, formatted to be readable by both humans and agents. No preamble or meta-commentary.`;
+const buildSingleTicketPrompt = (title, description, linkedResearchContext = '', projectMemoryBlock = '') => `You are helping plan a single software development ticket.
+
+This is a planning-only task.
+- You may inspect the repository and use read-only tools if helpful.
+- Do not edit files or make changes.
+- Return a short natural-language planning update first, then the final JSON object on the last line.
+
+Return ONLY a JSON object with this exact shape:
+{
+  "tickets": [
+    {
+      "key": "main-ticket",
+      "title": "Ticket title",
+      "description": "Detailed markdown description",
+      "open_questions": ["Optional question"],
+      "memory_suggestions": []
+    }
+  ],
+  "dependencies": []
+}
+
+Rules:
+- Return exactly one ticket.
+- Use the key \`main-ticket\`.
+- Use the provided title exactly.
+- Return an empty dependencies array.
+- Language rules:
+${ENGLISH_OUTPUT_RULES}
+- The description must be valid markdown and include:
+${IMPLEMENTATION_READY_DESCRIPTION_REQUIREMENTS}
+${INDENTED_IMPLEMENTATION_READY_DESCRIPTION_SECTION_TEMPLATE}
+- Additional detail requirements:
+${IMPLEMENTATION_DETAIL_RULES}
+- Preserve any user-provided URLs, Figma links, docs, tickets, or other external resources that are needed during implementation.
+- Include those resources verbatim in the final ticket description instead of replacing them with vague summaries.
+- Assume the downstream build agent cannot inspect linked repositories.
+- If linked-project findings are needed, copy the required facts directly into the ticket description.
+- Do not tell implementers to inspect linked projects or linked files.
+- When linked research includes exact snippets, payloads, schemas, or field ordering, embed those exact details directly in the ticket description when relevant.
+- Clarification handling rules:
+${PLANNING_QUESTIONS_RULES}
+- Memory suggestion rules:
+${MEMORY_SUGGESTION_RULES}
+- Do not wrap the JSON in markdown fences.
+- Write the natural-language update in English.
+- Keep the natural-language update to 1-3 short sentences focused on what changed in the plan.
+- Put the JSON object after the natural-language update.
+- The final line must be the JSON object.
+
+Title: ${title}
+Brief description: ${description}
+${projectMemoryBlock ? `${projectMemoryBlock}
+
+` : ''}
+${linkedResearchContext}`;
+const buildPlanningAgentOutlinePrompt = (description, linkedResearchContext = '', projectMemoryBlock = '') => `You are helping break down a software development initiative into implementation tickets for a kanban board.
+
+This is pass 1 of 2. Your job is to decide the best ticket split and dependency graph, not to fully expand implementation details yet.
+
+This is a planning-only task.
+- You may inspect the repository and use read-only tools if helpful.
+- Do not edit files or make changes.
+- Return only the final JSON object.
+
+Return ONLY a JSON object with this exact shape:
+{
+  "tickets": [
+    {
+      "key": "short-kebab-key",
+      "title": "Ticket title",
+      "summary": "Short scope summary",
+      "goal": "Intended end state",
+      "repo_context": "Relevant existing area to inspect first",
+      "likely_files": ["path/to/file.ts"],
+      "test_scope": "Concrete tests and checks to run or update",
+      "constraints": ["Constraint one", "Constraint two"]
+    }
+  ],
+  "dependencies": [
+    {
+      "blocker_key": "ticket-key",
+      "dependent_key": "other-ticket-key"
+    }
+  ]
+}
+
+Rules:
+- Create between 1 and ${MULTI_TICKET_MAX_COUNT} tickets.
+- Each ticket should be independently actionable and belong in the plan column.
+- Prefer the smallest useful number of tickets that still separates major implementation concerns cleanly.
+- Do not write full implementation-ready descriptions yet.
+- Language rules:
+${ENGLISH_OUTPUT_RULES}
+- For each ticket, include:
+${OUTLINE_DETAIL_REQUIREMENTS}
+- Use stable unique keys in kebab-case.
+- Dependencies must include only direct blockers. Do not include transitive dependencies.
+- Every dependency must reference one of the generated ticket keys.
+- If no dependencies are needed, return an empty dependencies array.
+- Do not wrap the JSON in markdown fences.
+- Do not include any text before or after the JSON object.
+- Every generated ticket must stay scoped to the active implementation project, not the linked reference repos.
+- If linked-project findings are relevant, capture them as self-contained facts in ticket summaries or constraints instead of telling implementers to inspect linked repos.
+- Preserve any user-provided URLs, Figma links, docs, tickets, or other external resources when they are needed during implementation.
+- If a resource is relevant to a generated ticket, carry it into the summary, test scope, or constraints so it survives the expansion pass.
+
+Work to break down:
+${description}
+${projectMemoryBlock ? `${projectMemoryBlock}
+
+` : ''}
+${linkedResearchContext}`;
+const buildPlanningAgentExpansionPrompt = (description, outline, linkedResearchContext = '', projectMemoryBlock = '') => `You are helping expand a previously decomposed software development initiative into implementation-ready tickets for a kanban board.
+
+Each generated ticket will later be implemented by a separate AI agent, so every ticket description must be self-contained and implementation-ready without needing any further context or clarification.
+
+This is pass 2 of 2. The ticket split and dependency graph are already decided.
+
+This is a planning-only task.
+- You may inspect the repository and use read-only tools if helpful.
+- Do not edit files or make changes.
+- Return only the final JSON object.
+
+Return ONLY a JSON object with this exact shape:
+{
+  "tickets": [
+    {
+      "key": "short-kebab-key",
+      "title": "Ticket title",
+      "description": "Detailed markdown description",
+      "open_questions": ["Optional question"],
+      "memory_suggestions": []
+    }
+  ],
+  "dependencies": [
+    {
+      "blocker_key": "ticket-key",
+      "dependent_key": "other-ticket-key"
+    }
+  ]
+}
+
+${projectMemoryBlock ? `${projectMemoryBlock}
+
+` : ''}
+
+Rules:
+- Preserve every ticket key exactly as provided.
+- Preserve every ticket title exactly as provided.
+- Preserve the dependency list exactly as provided.
+- Language rules:
+${ENGLISH_OUTPUT_RULES}
+- Each description must be valid markdown and include:
+${IMPLEMENTATION_READY_DESCRIPTION_REQUIREMENTS}
+${INDENTED_IMPLEMENTATION_READY_DESCRIPTION_SECTION_TEMPLATE}
+- Additional detail requirements:
+${IMPLEMENTATION_DETAIL_RULES}
+- Do not wrap the JSON in markdown fences.
+- Do not include any text before or after the JSON object.
+- Assume the downstream build agent cannot inspect linked repositories.
+- If linked-project findings are needed, copy the required facts directly into the ticket description.
+- Do not tell implementers to inspect linked projects or linked files.
+- When linked research includes exact snippets, payloads, schemas, or field ordering, embed those exact details directly in the ticket description when relevant.
+- Preserve any user-provided URLs, Figma links, docs, tickets, or other external resources that are needed during implementation.
+- Include those resources verbatim in the final ticket description instead of replacing them with vague summaries.
+- Clarification handling rules:
+${PLANNING_QUESTIONS_RULES}
+- Memory suggestion rules:
+${MEMORY_SUGGESTION_RULES}
+
+Example of the expected depth and structure for a single expanded ticket:
+${EXPANDED_TICKET_EXAMPLE}
+
+Original initiative:
+${description}
+${linkedResearchContext}
+
+Outline to expand:
+${JSON.stringify(outline, null, 2)}`;
+const resolvePlannerCwd = (project, branch) => {
+    if (!project) {
+        return undefined;
+    }
+    if (!branch) {
+        return project.repo_path;
+    }
+    return resolveExistingWorktreePath(branch, project) ?? project.repo_path;
+};
+const updatePlanningSessionId = (ticketId, sessionId, io) => {
+    db.prepare('UPDATE tickets SET planning_session_id = ?, updated_at = CURRENT_TIMESTAMP WHERE id = ?').run(sessionId, ticketId);
+    const ticket = getTicket(ticketId);
+    if (ticket) {
+        io.emit('ticket:updated', ticket);
+    }
+};
+export const runPlannerPrompt = (tool, model, variant, prompt, cwd, options = {}) => {
+    const resolvedModel = normalizeModelId(model);
+    const sessionTracking = options.sessionTracking;
+    let sessionId = null;
+    let spawnTimestamp = null;
+    let sessionLookupTimer = null;
+    let hasResolvedSessionId = Boolean(sessionTracking?.resumeSessionId);
+    const [cmd, args] = tool === 'claude'
+        ? (() => {
+            if (!sessionTracking) {
+                return ['claude', ['--dangerously-skip-permissions', '--print', '--verbose', '--output-format', 'stream-json', prompt]];
+            }
+            sessionId = sessionTracking.resumeSessionId || randomUUID();
+            return [
+                'claude',
+                [
+                    '--dangerously-skip-permissions',
+                    '--print',
+                    '--verbose',
+                    '--output-format',
+                    'stream-json',
+                    sessionTracking.resumeSessionId ? '--resume' : '--session-id',
+                    sessionId,
+                    prompt,
+                ],
+            ];
+        })()
+        : [
+            'opencode',
+            [
+                'run',
+                '--agent',
+                'plan',
+                '--format',
+                'json',
+                ...(sessionTracking?.resumeSessionId ? ['--session', sessionTracking.resumeSessionId] : []),
+                ...(resolvedModel ? ['--model', resolvedModel] : []),
+                ...(variant ? ['--variant', variant] : []),
+                prompt,
+            ],
+        ];
+    return new Promise((resolve, reject) => {
+        const attemptOpencodeSessionLookup = () => {
+            if (!sessionTracking || tool !== 'opencode' || hasResolvedSessionId) {
+                return false;
+            }
+            try {
+                const opencodeDb = new Database(resolveOpencodeDbPath(), { readonly: true });
+                const row = opencodeDb.prepare('SELECT id FROM session WHERE time_created > ? ORDER BY time_created DESC LIMIT 1').get(spawnTimestamp ?? 0);
+                if (row?.id) {
+                    hasResolvedSessionId = true;
+                    updatePlanningSessionId(sessionTracking.ticketId, row.id, sessionTracking.io);
+                }
+                opencodeDb.close();
+            }
+            catch {
+                // Planning session metadata is best-effort.
+            }
+            return hasResolvedSessionId;
+        };
+        const child = spawn(cmd, args, {
+            stdio: ['ignore', 'pipe', 'pipe'],
+            env: process.env,
+            ...(cwd ? { cwd } : {}),
+        });
+        if (sessionTracking && tool === 'claude' && sessionId) {
+            hasResolvedSessionId = true;
+            updatePlanningSessionId(sessionTracking.ticketId, sessionId, sessionTracking.io);
+        }
+        if (sessionTracking && tool === 'opencode') {
+            spawnTimestamp = Date.now();
+            if (!sessionTracking.resumeSessionId) {
+                sessionLookupTimer = setTimeout(() => {
+                    attemptOpencodeSessionLookup();
+                    sessionLookupTimer = null;
+                }, 1500);
+            }
+        }
+        const stdoutChunks = [];
+        const stderrChunks = [];
+        const logLines = [];
+        const responseLines = [];
+        let remainder = '';
+        const emitProgress = () => {
+            options.onProgress?.({
+                log: logLines.length > 0 ? logLines.join('\n\n') : null,
+                response: responseLines.length > 0 ? responseLines.join('\n\n') : null,
+            });
+        };
+        child.stdout?.on('data', (chunk) => {
+            stdoutChunks.push(chunk);
+            const text = remainder + chunk.toString();
+            const lines = text.split('\n');
+            remainder = lines.pop() ?? '';
+            for (const line of lines) {
+                const { logFragment, responseFragment } = tool === 'claude'
+                    ? parseClaudePlannerStreamJsonLine(line)
+                    : parseOpencodePlannerJsonLine(line);
+                if (logFragment !== null) {
+                    logLines.push(logFragment);
+                }
+                if (responseFragment !== null) {
+                    responseLines.push(responseFragment);
+                }
+                if (logFragment !== null || responseFragment !== null) {
+                    emitProgress();
+                }
+            }
+        });
+        child.stderr?.on('data', (chunk) => stderrChunks.push(chunk));
+        child.on('close', code => {
+            const resolvedSessionOnClose = attemptOpencodeSessionLookup();
+            if (sessionLookupTimer && (resolvedSessionOnClose || hasResolvedSessionId)) {
+                clearTimeout(sessionLookupTimer);
+                sessionLookupTimer = null;
+            }
+            if (remainder.trim()) {
+                const { logFragment, responseFragment } = tool === 'claude'
+                    ? parseClaudePlannerStreamJsonLine(remainder)
+                    : parseOpencodePlannerJsonLine(remainder);
+                if (logFragment !== null) {
+                    logLines.push(logFragment);
+                }
+                if (responseFragment !== null) {
+                    responseLines.push(responseFragment);
+                }
+            }
+            const rawOutput = Buffer.concat(stdoutChunks).toString().trim();
+            const output = tool === 'claude' && !rawOutput.startsWith('{')
+                ? rawOutput
+                : responseLines.join('\n\n').trim() || rawOutput;
+            const errorOutput = Buffer.concat(stderrChunks).toString().trim();
+            if (code === 0 && output) {
+                resolve(output);
+                return;
+            }
+            const fallbackError = code === 0
+                ? 'Planner did not return a usable plan.'
+                : `Process exited with code ${code}`;
+            reject(new Error(output || errorOutput || fallbackError));
+        });
+        child.on('error', err => {
+            if (sessionLookupTimer && hasResolvedSessionId) {
+                clearTimeout(sessionLookupTimer);
+                sessionLookupTimer = null;
+            }
+            reject(err);
+        });
+    });
+};
+const stripMarkdownCodeFence = (output) => {
+    const trimmedOutput = output.trim();
+    const fencedMatch = trimmedOutput.match(/^```(?:json)?\s*([\s\S]*?)\s*```$/i);
+    return fencedMatch ? fencedMatch[1].trim() : trimmedOutput;
+};
+const extractFirstJsonObjectWithLeadingText = (output) => {
+    const normalizedOutput = stripMarkdownCodeFence(stripSystemReminderBlocks(output));
+    try {
+        return {
+            parsed: JSON.parse(normalizedOutput),
+            before: '',
+        };
+    }
+    catch {
+        // Fall back to scanning for the first balanced JSON object.
+    }
+    for (let index = 0; index < normalizedOutput.length; index += 1) {
+        if (normalizedOutput[index] !== '{') {
+            continue;
+        }
+        let depth = 0;
+        let inString = false;
+        let escaping = false;
+        for (let endIndex = index; endIndex < normalizedOutput.length; endIndex += 1) {
+            const char = normalizedOutput[endIndex];
+            if (inString) {
+                if (escaping) {
+                    escaping = false;
+                    continue;
+                }
+                if (char === '\\') {
+                    escaping = true;
+                    continue;
+                }
+                if (char === '"') {
+                    inString = false;
+                }
+                continue;
+            }
+            if (char === '"') {
+                inString = true;
+                continue;
+            }
+            if (char === '{') {
+                depth += 1;
+                continue;
+            }
+            if (char === '}') {
+                depth -= 1;
+                if (depth === 0) {
+                    try {
+                        return {
+                            parsed: JSON.parse(normalizedOutput.slice(index, endIndex + 1)),
+                            before: normalizedOutput.slice(0, index).trim(),
+                        };
+                    }
+                    catch {
+                        break;
+                    }
+                }
+            }
+        }
+    }
+    throw new Error('Planner did not return a valid JSON ticket breakdown.');
+};
+const extractFirstJsonObject = (output) => {
+    const normalizedOutput = stripMarkdownCodeFence(stripSystemReminderBlocks(output));
+    try {
+        return JSON.parse(normalizedOutput);
+    }
+    catch {
+        // Fall back to scanning for the first balanced JSON object.
+    }
+    for (let index = 0; index < normalizedOutput.length; index += 1) {
+        if (normalizedOutput[index] !== '{') {
+            continue;
+        }
+        let depth = 0;
+        let inString = false;
+        let escaping = false;
+        for (let endIndex = index; endIndex < normalizedOutput.length; endIndex += 1) {
+            const char = normalizedOutput[endIndex];
+            if (inString) {
+                if (escaping) {
+                    escaping = false;
+                    continue;
+                }
+                if (char === '\\') {
+                    escaping = true;
+                    continue;
+                }
+                if (char === '"') {
+                    inString = false;
+                }
+                continue;
+            }
+            if (char === '"') {
+                inString = true;
+                continue;
+            }
+            if (char === '{') {
+                depth += 1;
+                continue;
+            }
+            if (char === '}') {
+                depth -= 1;
+                if (depth === 0) {
+                    try {
+                        return JSON.parse(normalizedOutput.slice(index, endIndex + 1));
+                    }
+                    catch {
+                        break;
+                    }
+                }
+            }
+        }
+    }
+    throw new Error('Planner did not return a valid JSON ticket breakdown.');
+};
+const normalizeOpenQuestions = (value) => {
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    return value
+        .filter((entry) => typeof entry === 'string')
+        .map(entry => entry.trim())
+        .filter(Boolean)
+        .filter((entry, index, values) => values.indexOf(entry) === index)
+        .slice(0, 3);
+};
+const validateOpenQuestions = (questions) => {
+    for (const question of questions) {
+        if (!question.endsWith('?')) {
+            throw new Error(`Planner returned an invalid open question: "${question}"`);
+        }
+    }
+    return questions;
+};
+const normalizePlanningMemorySuggestions = (value) => {
+    return normalizeProjectMemorySuggestions(value);
+};
+const createPlanningContext = ({ sourceKind, initiativePrompt, relatedTicketIds, openQuestions, }) => ({
+    source_kind: sourceKind,
+    initiative_prompt: initiativePrompt,
+    related_ticket_ids: relatedTicketIds,
+    open_questions: openQuestions,
+});
+const buildPlanningAssistantMessage = ({ response, openQuestions, }) => {
+    const trimmedResponse = response.trim();
+    const questionsBlock = openQuestions.length > 0
+        ? `Open questions:\n${openQuestions.map((question, index) => `${index + 1}. ${question}`).join('\n')}`
+        : '';
+    if (trimmedResponse && questionsBlock) {
+        return `${trimmedResponse}\n\n${questionsBlock}`;
+    }
+    if (trimmedResponse) {
+        return trimmedResponse;
+    }
+    if (questionsBlock) {
+        return questionsBlock;
+    }
+    return 'I prepared the implementation-ready plan.';
+};
+const normalizePlanningDraftTicket = (ticket) => {
+    return {
+        ...ticket,
+        open_questions: validateOpenQuestions(normalizeOpenQuestions(ticket.open_questions)),
+        memory_suggestions: normalizePlanningMemorySuggestions(ticket.memory_suggestions),
+    };
+};
+const normalizeLinkedResearchRequests = (decision, linkedProjects) => {
+    const linkedProjectIds = new Set(linkedProjects.map(project => project.id));
+    const requests = Array.isArray(decision.requests) ? decision.requests : [];
+    const seenKeys = new Set();
+    const validRequests = requests.filter((request) => {
+        return typeof request.project_id === 'string' && typeof request.question === 'string' && typeof request.rationale === 'string';
+    });
+    return validRequests
+        .map(request => ({
+        project_id: request.project_id.trim(),
+        question: request.question.trim(),
+        rationale: request.rationale.trim(),
+    }))
+        .filter(request => request.project_id !== '' && request.question !== '' && request.rationale !== '' && linkedProjectIds.has(request.project_id))
+        .filter(request => {
+        const key = `${request.project_id}:${request.question.toLowerCase()}`;
+        if (seenKeys.has(key)) {
+            return false;
+        }
+        seenKeys.add(key);
+        return true;
+    })
+        .slice(0, MAX_LINKED_RESEARCH_REQUESTS);
+};
+const normalizeLinkedResearchResponse = (response, linkedProject, request) => {
+    const summary = typeof response.summary === 'string' ? response.summary.trim() : '';
+    const filesChecked = Array.isArray(response.files_checked)
+        ? response.files_checked.filter(filePath => typeof filePath === 'string' && filePath.trim() !== '').map(filePath => filePath.trim())
+        : [];
+    const findings = Array.isArray(response.findings)
+        ? response.findings.filter(finding => typeof finding === 'string' && finding.trim() !== '').map(finding => finding.trim())
+        : [];
+    const implementationDetails = Array.isArray(response.implementation_details)
+        ? response.implementation_details.filter(detail => typeof detail === 'string' && detail.trim() !== '').map(detail => detail.trim())
+        : [];
+    const exactSnippet = typeof response.exact_snippet === 'string' && response.exact_snippet.trim() !== ''
+        ? response.exact_snippet.trim()
+        : null;
+    if (summary === '') {
+        throw new Error(`Linked project research for ${linkedProject.name} did not return a summary`);
+    }
+    return {
+        projectId: linkedProject.id,
+        projectName: linkedProject.name,
+        rationale: request.rationale,
+        question: request.question,
+        summary,
+        filesChecked,
+        findings,
+        implementationDetails,
+        exactSnippet,
+        confidence: normalizeLinkedResearchConfidence(response.confidence),
+    };
+};
+export const prepareLinkedPlanningResearch = async (taskDescription, options = {}) => {
+    const project = options.projectId ? getProjectById(options.projectId) : null;
+    const cwd = resolvePlannerCwd(project, options.branch);
+    if (!project || !cwd) {
+        return [];
+    }
+    const linkedProjects = listLinkedProjects(project.id);
+    if (linkedProjects.length === 0) {
+        return [];
+    }
+    const tool = options.tool ?? config.tool ?? 'opencode';
+    let decision;
+    try {
+        const output = await runPlannerPrompt(tool, options.model ?? null, options.variant ?? null, buildLinkedProjectSelectionPrompt(taskDescription, project, linkedProjects), cwd);
+        decision = extractFirstJsonObject(output);
+    }
+    catch {
+        return [];
+    }
+    const requests = normalizeLinkedResearchRequests(decision, linkedProjects);
+    if (requests.length === 0) {
+        return [];
+    }
+    const linkedProjectsById = new Map(linkedProjects.map(linkedProject => [linkedProject.id, linkedProject]));
+    const linkedResearch = await Promise.all(requests.map(async (request) => {
+        const linkedProject = linkedProjectsById.get(request.project_id);
+        if (!linkedProject) {
+            throw new Error(`Linked project ${request.project_id} is no longer available`);
+        }
+        const output = await runPlannerPrompt(tool, options.model ?? null, options.variant ?? null, prependSkillPromptBlock(buildLinkedProjectResearchPrompt(project, linkedProject, request), options.skills ?? []), linkedProject.repo_path);
+        return normalizeLinkedResearchResponse(extractFirstJsonObject(output), linkedProject, request);
+    }));
+    return linkedResearch;
+};
+export const generatePlanText = (title, description, options = {}) => {
+    const tool = options.tool ?? config.tool ?? 'opencode';
+    const project = options.projectId ? getProjectById(options.projectId) : null;
+    return (async () => {
+        const linkedResearch = options.linkedResearch ?? await prepareLinkedPlanningResearch(`${title}\n\n${description}`, options);
+        const linkedResearchContext = project ? buildLinkedResearchContext(project, linkedResearch) : '';
+        const projectMemoryBlock = getProjectMemoryPromptBlock(project?.id, {
+            stage: 'plan',
+            title,
+            description,
+        });
+        const expanded = extractFirstJsonObjectWithLeadingText(await runPlannerPrompt(tool, options.model ?? null, options.variant ?? null, prependSkillPromptBlock(buildSingleTicketPrompt(title, description, linkedResearchContext, projectMemoryBlock), options.skills ?? []), resolvePlannerCwd(project, options.branch), {
+            onProgress: options.onProgress,
+            ...(options.ticketId && options.io
+                ? {
+                    sessionTracking: {
+                        ticketId: options.ticketId,
+                        io: options.io,
+                        resumeSessionId: options.planningSessionId,
+                    },
+                }
+                : {}),
+        }));
+        const expandedTicket = expanded.parsed.tickets.find(ticket => ticket.key === 'main-ticket');
+        if (!expandedTicket?.description?.trim()) {
+            throw new Error('Planner did not return a usable plan.');
+        }
+        return {
+            ...normalizePlanningDraftTicket(expandedTicket),
+            key: 'main-ticket',
+            title: title.trim(),
+            description: expandedTicket.description.trim(),
+            response: expanded.before.trim(),
+        };
+    })();
+};
+export const generatePlanningTicketOutline = async (description, options = {}) => {
+    const tool = options.tool ?? config.tool ?? 'opencode';
+    const project = options.projectId ? getProjectById(options.projectId) : null;
+    const linkedResearch = options.linkedResearch ?? await prepareLinkedPlanningResearch(description, options);
+    const linkedResearchContext = project ? buildLinkedResearchContext(project, linkedResearch) : '';
+    const projectMemoryBlock = getProjectMemoryPromptBlock(project?.id, {
+        stage: 'plan',
+        title: description,
+        description,
+    });
+    const output = await runPlannerPrompt(tool, options.model ?? null, options.variant ?? null, prependSkillPromptBlock(buildPlanningAgentOutlinePrompt(description, linkedResearchContext, projectMemoryBlock), options.skills ?? []), resolvePlannerCwd(project, options.branch));
+    return extractFirstJsonObject(output);
+};
+export const expandPlanningTicketOutline = async (description, outline, options = {}) => {
+    const tool = options.tool ?? config.tool ?? 'opencode';
+    const project = options.projectId ? getProjectById(options.projectId) : null;
+    const linkedResearch = options.linkedResearch ?? await prepareLinkedPlanningResearch(description, options);
+    const linkedResearchContext = project ? buildLinkedResearchContext(project, linkedResearch) : '';
+    const projectMemoryBlock = getProjectMemoryPromptBlock(project?.id, {
+        stage: 'plan',
+        title: description,
+        description,
+    });
+    const output = await runPlannerPrompt(tool, options.model ?? null, options.variant ?? null, prependSkillPromptBlock(buildPlanningAgentExpansionPrompt(description, outline, linkedResearchContext, projectMemoryBlock), options.skills ?? []), resolvePlannerCwd(project, options.branch));
+    return extractFirstJsonObject(output);
+};
+const emitTicketUpdate = (ticketId, io) => {
+    const updated = getTicket(ticketId);
+    if (updated) {
+        io.emit('ticket:updated', updated);
+    }
+};
+const updatePlanningProgress = (ticketId, log, response, io) => {
+    db.prepare('UPDATE tickets SET agent_status = ?, agent_log = ?, streaming_response = ?, updated_at = CURRENT_TIMESTAMP WHERE id = ?').run('running', log ?? null, response ?? null, ticketId);
+    emitTicketUpdate(ticketId, io);
+};
+export const startPlan = (ticket, io, options = {}) => {
+    const jobKey = resolveTicketWorkerKey(ticket, 'plan');
+    if (!jobKey || isRunning(jobKey)) {
+        return;
+    }
+    enqueue(jobKey, async () => {
+        registerBundleActivity(ticket, 'plan');
+        db.prepare('UPDATE tickets SET agent_status = ?, agent_log = NULL, streaming_response = NULL, updated_at = CURRENT_TIMESTAMP WHERE id = ?').run('running', ticket.id);
+        emitTicketUpdate(ticket.id, io);
+        try {
+            const project = getEffectiveProject(ticket);
+            const branch = options.branch === undefined ? resolveTicketBranch(ticket) : options.branch;
+            const planningDescription = await resolveJiraPlanningDescription(project?.id ?? ticket.project_id, ticket.description);
+            const initiativePrompt = ticket.planning_context?.initiative_prompt?.trim() || planningDescription;
+            const planned = await generatePlanText(ticket.title, planningDescription, {
+                tool: resolveTicketTool(ticket, config.tool ?? 'opencode'),
+                model: ticket.model,
+                variant: ticket.variant,
+                skills: options.skills ?? ticket.skills ?? [],
+                projectId: project?.id ?? ticket.project_id,
+                branch,
+                planningSessionId: ticket.planning_session_id,
+                ticketId: ticket.id,
+                io,
+                onProgress: progress => {
+                    updatePlanningProgress(ticket.id, progress.log, progress.response, io);
+                },
+            });
+            const planningContext = createPlanningContext({
+                sourceKind: 'single',
+                initiativePrompt,
+                relatedTicketIds: [ticket.id],
+                openQuestions: planned.open_questions,
+            });
+            db.prepare('UPDATE tickets SET description = ?, agent_status = ?, agent_log = NULL, streaming_response = NULL, planning_context_json = ?, updated_at = CURRENT_TIMESTAMP WHERE id = ?').run(planned.description, 'done', JSON.stringify(planningContext), ticket.id);
+            const suggestionProjectId = project?.id ?? ticket.project_id;
+            if (suggestionProjectId && Boolean(project?.memory_enabled)) {
+                persistProjectMemorySuggestions(suggestionProjectId, ticket.id, 'plan', planned.memory_suggestions);
+            }
+            upsertTicketDescriptionMessage(ticket.id, planned.description);
+            const assistantMessage = buildPlanningAssistantMessage({
+                response: planned.response,
+                openQuestions: planned.open_questions,
+            });
+            if (assistantMessage) {
+                createTicketMessage({
+                    ticketId: ticket.id,
+                    role: 'assistant',
+                    kind: 'planning_response',
+                    content: assistantMessage,
+                });
+            }
+            emitTicketUpdate(ticket.id, io);
+        }
+        catch (err) {
+            const message = err instanceof JiraPlanningReferenceError
+                ? err.message
+                : err instanceof JiraApiError
+                    ? err.publicMessage
+                    : err instanceof Error
+                        ? err.message
+                        : String(err);
+            db.prepare('UPDATE tickets SET agent_status = ?, agent_log = ?, streaming_response = NULL, updated_at = CURRENT_TIMESTAMP WHERE id = ?').run('error', message, ticket.id);
+            emitTicketUpdate(ticket.id, io);
+        }
+        finally {
+            unregisterBundleActivity(ticket, 'plan');
+        }
+    });
+};
+//# sourceMappingURL=plan.js.map