@planu/cli 0.15.2

package/dist/tools/clarify-requirements/questions.js

@@ -0,0 +1,116 @@
+/** Returns true if the topic has fewer than 3 words (extremely vague — meta-questions needed). */
+export function isShortTopic(topic) {
+    return topic.trim().split(/\s+/).length < 3;
+}
+/** Generate meta-questions to scope a vague topic. */
+export function generateMetaQuestions() {
+    return [
+        {
+            id: 'meta-1',
+            question: 'Is this a brand new feature or an improvement to something that already exists?',
+            category: 'scope',
+            importance: 'critical',
+            suggestedAnswers: ['New feature', 'Improvement to existing feature', 'Bug fix', 'Refactor'],
+        },
+        {
+            id: 'meta-2',
+            question: 'Who is the primary user that benefits from this? (e.g., end user, admin, developer)',
+            category: 'scope',
+            importance: 'critical',
+            suggestedAnswers: ['End user', 'Admin', 'Developer/internal', 'All users'],
+        },
+        {
+            id: 'meta-3',
+            question: 'What is the minimum viable scope — what would make this "done" at a basic level?',
+            category: 'scope',
+            importance: 'critical',
+            suggestedAnswers: [
+                'Just the core happy path',
+                'Happy path + error handling',
+                'Full feature with edge cases',
+            ],
+        },
+    ];
+}
+/**
+ * Detect contradictions in a set of answers.
+ * Returns an array of human-readable contradiction descriptions.
+ */
+export function detectContradictions(answers) {
+    const contradictions = [];
+    const values = Object.values(answers).map((v) => v.toLowerCase());
+    const joined = values.join(' ');
+    // Heuristic: "fast" / "no cache"
+    if ((joined.includes('fast') || joined.includes('performant') || joined.includes('low latency')) &&
+        (joined.includes('no cache') ||
+            joined.includes('without cache') ||
+            joined.includes('sin cache'))) {
+        contradictions.push('Performance requirement ("fast") may conflict with "no cache" — caching is a primary tool for low-latency responses.');
+    }
+    // Heuristic: "simple" / many features
+    const featureKeywords = [
+        'real-time',
+        'realtime',
+        'offline',
+        'multi-tenant',
+        'i18n',
+        'analytics',
+        'notifications',
+    ];
+    const wantsSimple = joined.includes('simple') || joined.includes('minimal') || joined.includes('lightweight');
+    const wantsComplex = featureKeywords.some((k) => joined.includes(k));
+    if (wantsSimple && wantsComplex) {
+        contradictions.push('Scope may be underestimated: "simple/minimal" combined with advanced features (real-time, offline, multi-tenant, etc.) typically results in a complex implementation.');
+    }
+    // Heuristic: deadline conflicts
+    if ((joined.includes('urgent') || joined.includes('asap') || joined.includes('tomorrow')) &&
+        (joined.includes('comprehensive') ||
+            joined.includes('complete') ||
+            joined.includes('all edge cases'))) {
+        contradictions.push('Timeline conflict: "urgent/ASAP" deadline with "comprehensive/all edge cases" scope — consider scoping down to an MVP first.');
+    }
+    return contradictions;
+}
+/**
+ * Build suggested answers for a question using project knowledge.
+ */
+export function buildSuggestedAnswers(question, knowledge) {
+    const lower = question.question.toLowerCase();
+    // Database-related: suggest the project's database
+    if (lower.includes('database') || lower.includes('table') || lower.includes('schema')) {
+        if (knowledge && knowledge.database !== 'unknown') {
+            return [
+                `Yes, using project's ${knowledge.database} database`,
+                'No new tables needed',
+                'Needs new tables',
+                'Modifies existing tables',
+            ];
+        }
+    }
+    // Framework-related: suggest the project's framework
+    if (lower.includes('framework') || lower.includes('pattern') || lower.includes('component')) {
+        if (knowledge?.framework) {
+            return [
+                `Yes, reuse ${knowledge.framework} patterns`,
+                'New pattern needed',
+                'Mix of existing and new',
+            ];
+        }
+    }
+    // Performance questions
+    if (lower.includes('performance') ||
+        lower.includes('response time') ||
+        lower.includes('throughput')) {
+        return ['< 200ms response', '< 1s response', 'No strict requirement', 'Depends on load'];
+    }
+    // Auth questions
+    if (lower.includes('authentication') || lower.includes('auth')) {
+        return ['JWT tokens', 'Session-based', 'OAuth 2.0', 'No authentication needed', 'API key'];
+    }
+    // Timeline questions
+    if (lower.includes('deadline') || lower.includes('timeline')) {
+        return ['No strict deadline', 'Within 1 week', 'Within 1 sprint (2 weeks)', 'Specific date'];
+    }
+    return [];
+}
+//# sourceMappingURL=questions.js.map

