@planu/cli 4.11.1 → 4.11.3

package/dist/tools/schemas/token-intelligence.d.ts

@@ -1,23 +1,23 @@
 import { z } from 'zod';
 export declare const TokenIntelligencePeriodEnum: z.ZodEnum<{
+    all_time: "all_time";
+    month: "month";
     today: "today";
     week: "week";
-    month: "month";
-    all_time: "all_time";
 }>;
 export declare const TokenIntelligenceGroupByEnum: z.ZodEnum<{
+    day: "day";
     model: "model";
     spec: "spec";
     tool: "tool";
-    day: "day";
 }>;
 export declare const TokenIntelligenceViewEnum: z.ZodEnum<{
-    graph: "graph";
-    summary: "summary";
+    autopilot: "autopilot";
     budget: "budget";
     detailed: "detailed";
-    autopilot: "autopilot";
+    graph: "graph";
     reconciliation: "reconciliation";
+    summary: "summary";
     trends: "trends";
 }>;
 //# sourceMappingURL=token-intelligence.d.ts.map

package/dist/tools/schemas/token-optimization.d.ts

@@ -1,9 +1,9 @@
 import { z } from 'zod';
 export declare const TokenUsagePeriodEnum: z.ZodEnum<{
-    today: "today";
+    all_time: "all_time";
     current_session: "current_session";
     last_hour: "last_hour";
-    all_time: "all_time";
+    today: "today";
 }>;
 export declare const TokenUsageGroupByEnum: z.ZodEnum<{
     session: "session";

package/dist/tools/schemas/workers-schema.d.ts

@@ -8,13 +8,13 @@ export declare const ConfigureWorkersInputSchema: z.ZodObject<{
     projectId: z.ZodString;
     workerName: z.ZodString;
     action: z.ZodEnum<{
-        enable: "enable";
+        "add-pattern": "add-pattern";
         disable: "disable";
+        enable: "enable";
+        "enable-auto-memory": "enable-auto-memory";
+        "remove-pattern": "remove-pattern";
         "set-cooldown": "set-cooldown";
         "set-priority": "set-priority";
-        "add-pattern": "add-pattern";
-        "remove-pattern": "remove-pattern";
-        "enable-auto-memory": "enable-auto-memory";
     }>;
     value: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
 }, z.core.$strip>;

package/dist/tools/skill-bootstrap-handler.d.ts

@@ -5,20 +5,20 @@ export declare const DiscoverSkillsInputSchema: {
     stack: z.ZodOptional<z.ZodArray<z.ZodString>>;
     sources: z.ZodOptional<z.ZodArray<z.ZodEnum<{
         "awesome-cursorrules": "awesome-cursorrules";
-        "skills-sh": "skills-sh";
         "github-custom": "github-custom";
+        "skills-sh": "skills-sh";
     }>>>;
 };
 export declare const BootstrapSkillsInputSchema: {
     projectPath: z.ZodString;
     stack: z.ZodOptional<z.ZodArray<z.ZodString>>;
     targets: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+        "agents-md": "agents-md";
         "claude-md": "claude-md";
+        clinerules: "clinerules";
         cursorrules: "cursorrules";
-        windsurfrules: "windsurfrules";
         "kiro-steering": "kiro-steering";
-        "agents-md": "agents-md";
-        clinerules: "clinerules";
+        windsurfrules: "windsurfrules";
     }>>>;
     dryRun: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
 };
@@ -34,12 +34,12 @@ export declare const ConfigureSkillRegistriesInputSchema: {
     enableSource: z.ZodOptional<z.ZodString>;
     disableSource: z.ZodOptional<z.ZodString>;
     setTargets: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+        "agents-md": "agents-md";
         "claude-md": "claude-md";
+        clinerules: "clinerules";
         cursorrules: "cursorrules";
-        windsurfrules: "windsurfrules";
         "kiro-steering": "kiro-steering";
-        "agents-md": "agents-md";
-        clinerules: "clinerules";
+        windsurfrules: "windsurfrules";
     }>>>;
     setAutoMerge: z.ZodOptional<z.ZodBoolean>;
 };

package/dist/tools/suggest-stack.js

