@planu/cli 4.11.2 → 4.11.3

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+## [4.11.3] - 2026-07-10
+
+### Bug Fixes
+- fix(release): classify npm 404 visibility correctly
+- fix(planu): harden release and grounded spec flow
+
+
 ## [4.11.2] - 2026-07-10
 
 ### Bug Fixes

package/dist/config/elicitation-questions.json

@@ -2,8 +2,7 @@
   {
     "id": "users",
     "category": "users",
-    "questionTemplate": "Who are the primary users of \"{title}\"?",
-    "hint": "e.g., \"authenticated users\", \"admin only\", \"all visitors\"",
+    "questionTemplate": "Which actors, systems, or processes are explicitly in scope for \"{title}\"?",
     "required": true,
     "answerType": "text",
     "condition": "always"
@@ -11,8 +10,7 @@
   {
     "id": "success",
     "category": "success",
-    "questionTemplate": "How will you know when this feature is successfully implemented?",
-    "hint": "Describe the outcome from the user's perspective",
+    "questionTemplate": "Which explicit observations or checks will prove that \"{title}\" is complete?",
     "required": true,
     "answerType": "text",
     "condition": "always"
@@ -34,8 +32,7 @@
   {
     "id": "edge_cases",
     "category": "behavior",
-    "questionTemplate": "What should happen in error or edge cases?",
-    "hint": "e.g., \"show error message\", \"redirect to login\", \"fail silently\"",
+    "questionTemplate": "Which failure conditions are explicitly in scope?",
     "required": false,
     "answerType": "text",
     "condition": "always"
@@ -43,8 +40,7 @@
   {
     "id": "data",
     "category": "data",
-    "questionTemplate": "What data needs to be stored or retrieved for this feature?",
-    "hint": "List the key fields/entities involved",
+    "questionTemplate": "Does this request require a confirmed data change? If yes, describe only the known data boundary.",
     "required": false,
     "answerType": "text",
     "condition": "data",
@@ -53,18 +49,10 @@
   {
     "id": "api_contract",
     "category": "constraints",
-    "questionTemplate": "Does this require a new API endpoint or changes to existing ones?",
+    "questionTemplate": "Does this request explicitly require an API contract change?",
     "required": false,
     "answerType": "yes-no",
     "condition": "api",
     "conditionKeywords": ["api", "endpoint"]
-  },
-  {
-    "id": "performance",
-    "category": "constraints",
-    "questionTemplate": "Are there performance requirements (response time, load, etc.)?",
-    "required": false,
-    "answerType": "text",
-    "condition": "always"
   }
 ]

package/dist/engine/elicitation/question-generator.js

@@ -46,13 +46,20 @@ function shouldInclude(config, lowerDesc, context) {
         if (context?.hasDatabase === true) {
             return true;
         }
-        return (config.conditionKeywords ?? []).some((kw) => lowerDesc.includes(kw));
+        return (config.conditionKeywords ?? []).some((keyword) => hasAffirmedKeyword(lowerDesc, keyword));
     }
     // condition === 'api' is the only remaining case
     if (context?.isApi === true) {
         return true;
     }
-    return (config.conditionKeywords ?? []).some((kw) => lowerDesc.includes(kw));
+    return (config.conditionKeywords ?? []).some((keyword) => hasAffirmedKeyword(lowerDesc, keyword));
+}
+const NEGATION_RE = /\b(?:no|not|never|without|exclude|excluding|forbid|forbidden|avoid|must not|should not|do not|does not|don't|doesn't|out[- ]of[- ]scope)\b/i;
+function hasAffirmedKeyword(description, keyword) {
+    return description.split(/(?:\r?\n|[.;!?]+)/).some((segment) => {
+        const index = segment.indexOf(keyword.toLowerCase());
+        return index >= 0 && !NEGATION_RE.test(segment.slice(0, index));
+    });
 }
 /** Generate standard clarification questions for a feature spec */
 export function generateSpecQuestions(title, description, context) {
@@ -101,7 +108,7 @@ export function formatQuestionsAsPrompt(session) {
         lines.push('');
     });
     lines.push('---');
-    lines.push('*Reply with your answers (e.g., "1. Admin users 2. User sees dashboard with charts...")*');
+    lines.push('*Reply with numbered answers that reflect only confirmed requirements.*');
     return lines.join('\n');
 }
 /** Parse answers from free-form text (numbered list format) */

package/dist/engine/implementation-contract/renderer.js

@@ -1,43 +1,33 @@
 import { hasImplementationContract, IMPLEMENTATION_CONTRACT_SECTION } from './common.js';
 export function buildImplementationContractSection(input) {
-    const criteria = input.criteria.length > 0 ? input.criteria : fallbackCriteria();
+    const criteria = input.criteria;
     const testFiles = input.files.test.map((file) => file.path);
-    const verificationCommands = input.verificationCommands.length > 0
-        ? input.verificationCommands
-        : ['pnpm typecheck', 'pnpm lint', 'pnpm test'];
+    const verificationCommands = input.verificationCommands;
     const lines = [
         `## ${IMPLEMENTATION_CONTRACT_SECTION}`,
         '### User Outcome',
         firstConcreteSentence(input.description) ??
-            'Needs decision: define the exact user-visible outcome this spec must deliver.',
+            'Needs decision: define the exact observable outcome this spec must deliver.',
         '',
         '### Behavior Contract',
         ...renderBehaviorContract(criteria),
-        '- Inputs: use the user request and existing project conventions as the source of truth.',
-        '- Outputs: update canonical `spec.md` behavior without creating sidecar implementation docs.',
-        '- State changes: persist only the files and metadata required by the spec workflow.',
-        '- Errors: missing implementation detail must surface as `Needs decision:` instead of generic filler.',
         '',
         '### File-Level Work Plan',
         ...renderFilePlan(input.files),
         '',
-        '### Minimal Change Guidance',
-        ...renderMinimalChangeGuidance(),
-        '',
         '### Acceptance-To-Verification Map',
         ...criteria.map((criterion, index) => renderVerificationRow(criterion.text, index + 1, testFiles, verificationCommands)),
         '',
         '### Edge Cases And Failure Modes',
-        '- Generated specs with too little context must use `Needs decision:` placeholders.',
-        '- Existing specs without this section must remain readable and must not be rewritten by readiness checks.',
-        '- A heading with filler text must not count as a usable implementation contract.',
-        '- Manual verification must include exact observable steps when no automated proof is practical.',
+        '- Needs decision: identify criterion-specific failure modes from user input or project evidence.',
         '',
         '### Non-Goals And Forbidden Approaches',
         ...renderNonGoals(input.outOfScope),
         '',
         '### Verification Commands',
-        ...verificationCommands.map((command) => `- \`${command}\``),
+        ...(verificationCommands.length > 0
+            ? verificationCommands.map((command) => `- \`${command}\``)
+            : ['- Needs decision: provide a repository-supported verification command.']),
         '',
     ];
     return lines.join('\n');
@@ -48,21 +38,6 @@ export function appendImplementationContractIfMissing(specBody, input) {
     }
     return `${specBody.trimEnd()}\n\n${buildImplementationContractSection(input)}`;
 }
-function renderMinimalChangeGuidance() {
-    return [
-        '- Before implementing, check whether the work is unnecessary, already exists in this codebase, is covered by stdlib, is covered by the native platform, or is covered by an already-installed dependency.',
-        '- Add new code only after those checks, and keep the diff to the minimum that satisfies the accepted criteria.',
-        '- Do not use minimality to remove security, trust-boundary validation, data-loss handling, accessibility, explicit requirements, or required validation.',
-    ];
-}
-function fallbackCriteria() {
-    return [
-        {
-            text: 'Needs decision: define at least one acceptance criterion with executable verification.',
-            done: false,
-        },
-    ];
-}
 function firstConcreteSentence(description) {
     const body = description
         .replace(/^---[\s\S]*?---/, '')
@@ -89,20 +64,23 @@ function renderFilePlan(files) {
     return lines.length > 0 ? lines : ['- Needs decision: identify expected source and test files.'];
 }
 function renderBehaviorContract(criteria) {
-    return criteria.map((criterion, index) => `- Expected behavior AC${String(index + 1)}: ${criterion.text}`);
+    return criteria.length > 0
+        ? criteria.map((criterion, index) => `- Expected behavior AC${String(index + 1)}: ${criterion.text}`)
+        : ['- Needs decision: define at least one evidence-grounded acceptance criterion.'];
 }
 function renderVerificationRow(criterion, index, testFiles, commands) {
     const test = testFiles[0];
     if (test) {
-        return `- AC${String(index)}: ${criterion} -> unit test \`${test}\` plus \`${commands[0] ?? 'pnpm test'}\`.`;
+        const command = commands[0];
+        return command
+            ? `- AC${String(index)}: ${criterion} -> unit test \`${test}\` plus \`${command}\`.`
+            : `- AC${String(index)}: ${criterion} -> unit test \`${test}\`.`;
     }
     return `- AC${String(index)}: ${criterion} -> Needs decision: choose unit test, integration test, CLI/tool result, snapshot/golden fixture, or exact manual verification.`;
 }
 function renderNonGoals(outOfScope) {
-    const base = [
-        '- Do not create durable sidecar implementation docs outside canonical `spec.md`.',
-        '- Do not treat headings or filler text as implementation-ready detail.',
-    ];
-    return outOfScope.length > 0 ? [...base, ...outOfScope.map((item) => `- ${item}`)] : base;
+    return outOfScope.length > 0
+        ? outOfScope.map((item) => `- ${item}`)
+        : ['- Needs decision: provide explicit non-goals or confirm that none were supplied.'];
 }
 //# sourceMappingURL=renderer.js.map

package/dist/engine/lifecycle-hints.d.ts

@@ -3,7 +3,7 @@ import type { SpecStatus, NextAction, LifecycleMap } from '../types/index.js';
  * Returns the guided next action for a given status transition.
  * The hint targets the *newStatus* reached, guiding what to do from there.
  */
-export declare function buildNextAction(newStatus: SpecStatus): NextAction;
+export declare function buildNextAction(newStatus: SpecStatus): NextAction | null;
 /**
  * Returns the lifecycle map for the given current status.
  * Shows where the spec is, what's next, and what remains.

package/dist/engine/lifecycle-hints.js

@@ -2,53 +2,37 @@
 const LIFECYCLE_STAGES = ['draft', 'review', 'approved', 'implementing', 'done'];
 /** Maps each forward transition to a guided next action */
 const NEXT_ACTION_MAP = {
+    draft: {
+        step: 'Challenge the spec',
+        prompt: 'Run challenge_spec and resolve the discovered findings before review',
+        suggestedCommand: 'challenge_spec(specId)',
+        whenToDoIt: 'Before requesting review',
+    },
     review: {
         step: 'Get approval',
         prompt: "Share this plan with your team or just tell me 'approved' to move forward",
-        suggestedCommand: 'update_status(approved)',
+        suggestedCommand: 'update_status(status="approved")',
         whenToDoIt: "When you're happy with the plan",
     },
     approved: {
-        step: 'Create your git branch',
-        prompt: 'Run: git checkout -b feat/<spec-slug>',
-        suggestedCommand: 'manage_git(branch)',
+        step: 'Start implementation',
+        prompt: 'Move the approved spec to implementing before writing production code',
+        suggestedCommand: 'update_status(status="implementing")',
         whenToDoIt: 'Before writing any code',
     },
     implementing: {
-        step: 'Start coding',
-        prompt: 'Implement the spec following the technical plan',
-        suggestedCommand: 'validate(specId)',
-        whenToDoIt: 'While developing',
-    },
-    done: {
-        step: 'Validate your implementation',
-        prompt: 'Run validate to check that your code matches the spec',
+        step: 'Validate the implementation',
+        prompt: 'Check the implementation against every acceptance criterion',
         suggestedCommand: 'validate(specId)',
         whenToDoIt: 'After all tests pass',
     },
-    discarded: {
-        step: 'Archive or delete spec',
-        prompt: 'This spec has been discarded. You can delete it or keep it for reference.',
-        suggestedCommand: 'delete_spec(specId)',
-        whenToDoIt: 'When cleanup is needed',
-    },
 };
 /**
  * Returns the guided next action for a given status transition.
  * The hint targets the *newStatus* reached, guiding what to do from there.
  */
 export function buildNextAction(newStatus) {
-    const hint = NEXT_ACTION_MAP[newStatus];
-    if (hint !== undefined) {
-        return hint;
-    }
-    // Fallback for any unrecognised status
-    return {
-        step: 'Continue',
-        prompt: `Spec is now ${newStatus}. Check Planu for next steps.`,
-        suggestedCommand: 'list_specs()',
-        whenToDoIt: 'When ready',
-    };
+    return NEXT_ACTION_MAP[newStatus] ?? null;
 }
 /**
  * Returns the lifecycle map for the given current status.

package/dist/engine/spec-format/lean-spec-generator.d.ts

@@ -2,7 +2,7 @@ import type { LeanCriterion, LeanSpecInput } from '../../types/index.js';
 export type { LeanCriterion, LeanHistoryEntry, LeanSpecInput } from '../../types/index.js';
 /** Generate lean spec.md content: YAML frontmatter + user description only. */
 export declare function generateLeanSpecContent(input: LeanSpecInput): string;
-/** Extract acceptance criteria from description. Looks for checkbox patterns or generates a default.
- * Priority: checkboxes > GIVEN/WHEN/THEN > plain list items > fallback. */
+/** Extract acceptance criteria explicitly present in the description.
+ * Priority: checkboxes > GIVEN/WHEN/THEN > plain list items. */
 export declare function extractCriteria(description: string): LeanCriterion[];
 //# sourceMappingURL=lean-spec-generator.d.ts.map

package/dist/engine/spec-format/lean-spec-generator.js

@@ -128,8 +128,8 @@ function buildBddLines(description, extraCriteria, criteriaOverride, scenarioTes
     }
     return renderBddScenariosYaml(scenarios);
 }
-/** Extract acceptance criteria from description. Looks for checkbox patterns or generates a default.
- * Priority: checkboxes > GIVEN/WHEN/THEN > plain list items > fallback. */
+/** Extract acceptance criteria explicitly present in the description.
+ * Priority: checkboxes > GIVEN/WHEN/THEN > plain list items. */
 export function extractCriteria(description) {
     const checkboxCriteria = extractCheckboxCriteria(description);
     if (checkboxCriteria.length > 0) {
@@ -143,12 +143,7 @@ export function extractCriteria(description) {
     if (plainListCriteria.length > 0) {
         return plainListCriteria;
     }
-    return [
-        {
-            text: 'Define acceptance criteria — autopilot could not infer testable behavior from the description',
-            done: false,
-        },
-    ];
+    return [];
 }
 /** Extract checkbox-style criteria: `- [ ] text` or `- [x] text`. */
 function extractCheckboxCriteria(description) {
@@ -198,16 +193,20 @@ function extractGivenWhenThenCriteria(description) {
 /** Extract plain list items: `- text` or `* text` (no checkboxes).
  * Only used when no checkboxes or GIVEN/WHEN/THEN are found. */
 function extractPlainListCriteria(description) {
+    const acceptanceSection = /(?:^|\n)#{1,6}[ \t]+Acceptance Criteria[ \t]*\r?\n([\s\S]*?)(?=\r?\n#{1,6}[ \t]+|$)/i.exec(description)?.[1] ?? '';
+    if (acceptanceSection.length === 0) {
+        return [];
+    }
     const criteria = [];
     // Plain list: `- text` or `* text`, not followed by `[`
     const plainListRegex = /^[-*]\s+(?!\[)(.+)$/gm;
-    let match = plainListRegex.exec(description);
+    let match = plainListRegex.exec(acceptanceSection);
     while (match) {
         const text = match[1]?.trim() ?? '';
         if (text) {
             criteria.push({ text, done: false });
         }
-        match = plainListRegex.exec(description);
+        match = plainListRegex.exec(acceptanceSection);
     }
     return criteria;
 }

package/dist/engine/spec-generator/fallback-generator.js

@@ -1,15 +1,19 @@
+import { extractCriteria } from '../spec-format/lean-spec-generator.js';
 export class FallbackGenerator {
     generate(request) {
-        const sourceDescription = normalizeSourceDescription(request.description, request.title);
-        const contextLine = buildContextLine(request);
+        const sourceDescription = normalizeSourceDescription(request.description);
+        const hasCriteria = extractCriteria(sourceDescription).length > 0;
         const technicalSection = '';
         const specBody = [
             '## Problem',
             sourceDescription,
-            '',
-            '## Solution',
-            'Use the preserved source description above as the authoritative requirements body.',
-            contextLine,
+            ...(hasCriteria
+                ? []
+                : [
+                    '',
+                    '## Missing Decisions',
+                    'Needs decision: provide at least one explicit, verifiable acceptance criterion.',
+                ]),
         ].join('\n');
         return Promise.resolve({
             specBody,
@@ -19,28 +23,17 @@ export class FallbackGenerator {
                 generatedAt: new Date().toISOString(),
             },
             qualityWarnings: [
-                'Fallback generator used. Source description was preserved; technical ownership must come from explicit source paths or local project analysis.',
+                'Fallback generator used. Source description was preserved; missing decisions require explicit user input.',
             ],
             fallbackReason: 'No external model generator is configured for create_spec.',
         });
     }
 }
-function normalizeSourceDescription(description, title) {
+function normalizeSourceDescription(description) {
     const compact = description.replace(/\r\n/g, '\n').trim();
     if (compact.length > 0) {
         return compact;
     }
-    return `The project needs ${title} defined with enough implementation detail to proceed safely.`;
-}
-function buildContextLine(request) {
-    const parts = [
-        request.projectContext?.language,
-        request.projectContext?.framework,
-        request.projectContext?.architecture,
-    ].filter((part) => part !== undefined && part.trim().length > 0);
-    if (parts.length === 0) {
-        return 'Use the existing project architecture and conventions.';
-    }
-    return `Use the existing ${parts.join(' / ')} project conventions.`;
+    return 'Needs decision: provide the source requirement description.';
 }
 //# sourceMappingURL=fallback-generator.js.map

package/dist/engine/spec-grounding/contract.d.ts

@@ -6,6 +6,11 @@ export declare function filterGroundedCriteria(criteria: string[]): string[];
 export declare function buildCriterionGroundingRecords(args: {
     criteria: string[];
     userInput: string;
+    criterionEvidence?: {
+        criterion: string;
+        evidence: string[];
+    }[];
+    /** @deprecated Global evidence cannot ground a criterion. Use criterionEvidence. */
     projectEvidence?: string[];
     generatedEvidence?: string[];
 }): CriterionGroundingRecord[];

package/dist/engine/spec-grounding/contract.js

@@ -23,8 +23,11 @@ export function filterGroundedCriteria(criteria) {
 }
 export function buildCriterionGroundingRecords(args) {
     const userInput = normalizeCriterionText(args.userInput);
-    const projectEvidence = args.projectEvidence ?? [];
     const generatedEvidence = args.generatedEvidence ?? [];
+    const criterionEvidence = new Map((args.criterionEvidence ?? []).map((record) => [
+        normalizeCriterionText(record.criterion),
+        record.evidence.filter((item) => item.trim().length > 0),
+    ]));
     return args.criteria.map((criterion) => {
         const normalized = normalizeCriterionText(criterion);
         if (isGenericCriterion(criterion)) {
@@ -43,12 +46,13 @@ export function buildCriterionGroundingRecords(args) {
                 confidence: 'high',
             };
         }
-        if (projectEvidence.length > 0) {
+        const directProjectEvidence = criterionEvidence.get(normalized) ?? [];
+        if (directProjectEvidence.length > 0) {
             return {
                 text: criterion,
                 source: 'project_evidence',
-                evidence: projectEvidence.slice(0, 8),
-                confidence: 'medium',
+                evidence: directProjectEvidence.slice(0, 8),
+                confidence: 'high',
             };
         }
         return {
@@ -108,7 +112,7 @@ export function checkGroundedSpecContract(spec, content) {
         issues.push(`Spec ${spec.id} requires grounding metadata but has no grounded criteria records.`);
     }
     for (const record of records) {
-        if (record.source === 'ungrounded_advisory') {
+        if (record.source === 'ungrounded_advisory' || record.source === 'documented_assumption') {
             issues.push(`Criterion is advisory-only and cannot be approved as contract: ${record.text}`);
         }
         if (record.evidence.length === 0 && record.source !== 'ungrounded_advisory') {
@@ -117,7 +121,7 @@ export function checkGroundedSpecContract(spec, content) {
     }
     const technicalRecords = parseTechnicalReferenceGroundingRecords(frontmatter);
     for (const record of technicalRecords) {
-        if (record.source === 'ungrounded_advisory') {
+        if (record.source === 'ungrounded_advisory' || record.source === 'documented_assumption') {
             issues.push(`Technical reference is advisory-only and cannot be contract: ${record.path}`);
         }
         if (record.evidence.length === 0 && record.source !== 'ungrounded_advisory') {

package/dist/engine/spec-migrator/lean-migration.js

@@ -113,9 +113,6 @@ function extractOldCriteria(content) {
         }
         match = re.exec(content);
     }
-    if (criteria.length === 0) {
-        criteria.push({ text: 'Implementation complete and tested', done: false });
-    }
     return criteria;
 }
 /** Check if a criterion is generic boilerplate (not specific to the feature). */
@@ -415,10 +412,14 @@ export async function migrateSpecToLean(specDir, projectPath) {
         const criteria = extractOldCriteria(specContent);
         const estimation = buildEstimationFromOld(metadata, oldTechContent);
         const spec = buildSpecFromMetadata(metadata, id, title, status, estimation, specPath, techPath);
-        // Generate lean spec.md with extracted criteria
-        const leanSpecLines = generateLeanSpecContent({ spec, description, estimation });
-        // Inject real criteria (replace the default one)
-        const leanSpecWithCriteria = replaceCriteria(leanSpecLines, criteria);
+        // Generate lean spec.md with extracted legacy criteria. Do not synthesize defaults:
+        // migrations preserve source-backed acceptance criteria only.
+        const leanSpecLines = generateLeanSpecContent({
+            spec,
+            description,
+            estimation,
+            criteriaOverride: criteria,
+        });
         // Generate the legacy technical body, then fold it into unified spec.md.
         const leanTech = generateLeanTechnicalContent({
             specId: id,
@@ -434,7 +435,7 @@ export async function migrateSpecToLean(specDir, projectPath) {
             return `backup failed: ${backupErr instanceof Error ? backupErr.message : String(backupErr)}`;
         }
         // Write one unified spec.md.
-        await atomicWriteFile(specPath, buildUnifiedSpecContent(leanSpecWithCriteria, leanTech));
+        await atomicWriteFile(specPath, buildUnifiedSpecContent(leanSpecLines, leanTech));
         // Delete obsolete files
         for (const file of OBSOLETE_FILES) {
             const filePath = join(specDir, file);
@@ -457,14 +458,6 @@ export async function migrateSpecToLean(specDir, projectPath) {
         return err instanceof Error ? err.message : String(err);
     }
 }
-/** Replace criteria in lean spec content with extracted old criteria. */
-function replaceCriteria(content, criteria) {
-    // Find the criteria section in YAML and replace it
-    const criteriaLines = criteria.map((c) => `  - text: "${c.text.replace(/"/g, '\\"')}"\n    done: ${String(c.done)}`);
-    const newCriteria = `criteria:\n${criteriaLines.join('\n')}`;
-    // Replace the existing criteria block
-    return content.replace(/criteria:\n(?: {2}- text:.*\n {4}done:.*\n?)+/, `${newCriteria}\n`);
-}
 /** Migrate all specs in a project to lean format. */
 export async function migrateAllSpecsToLean(projectPath) {
     const result = { migratedCount: 0, skippedCount: 0, errors: [] };

package/dist/engine/web-fetcher/stack-advisor.d.ts

@@ -1,4 +1,4 @@
-import type { StackRecommendation, SuggestStackResult } from '../../types/index.js';
+import type { StackAdviceGrounding, StackRecommendation, SuggestStackResult } from '../../types/index.js';
 export declare function verifyFrameworkVersion(framework: string): Promise<string | null>;
 export declare function recommendStack(projectType: string, requirements: string[], constraints: string[]): StackRecommendation;
 export declare function recommendAlternativeStack(projectType: string, _requirements: string[]): StackRecommendation;
@@ -11,5 +11,5 @@ export declare function buildMcpCompatibility(stack: StackRecommendation): {
     compatible: boolean;
     notes: string;
 }[];
-export declare function buildSuggestStackResult(projectType: string, requirements: string[], constraints: string[]): Promise<SuggestStackResult>;
+export declare function buildSuggestStackResult(projectType: string, requirements: string[], constraints: string[]): Promise<SuggestStackResult & StackAdviceGrounding>;
 //# sourceMappingURL=stack-advisor.d.ts.map