package/dist/tools/clarify-requirements/questions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"questions.js","sourceRoot":"","sources":["../../../src/tools/clarify-requirements/questions.ts"],"names":[],"mappings":"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"}

package/dist/tools/clarify-requirements.d.ts

@@ -0,0 +1,3 @@
+import type { ClarifyRequirementsInput, ToolResult } from '../types/index.js';
+export declare function handleClarifyRequirements(params: ClarifyRequirementsInput): Promise<ToolResult>;
+//# sourceMappingURL=clarify-requirements.d.ts.map

package/dist/tools/clarify-requirements.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"clarify-requirements.d.ts","sourceRoot":"","sources":["../../src/tools/clarify-requirements.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,wBAAwB,EAGxB,UAAU,EACX,MAAM,mBAAmB,CAAC;AAyF3B,wBAAsB,yBAAyB,CAC7C,MAAM,EAAE,wBAAwB,GAC/B,OAAO,CAAC,UAAU,CAAC,CA2FrB"}

package/dist/tools/clarify-requirements.js

@@ -0,0 +1,151 @@
+import { ti } from '../i18n/index.js';
+import { knowledgeStore } from '../storage/index.js';
+import { randomUUID } from 'node:crypto';
+import { isShortTopic, generateMetaQuestions, detectContradictions, buildSuggestedAnswers, } from './clarify-requirements/questions.js';
+import { generateQuestions } from './clarify-requirements/questions-context.js';
+/** Resume an existing clarification session with new answers. */
+async function handleResumeSession(projectId, sessionId, newAnswers, knowledge) {
+    const existing = await knowledgeStore.getClarification(projectId, sessionId).catch(() => null);
+    if (!existing) {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify({
+                        error: `Session '${sessionId}' not found. Start a new session by calling clarify_requirements without sessionId.`,
+                    }, null, 2),
+                },
+            ],
+            isError: true,
+        };
+    }
+    const mergedAnswers = { ...existing.answers, ...newAnswers };
+    const contradictions = Object.keys(mergedAnswers).length > 0 ? detectContradictions(mergedAnswers) : [];
+    const criticalIds = existing.questions
+        .filter((q) => q.importance === 'critical')
+        .map((q) => q.id);
+    const specReady = criticalIds.every((id) => {
+        const ans = mergedAnswers[id];
+        return ans !== undefined && ans.trim() !== '';
+    });
+    const enriched = existing.questions.map((q) => ({
+        ...q,
+        suggestedAnswers: q.suggestedAnswers ?? buildSuggestedAnswers(q, knowledge),
+    }));
+    const updated = {
+        ...existing,
+        questions: enriched,
+        answers: mergedAnswers,
+        isComplete: specReady,
+        contradictions: contradictions.length > 0 ? contradictions : undefined,
+        specReady,
+    };
+    await knowledgeStore.addClarification(projectId, updated);
+    const result = {
+        sessionId: existing.id,
+        topic: existing.topic,
+        questionsCount: existing.questions.length,
+        questions: enriched.map((q) => ({
+            id: q.id,
+            question: q.question,
+            category: q.category,
+            importance: q.importance,
+            suggestedAnswers: q.suggestedAnswers,
+            answered: mergedAnswers[q.id] !== undefined,
+        })),
+        specReady,
+        answeredCount: Object.keys(mergedAnswers).length,
+        ...(contradictions.length > 0
+            ? {
+                contradictions,
+                contradictionWarning: 'Potential contradictions detected — review before creating the spec.',
+            }
+            : {}),
+        instructions: specReady
+            ? 'All critical questions answered. Call create_spec with clarificationSessionId.'
+            : `${criticalIds.length - criticalIds.filter((id) => mergedAnswers[id]?.trim()).length} critical question(s) remaining.`,
+        message: `Session resumed. ${Object.keys(mergedAnswers).length}/${existing.questions.length} answered.`,
+    };
+    return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+}
+export async function handleClarifyRequirements(params) {
+    const { projectId, topic, context, maxQuestions = 7, answers, sessionId } = params;
+    try {
+        // Load project knowledge — proceed with null if project not yet initialized (SPEC-020: criterion 5.1)
+        const knowledge = await knowledgeStore.getKnowledge(projectId).catch(() => null);
+        // Resume existing session if sessionId provided
+        if (sessionId) {
+            return await handleResumeSession(projectId, sessionId, answers ?? {}, knowledge);
+        }
+        // Detect contradictions in provided answers (if any)
+        const contradictions = answers && Object.keys(answers).length > 0 ? detectContradictions(answers) : [];
+        // If topic is vague (< 10 words), prepend meta-questions
+        const metaQuestions = isShortTopic(topic)
+            ? generateMetaQuestions()
+            : [];
+        // Generate main clarification questions (cap total at maxQuestions)
+        const mainMaxQ = Math.max(1, maxQuestions - metaQuestions.length);
+        const mainQuestions = generateQuestions(topic, context, knowledge, mainMaxQ);
+        const questions = [...metaQuestions, ...mainQuestions].slice(0, maxQuestions);
+        // Determine if spec is ready (all critical questions have non-empty answers)
+        const criticalIds = questions.filter((q) => q.importance === 'critical').map((q) => q.id);
+        const specReady = answers !== undefined &&
+            criticalIds.every((id) => {
+                const ans = answers[id];
+                return ans !== undefined && ans.trim() !== '';
+            });
+        // Create a clarification session
+        const session = {
+            id: randomUUID().slice(0, 8),
+            projectId,
+            topic,
+            questions,
+            answers: answers ?? {},
+            isComplete: specReady,
+            createdAt: new Date().toISOString(),
+            contradictions: contradictions.length > 0 ? contradictions : undefined,
+            specReady,
+        };
+        // Persist the session
+        await knowledgeStore.addClarification(projectId, session);
+        const result = {
+            sessionId: session.id,
+            topic,
+            questionsCount: questions.length,
+            hasMetaQuestions: metaQuestions.length > 0,
+            questions: questions.map((q) => ({
+                id: q.id,
+                question: q.question,
+                category: q.category,
+                importance: q.importance,
+                suggestedAnswer: q.suggestedAnswer,
+                /* v8 ignore next 1 */
+                suggestedAnswers: q.suggestedAnswers ?? [],
+            })),
+            specReady,
+            instructions: specReady
+                ? 'All critical questions answered. Call create_spec with clarificationSessionId to create a precise spec.'
+                : 'Answer the questions above, then call create_spec with the gathered context. You can skip nice-to-have questions if the user does not have strong opinions.',
+            message: ti('tools.clarify_requirements.success', {
+                count: String(questions.length),
+                topic,
+            }),
+        };
+        if (contradictions.length > 0) {
+            result.contradictions = contradictions;
+            result.contradictionWarning =
+                'Potential contradictions detected in your answers — please review before creating the spec.';
+        }
+        return {
+            content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+            content: [{ type: 'text', text: ti('errors.internalError', { message }) }],
+            isError: true,
+        };
+    }
+}
+//# sourceMappingURL=clarify-requirements.js.map