@@ -7,20 +7,26 @@ import { adjustRecommendationRanking } from '../engine/self-improver.js';
 export async function handleSuggestStack(args) {
     const { projectType, requirements, constraints = [], projectId } = args;
     // If projectId provided, enrich with project knowledge
-    let contextInfo = '';
+    const projectEvidence = [];
     if (projectId) {
         const knowledge = await knowledgeStore.getKnowledge(projectId);
         if (knowledge) {
-            contextInfo =
-                `\n\n**Project context:** ${knowledge.language}` +
-                    (knowledge.framework ? ` / ${knowledge.framework}` : '') +
-                    ` — architecture: ${knowledge.architecture.primary}` +
-                    ` — database: ${knowledge.database}`;
+            if (knowledge.language !== 'unknown') {
+                projectEvidence.push(`language=${knowledge.language}`);
+            }
+            if (knowledge.framework) {
+                projectEvidence.push(`framework=${knowledge.framework}`);
+            }
+            projectEvidence.push(`architecture=${knowledge.architecture.primary}`);
+            if (knowledge.database !== 'unknown') {
+                projectEvidence.push(`database=${knowledge.database}`);
+            }
         }
     }
     // SPEC-012: Load developer preferences to adjust recommendation ranking
     const developerPrefs = await globalStore.getDeveloperPreferences();
     const result = await suggestStack(projectType, requirements, constraints);
+    const grounding = result;
     // Apply developer preference rankings to ecosystem items
     const ecosystemItems = [...result.primary.ecosystem, ...result.alternative.ecosystem];
     const rankings = adjustRecommendationRanking(ecosystemItems, developerPrefs);
@@ -28,11 +34,14 @@ export async function handleSuggestStack(args) {
     const rejectedItems = [...rankings.entries()]
         .filter(([, score]) => score < -1)
         .map(([tool]) => tool);
-    // Format primary recommendation
+    // Recommendations remain candidates until the user confirms a choice.
     const primaryLines = [
         `## ${t('tools.suggest_stack.description')}`,
         '',
-        '### Primary Recommendation',
+        grounding.candidateNotice ??
+            'Recommendations are optional candidates. This tool does not select or persist a stack.',
+        '',
+        '### Candidate A (unconfirmed)',
         '',
         `| Aspect | Value |`,
         `|--------|-------|`,
@@ -48,10 +57,10 @@ export async function handleSuggestStack(args) {
         '',
         `**Ecosystem:** ${result.primary.ecosystem.join(', ')}`,
     ].filter(Boolean);
-    // Format alternative
+    // Format alternative candidate
     const altLines = [
         '',
-        '### Alternative Recommendation',
+        '### Candidate B (unconfirmed)',
         '',
         `| Aspect | Value |`,
         `|--------|-------|`,
@@ -67,10 +76,10 @@ export async function handleSuggestStack(args) {
         '',
         `**Ecosystem:** ${result.alternative.ecosystem.join(', ')}`,
     ].filter(Boolean);
-    // Why not others
+    // Other optional candidates
     const whyNotLines = [
         '',
-        '### Why Not Others',
+        '### Other Candidates Considered',
         '',
         ...result.whyNotOthers.map((w) => `- **${w.name}:** ${w.reason}`),
     ];
@@ -86,18 +95,45 @@ export async function handleSuggestStack(args) {
     const prefsNote = rejectedItems.length > 0
         ? `\n\n> **Note:** Based on your preferences, these were previously rejected: ${rejectedItems.join(', ')}`
         : '';
+    const detectedEvidence = [
+        ...projectEvidence.map((item) => `project:${item}`),
+        ...(grounding.detectedEvidence ?? []),
+    ];
+    const evidenceLines = [
+        '',
+        '### Detected Evidence',
+        '',
+        ...(detectedEvidence.length > 0
+            ? detectedEvidence.map((item) => `- ${item}`)
+            : ['- No stack evidence was detected.']),
+        '',
+        '### User-Confirmed Choices',
+        '',
+        ...((grounding.confirmedChoices ?? []).length > 0
+            ? (grounding.confirmedChoices ?? []).map((choice) => `- ${choice.field}: ${choice.value}`)
+            : ['- None.']),
+    ];
     const text = [
         ...primaryLines,
         ...altLines,
         ...whyNotLines,
         ...mcpLines,
-        contextInfo,
+        ...evidenceLines,
         prefsNote,
         '',
         `_Last checked: ${result.lastChecked}_`,
     ].join('\n');
     return {
         content: [{ type: 'text', text }],
+        structuredContent: {
+            selectionStatus: grounding.selectionStatus ?? 'unconfirmed',
+            detectedEvidence,
+            confirmedChoices: grounding.confirmedChoices ?? [],
+            candidates: [
+                { id: 'candidate-a', status: 'candidate', stack: result.primary },
+                { id: 'candidate-b', status: 'candidate', stack: result.alternative },
+            ],
+        },
     };
 }
 //# sourceMappingURL=suggest-stack.js.map

package/dist/tools/tool-registry/deprecated-stubs.d.ts

@@ -5,7 +5,7 @@ export declare const DEPRECATION_MESSAGE_TEMPLATE = "This tool has been migrated
  * The 5 MCP tool names that have been migrated to skills.
  * Used in smoke tests (Scenario 6) and anywhere a guard on migrated tools is needed.
  */
-export declare const DEPRECATED_TOOLS: readonly ["execute_sdd_flow", "implement_plan", "multi_teammate_review", "run_healing_loop", "generate_orchestration_plan"];
+export declare const DEPRECATED_TOOLS: readonly ['execute_sdd_flow', 'implement_plan', 'multi_teammate_review', 'run_healing_loop', 'generate_orchestration_plan'];
 export type DeprecatedToolName = (typeof DEPRECATED_TOOLS)[number];
 /**
  * Create a ToolEntry-compatible deprecation stub.

package/dist/tools/triage-request.d.ts

@@ -5,11 +5,11 @@ export declare const TriageRequestInputSchema: z.ZodObject<{
     sessionId: z.ZodOptional<z.ZodString>;
     hint: z.ZodOptional<z.ZodObject<{
         kind: z.ZodOptional<z.ZodEnum<{
-            idea: "idea";
-            "quick-fix": "quick-fix";
             "bug-spec": "bug-spec";
-            "feature-spec": "feature-spec";
             epic: "epic";
+            "feature-spec": "feature-spec";
+            idea: "idea";
+            "quick-fix": "quick-fix";
         }>>;
     }, z.core.$strip>>;
     projectId: z.ZodOptional<z.ZodString>;

package/dist/tools/update-status/dod-gates.d.ts

@@ -30,6 +30,13 @@ export type ValidateGateResult = {
     forcedReason: string;
     scoreSource: 'forced-best-effort-validateSpec';
 };
+export type ValidationReportGateResult = {
+    ok: true;
+    score: number | null;
+} | {
+    ok: false;
+    error: ToolResult;
+};
 /**
  * SPEC-721 / SPEC-222 Trigger 1: Run validate engine before marking done.
  *
@@ -79,6 +86,7 @@ export interface DoneGateResult {
  * with reviewer evidence and all validation gates passing.
  */
 export declare function checkValidationReportGate(specId: string, projectId: string, force: boolean | undefined): Promise<ToolResult | null>;
+export declare function readApprovedValidationReportGate(specId: string, projectId: string, force: boolean | undefined): Promise<ValidationReportGateResult>;
 /** SPEC-1051: Write spec-review evidence when a spec enters review. */
 export declare function writeSpecReviewArtifact(spec: Spec, specId: string, projectId: string): Promise<ToolResult | null>;
 /** SPEC-1051: Approval requires a dedicated spec reviewer artifact. */

package/dist/tools/update-status/dod-gates.js

@@ -280,8 +280,12 @@ async function recordForceDoneBypass(specId, projectId, reason, failingItems, wa
  * with reviewer evidence and all validation gates passing.
  */
 export async function checkValidationReportGate(specId, projectId, force) {
+    const result = await readApprovedValidationReportGate(specId, projectId, force);
+    return result.ok ? null : result.error;
+}
+export async function readApprovedValidationReportGate(specId, projectId, force) {
     if (force) {
-        return null;
+        return { ok: true, score: null };
     }
     try {
         const { readArtifact } = await import('../../engine/handoff-artifacts/io.js');
@@ -289,60 +293,81 @@ export async function checkValidationReportGate(specId, projectId, force) {
         if (!result.ok) {
             const firstErr = result.errors[0];
             if (firstErr?.code === 'ARTIFACT_NOT_FOUND') {
-                return validationReportGateError({
+                return {
+                    ok: false,
+                    error: validationReportGateError({
+                        specId,
+                        error: 'validation_report_missing',
+                        message: 'No validation-report artifact exists for this spec. Run validate to generate implementation-review evidence before marking done.',
+                        gates: [],
+                        fixHint: 'Run validate for this spec, fix any failing gates, then retry update_status(done). Use force:true only with an audited reason.',
+                    }),
+                };
+            }
+            return {
+                ok: false,
+                error: validationReportGateError({
                     specId,
-                    error: 'validation_report_missing',
-                    message: 'No validation-report artifact exists for this spec. Run validate to generate implementation-review evidence before marking done.',
+                    error: 'validation_report_invalid',
+                    message: 'The validation-report artifact is malformed or uses an obsolete schema. Re-run validate so Planu can generate reviewer evidence.',
                     gates: [],
-                    fixHint: 'Run validate for this spec, fix any failing gates, then retry update_status(done). Use force:true only with an audited reason.',
-                });
-            }
-            return validationReportGateError({
-                specId,
-                error: 'validation_report_invalid',
-                message: 'The validation-report artifact is malformed or uses an obsolete schema. Re-run validate so Planu can generate reviewer evidence.',
-                gates: [],
-                fixHint: 'Re-run validate for this spec. The report must include reviewer evidence and passing gates.',
-            });
+                    fixHint: 'Re-run validate for this spec. The report must include reviewer evidence and passing gates.',
+                }),
+            };
         }
         if (!result.payload.passed) {
-            return validationReportGateError({
-                specId,
-                error: 'validation_report_failed',
-                message: 'Validation report has passed:false — fix all failing gates before marking done.',
-                gates: result.payload.gates,
-                fixHint: 'Fix failing gates and re-run validate before marking done.',
-            });
+            return {
+                ok: false,
+                error: validationReportGateError({
+                    specId,
+                    error: 'validation_report_failed',
+                    message: 'Validation report has passed:false — fix all failing gates before marking done.',
+                    gates: result.payload.gates,
+                    fixHint: 'Fix failing gates and re-run validate before marking done.',
+                }),
+            };
         }
         if (result.payload.minimalityReport?.blocked) {
-            return validationReportGateError({
-                specId,
-                error: 'minimality_findings_block_done',
-                message: 'Validation report contains blocking minimal implementation findings. Remove avoidable complexity or provide an audited forceStatusReason.',
-                gates: result.payload.gates,
-                fixHint: 'Fix blocking minimality findings and re-run validate before marking done. Use forceStatus only with an audited reason for accepted complexity.',
-            });
+            return {
+                ok: false,
+                error: validationReportGateError({
+                    specId,
+                    error: 'minimality_findings_block_done',
+                    message: 'Validation report contains blocking minimal implementation findings. Remove avoidable complexity or provide an audited forceStatusReason.',
+                    gates: result.payload.gates,
+                    fixHint: 'Fix blocking minimality findings and re-run validate before marking done. Use forceStatus only with an audited reason for accepted complexity.',
+                }),
+            };
         }
         if (result.payload.reviewer.verdict !== 'approved' ||
             result.payload.reviewer.agent.trim().length === 0) {
-            return validationReportGateError({
-                specId,
-                error: 'validation_report_reviewer_not_approved',
-                message: 'The implementation reviewer did not approve this spec. Fix the requested changes and re-run validate.',
-                gates: result.payload.gates,
-                fixHint: 'Fix reviewer findings and re-run validate before marking done.',
-            });
+            return {
+                ok: false,
+                error: validationReportGateError({
+                    specId,
+                    error: 'validation_report_reviewer_not_approved',
+                    message: 'The implementation reviewer did not approve this spec. Fix the requested changes and re-run validate.',
+                    gates: result.payload.gates,
+                    fixHint: 'Fix reviewer findings and re-run validate before marking done.',
+                }),
+            };
         }
-        return null;
+        return {
+            ok: true,
+            score: typeof result.payload.score === 'number' ? result.payload.score : null,
+        };
     }
     catch (err) {
-        return validationReportGateError({
-            specId,
-            error: 'validation_report_unreadable',
-            message: `Could not read validation-report artifact: ${err instanceof Error ? err.message : String(err)}`,
-            gates: [],
-            fixHint: 'Re-run validate for this spec, then retry update_status(done).',
-        });
+        return {
+            ok: false,
+            error: validationReportGateError({
+                specId,
+                error: 'validation_report_unreadable',
+                message: `Could not read validation-report artifact: ${err instanceof Error ? err.message : String(err)}`,
+                gates: [],
+                fixHint: 'Re-run validate for this spec, then retry update_status(done).',
+            }),
+        };
     }
 }
 /** SPEC-1051: Write spec-review evidence when a spec enters review. */

package/dist/tools/update-status/file-sync.d.ts

@@ -10,7 +10,7 @@ export interface FrontmatterSyncWarning {
     specPath: string | null;
     reason: string;
 }
-export declare function syncSpecFiles(updatedSpec: Spec, currentStatus: SpecStatus, newStatus: SpecStatus, projectPath?: string): Promise<{
+export declare function syncSpecFiles(updatedSpec: Spec, _currentStatus: SpecStatus, newStatus: SpecStatus, projectPath?: string): Promise<{
     warning?: FrontmatterSyncWarning;
 }>;
 export declare function tryReconcile(newStatus: string, specId: string, projectId: string): Promise<string | null>;

package/dist/tools/update-status/file-sync.js

@@ -2,14 +2,15 @@ import { calculateAccuracy } from '../../engine/estimator.js';
 import { metricsStore } from '../../storage/index.js';
 import { addLesson, getLessons } from '../../storage/lessons-store.js';
 import { dispatchFeedbackEvent } from '../learn.js';
-import { generateProgressUpdate } from '../../engine/progress-writer.js';
 import { autoReconcileOnDone } from '../update-status-reconcile.js';
 import { readFile, writeFile } from 'node:fs/promises';
-import { replaceSectionInSpec } from '../../engine/spec-format/replace-section.js';
 import { parseFrontmatter } from '../../engine/frontmatter-parser.js';
 import { computeFrontmatterSha } from '../../engine/frontmatter-sha/index.js';
 import { appendTransitionEvent } from '../../storage/transition-log.js';
 export async function recordDoneMetrics(projectId, specId, spec, actuals, projectPath) {
+    if (actuals.devHours + actuals.reviewHours === 0) {
+        return;
+    }
     const accuracyScore = calculateAccuracy(spec.estimation, actuals.devHours + actuals.reviewHours);
     const metricEntry = {
         specId,
@@ -19,7 +20,7 @@ export async function recordDoneMetrics(projectId, specId, spec, actuals, projec
         accuracyScore,
     };
     await metricsStore.addMetricEntry(projectId, metricEntry);
-    if (accuracyScore < 0.7 || accuracyScore > 1.3) {
+    if (accuracyScore < 70) {
         void dispatchFeedbackEvent(projectId, {
             type: 'validate',
             specId,
@@ -29,13 +30,13 @@ export async function recordDoneMetrics(projectId, specId, spec, actuals, projec
                 estimatedHours: spec.estimation.devHours + spec.estimation.reviewHours,
                 actualHours: actuals.devHours + actuals.reviewHours,
             },
-            delta: { accuracyDrift: Math.abs(1 - accuracyScore) },
+            delta: { accuracyDrift: Math.abs(100 - accuracyScore) },
             timestamp: new Date().toISOString(),
         }).catch((err) => {
             console.error('[planu] dispatchFeedbackEvent failed:', err);
         });
     }
-    if (accuracyScore < 0.7 && projectPath) {
+    if (accuracyScore < 70 && projectPath) {
         void autoCaptureLessonEstimation(spec, actuals, accuracyScore, projectId, projectPath);
     }
 }
@@ -51,14 +52,14 @@ async function autoCaptureLessonEstimation(spec, actuals, accuracy, projectId, p
         }
         const estimatedHours = spec.estimation.devHours + spec.estimation.reviewHours;
         const actualHours = actuals.devHours + actuals.reviewHours;
-        const severity = accuracy < 0.6 ? 'high' : 'medium';
+        const severity = accuracy < 60 ? 'high' : 'medium';
         await addLesson(projectPath, {
             projectId,
             specId: spec.id,
             category: 'estimation',
             severity,
             title: `Estimation miss on ${spec.title}`,
-            description: `Spec took ${String(actualHours)}h actual vs ${String(estimatedHours)}h estimated (${String(Math.round(accuracy * 100))}% accuracy)`,
+            description: `Spec took ${String(actualHours)}h actual vs ${String(estimatedHours)}h estimated (${String(Math.round(accuracy))}% accuracy)`,
             prevention: 'Review complexity and scope assumptions before estimating similar specs',
             tags: [...spec.tags, 'auto-captured', 'estimation'],
         });
@@ -90,7 +91,7 @@ function assertSpecBodyIntegrity(args) {
         throw new Error(`SPEC_INTEGRITY_WRITE_FAILED: refusing to write ${args.specId} because update_status(${args.newStatus}) would shrink spec.md body by ${String(lost)} characters without an explicit migration marker.`);
     }
 }
-export async function syncSpecFiles(updatedSpec, currentStatus, newStatus, projectPath) {
+export async function syncSpecFiles(updatedSpec, _currentStatus, newStatus, projectPath) {
     let warning;
     if (updatedSpec.specPath) {
         try {
@@ -145,21 +146,6 @@ export async function syncSpecFiles(updatedSpec, currentStatus, newStatus, proje
         console.warn(`[Planu] update_status: ${reason} (${updatedSpec.id})`);
         warning = { specId: updatedSpec.id, specPath: null, reason };
     }
-    // SPEC-1010 PR-C: Write progress into the unified spec.md ## Progress section
-    // instead of a standalone progress.md file. We do this only when specPath is
-    // known (which it always is for specs that reach syncSpecFiles).
-    if (updatedSpec.specPath) {
-        try {
-            const existing = await readFile(updatedSpec.specPath, 'utf-8');
-            // Extract current ## Progress body (may be empty for new lean specs)
-            const progressBody = extractProgressBody(existing);
-            const updatedProgress = generateProgressUpdate(updatedSpec, currentStatus, progressBody);
-            await replaceSectionInSpec(updatedSpec.specPath, 'Progress', updatedProgress);
-        }
-        catch {
-            // best-effort — never blocks the transition
-        }
-    }
     return warning ? { warning } : {};
 }
 /** Flip all `    done: false` lines to `    done: true` in spec content.
@@ -169,7 +155,7 @@ function markAllCriteriaDone(content) {
 }
 /** True when content is a lean-format spec (has a `criteria:` key in the frontmatter). */
 function isLeanSpecContent(content) {
-    return /^criteria:/m.test(content);
+    return /^criteria:[ \t]*(?:#.*)?\r?\n(?:[ \t]*\r?\n)*[ \t]+-\s+text:/m.test(content);
 }
 /**
  * SPEC-630: Remove done criteria entries from lean spec and annotate the count on the criteria key.
@@ -183,27 +169,6 @@ function stripDoneCriteria(content) {
     });
     return stripped.replace(/^(criteria:)(\s*#.*)?$/m, `$1 # ${String(doneCount)} done`);
 }
-/**
- * Extract the body of the `## Progress` section from spec.md content.
- * Returns "" when the section is absent so callers get a clean empty string.
- * Mirrors the extractSectionBody logic without importing from spec-format to
- * keep this module's dependency chain flat.
- */
-function extractProgressBody(specContent) {
-    const normalized = specContent.replace(/\r\n/g, '\n');
-    // Mask fenced code blocks so inner markdown headings are not matched
-    const masked = normalized.replace(/(```|~~~)[\s\S]*?\1/g, (block) => block.replace(/[^\n]/g, ' '));
-    const headingMatch = /^##\s+Progress\b.*$/m.exec(masked);
-    if (!headingMatch) {
-        return '';
-    }
-    const afterHeading = headingMatch.index + headingMatch[0].length;
-    const nextRe = /^##\s+\S/gm;
-    nextRe.lastIndex = afterHeading;
-    const next = nextRe.exec(masked);
-    const end = next ? next.index : normalized.length;
-    return normalized.slice(afterHeading, end).trim();
-}
 export async function tryReconcile(newStatus, specId, projectId) {
     if (newStatus !== 'done') {
         return null;