package/dist/tools/clarify-requirements.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"clarify-requirements.js","sourceRoot":"","sources":["../../src/tools/clarify-requirements.ts"],"names":[],"mappings":"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"}

package/dist/tools/consult-docs.d.ts

@@ -0,0 +1,3 @@
+import type { ConsultDocsInput, ToolResult } from '../types/index.js';
+export declare function handleConsultDocs(args: ConsultDocsInput): Promise<ToolResult>;
+//# sourceMappingURL=consult-docs.d.ts.map

package/dist/tools/consult-docs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"consult-docs.d.ts","sourceRoot":"","sources":["../../src/tools/consult-docs.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,gBAAgB,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAEtE,wBAAsB,iBAAiB,CAAC,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAAC,UAAU,CAAC,CA6EnF"}

package/dist/tools/consult-docs.js

@@ -0,0 +1,74 @@
+// tools/consult-docs.ts — Fetch official documentation
+// Uses web-fetcher engine: consultDocs()
+import { t, ti } from '../i18n/index.js';
+import { knowledgeStore } from '../storage/index.js';
+import { consultDocs } from '../engine/web-fetcher.js';
+export async function handleConsultDocs(args) {
+    const { topic, projectId, framework } = args;
+    const knowledge = await knowledgeStore.getKnowledge(projectId);
+    if (!knowledge) {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: ti('errors.projectNotFound', { projectId }),
+                },
+            ],
+            isError: true,
+        };
+    }
+    // Auto-detect framework from project knowledge if not provided
+    const resolvedFramework = framework ?? knowledge.framework ?? knowledge.language;
+    const result = await consultDocs(topic, resolvedFramework);
+    // Format output
+    const sourceLabel = result.source === 'web' ? 'live' : result.source === 'cache' ? 'cached' : 'offline';
+    const staleNote = result.stale ? ' (stale)' : '';
+    const lines = [
+        `## ${t('tools.consult_docs.description')}`,
+        '',
+        `**Framework:** ${result.framework}`,
+        `**Topic:** ${result.topic}`,
+        `**Source:** ${sourceLabel}${staleNote}`,
+        '',
+        `### Documentation URL`,
+        '',
+        `[${result.framework} docs for "${result.topic}"](${result.docsUrl})`,
+        '',
+        '### Summary',
+        '',
+        result.summary,
+        '',
+    ];
+    if (result.codeExamples.length > 0) {
+        lines.push('### Code Examples');
+        lines.push('');
+        lines.push('```');
+        for (const example of result.codeExamples) {
+            lines.push(example);
+        }
+        lines.push('```');
+        lines.push('');
+    }
+    if (result.bestPractices.length > 0) {
+        lines.push('### Best Practices');
+        lines.push('');
+        for (const practice of result.bestPractices) {
+            lines.push(`- ${practice}`);
+        }
+        lines.push('');
+    }
+    // Additional context from project docs registry
+    if (Object.keys(knowledge.docsRegistry).length > 0) {
+        lines.push('### Project Docs Registry');
+        lines.push('');
+        lines.push('Additional documentation sources configured for this project:');
+        lines.push('');
+        for (const [key, value] of Object.entries(knowledge.docsRegistry)) {
+            lines.push(`- **${key}:** [${value.base}](${value.base})`);
+        }
+    }
+    return {
+        content: [{ type: 'text', text: lines.join('\n') }],
+    };
+}
+//# sourceMappingURL=consult-docs.js.map

package/dist/tools/consult-docs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"consult-docs.js","sourceRoot":"","sources":["../../src/tools/consult-docs.ts"],"names":[],"mappings":"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"}

package/dist/tools/context-budget.d.ts

@@ -0,0 +1,3 @@
+import type { ContextBudgetInput, ToolResult } from '../types/index.js';
+export declare function handleContextBudget(args: ContextBudgetInput): Promise<ToolResult>;
+//# sourceMappingURL=context-budget.d.ts.map

package/dist/tools/context-budget.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-budget.d.ts","sourceRoot":"","sources":["../../src/tools/context-budget.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,kBAAkB,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAaxE,wBAAsB,mBAAmB,CAAC,IAAI,EAAE,kBAAkB,GAAG,OAAO,CAAC,UAAU,CAAC,CAoBvF"}

package/dist/tools/context-budget.js

@@ -0,0 +1,131 @@
+import { getStatus, getWarning, setConfig, getSessionOps, generateCheckpoint, formatCheckpoint, analyzeSession, suggestExplorePrompt, } from '../engine/context-budget/index.js';
+import * as checkpointStore from '../storage/checkpoint-store.js';
+export async function handleContextBudget(args) {
+    switch (args.action) {
+        case 'status':
+            return handleStatus(args.projectId);
+        case 'configure':
+            return handleConfigure(args);
+        case 'checkpoint':
+            return handleCheckpoint(args);
+        case 'restore':
+            return handleRestore(args.projectId, args.checkpointId);
+        case 'list-checkpoints':
+            return handleListCheckpoints(args.projectId, args.limit);
+        case 'optimize':
+            return handleOptimize(args.projectId);
+        default:
+            return {
+                content: [{ type: 'text', text: `Unknown action: ${String(args.action)}` }],
+                isError: true,
+            };
+    }
+}
+async function handleStatus(projectId) {
+    const stored = await checkpointStore.loadConfig(projectId);
+    if (stored) {
+        setConfig(stored);
+    }
+    const status = getStatus();
+    const warning = getWarning();
+    const lines = [
+        `## Context Budget Status`,
+        '',
+        `| Metric | Value |`,
+        `|--------|-------|`,
+        `| Tokens used | ${String(status.tokensEstimatedUsed)} |`,
+        `| Tokens available | ${String(status.tokensEstimatedAvailable)} |`,
+        `| Usage | ${String(status.percentUsed)}% |`,
+        `| Alert level | ${status.alertLevel} |`,
+        `| Operations | ${String(status.operationCount)} |`,
+    ];
+    if (status.topConsumers.length > 0) {
+        lines.push('', '### Top Consumers');
+        for (const c of status.topConsumers) {
+            lines.push(`- **${c.tool}**: ${String(c.tokens)} tokens`);
+        }
+    }
+    if (warning) {
+        lines.push('', `> **Warning**: ${warning.recommendation}`);
+    }
+    return { content: [{ type: 'text', text: lines.join('\n') }] };
+}
+async function handleConfigure(args) {
+    const config = setConfig({
+        ...(args.contextWindowSize !== undefined && { contextWindowSize: args.contextWindowSize }),
+        ...(args.warningThreshold !== undefined && { warningThreshold: args.warningThreshold }),
+        ...(args.criticalThreshold !== undefined && { criticalThreshold: args.criticalThreshold }),
+    });
+    await checkpointStore.saveConfig(args.projectId, config);
+    return {
+        content: [
+            {
+                type: 'text',
+                text: `Context budget configured. Window: ${String(config.contextWindowSize)} tokens, warning: ${String(config.warningThreshold * 100)}%, critical: ${String(config.criticalThreshold * 100)}%`,
+            },
+        ],
+    };
+}
+async function handleCheckpoint(args) {
+    const status = getStatus();
+    const cp = generateCheckpoint(args.projectId, status, {
+        summary: args.summary,
+        decisions: args.decisions,
+        filesModified: args.filesModified,
+        filesRead: args.filesRead,
+        specsInProgress: args.specsInProgress,
+        pendingWork: args.pendingWork,
+    });
+    const id = await checkpointStore.saveCheckpoint(args.projectId, cp);
+    const formatted = formatCheckpoint(cp);
+    return { content: [{ type: 'text', text: `Checkpoint saved: **${id}**\n\n${formatted}` }] };
+}
+async function handleRestore(projectId, checkpointId) {
+    const cp = await checkpointStore.loadCheckpoint(projectId, checkpointId);
+    if (!cp) {
+        return { content: [{ type: 'text', text: 'No checkpoint found.' }], isError: true };
+    }
+    const formatted = formatCheckpoint(cp);
+    return { content: [{ type: 'text', text: `## Restored Checkpoint\n\n${formatted}` }] };
+}
+async function handleListCheckpoints(projectId, limit) {
+    const summaries = await checkpointStore.listCheckpoints(projectId, limit ?? 10);
+    if (summaries.length === 0) {
+        return { content: [{ type: 'text', text: 'No checkpoints found for this project.' }] };
+    }
+    const lines = ['## Available Checkpoints', ''];
+    for (const s of summaries) {
+        lines.push(`- **${s.id}** (${s.timestamp}): ${s.summary}`);
+    }
+    return { content: [{ type: 'text', text: lines.join('\n') }] };
+}
+function handleOptimize(projectId) {
+    const ops = getSessionOps();
+    const status = getStatus();
+    const result = analyzeSession(ops, status);
+    const lines = [
+        `## Context Optimization — ${projectId}`,
+        '',
+        `Current usage: ${String(result.currentUsage.percentUsed)}% (${result.currentUsage.alertLevel})`,
+        '',
+    ];
+    if (result.delegationHints.length > 0) {
+        lines.push('### Delegation Suggestions');
+        for (const hint of result.delegationHints) {
+            lines.push(`- **${hint.operation}**: ${hint.reason} → use \`${hint.suggestedModel}\``);
+        }
+        lines.push('');
+    }
+    if (result.filesAlreadyRead.length > 5) {
+        lines.push('### Batch Read Suggestion');
+        lines.push('Consider delegating file reads to an Explore subagent:');
+        lines.push('```');
+        lines.push(suggestExplorePrompt(result.filesAlreadyRead));
+        lines.push('```');
+    }
+    if (result.delegationHints.length === 0) {
+        lines.push('No optimization suggestions at this time — context usage is efficient.');
+    }
+    return Promise.resolve({ content: [{ type: 'text', text: lines.join('\n') }] });
+}
+//# sourceMappingURL=context-budget.js.map

package/dist/tools/context-budget.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-budget.js","sourceRoot":"","sources":["../../src/tools/context-budget.ts"],"names":[],"mappings":"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"}

package/dist/tools/contribute-context.d.ts

@@ -0,0 +1,13 @@
+import type { ToolResult, RequestContextInput, ContributeContextInput } from '../types/index.js';
+/**
+ * Generate a prompt that the agent presents to the user, asking for
+ * reference documentation (README, PRD, architecture diagrams, etc.).
+ * Sets knowledge.contextRequested = true to prevent repeated prompts.
+ */
+export declare function handleRequestContext(args: RequestContextInput): Promise<ToolResult>;
+/**
+ * Persist structured knowledge that the agent extracted from user documents.
+ * Merges intelligently with existing auto-detected knowledge and reports conflicts.
+ */
+export declare function handleContributeContext(args: ContributeContextInput): Promise<ToolResult>;
+//# sourceMappingURL=contribute-context.d.ts.map

package/dist/tools/contribute-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contribute-context.d.ts","sourceRoot":"","sources":["../../src/tools/contribute-context.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EACV,UAAU,EACV,mBAAmB,EACnB,sBAAsB,EAEvB,MAAM,mBAAmB,CAAC;AAQ3B;;;;GAIG;AACH,wBAAsB,oBAAoB,CAAC,IAAI,EAAE,mBAAmB,GAAG,OAAO,CAAC,UAAU,CAAC,CAyDzF;AAMD;;;GAGG;AACH,wBAAsB,uBAAuB,CAAC,IAAI,EAAE,sBAAsB,GAAG,OAAO,CAAC,UAAU,CAAC,CA4B/F"}