@planu/cli 4.3.18 → 4.3.19

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [4.3.19] - 2026-05-27
+
+### Bug Fixes
+- fix(SPEC-1072): clean spec advisory surfaces
+
+
 ## [4.3.13] - 2026-05-25
 
 ### Bug Fixes

package/dist/engine/pii-detector/core.js

@@ -1,5 +1,6 @@
 // pii-detector/core.ts — PII detection in spec text (SPEC-030)
 import { createRequire } from 'node:module';
+import { stripNonContractText } from '../text-signal-boundaries.js';
 const require = createRequire(import.meta.url);
 export const patterns = require('../../config/pii-patterns.json');
 // ---------------------------------------------------------------------------
@@ -33,6 +34,16 @@ function isBlacklistedContext(modelContext) {
     const lower = modelContext.toLowerCase();
     return patterns.modelContextBlacklist.some((b) => lower.includes(b.toLowerCase()));
 }
+function isWhitelistedContext(modelContext) {
+    const lower = modelContext.toLowerCase();
+    return patterns.modelContextWhitelist.some((w) => lower.includes(w.toLowerCase()));
+}
+function hasFieldCue(contextWindow) {
+    return /\b(field|fields|column|columns|property|properties|attribute|schema|model|entity|table|class|interface)\b/i.test(contextWindow);
+}
+function hasCollectionCue(contextWindow) {
+    return /\b(collect|store|process|persist|save|record|provide|must have|includes?|contains?)\b/i.test(contextWindow);
+}
 /**
  * Determines if a detected PII field is a GDPR Art. 9 special category.
  */
@@ -77,18 +88,26 @@ function inferModelContext(contextWindow) {
  */
 function extractCandidates(text) {
     const candidates = [];
-    const lower = text.toLowerCase();
+    const cleaned = stripNonContractText(text);
+    const lower = cleaned.toLowerCase();
     /* v8 ignore start */
-    const words = text.match(/\b[a-zA-Z_][a-zA-Z0-9_]*\b/g) ?? [];
+    const words = cleaned.match(/\b[a-zA-Z_][a-zA-Z0-9_]*\b/g) ?? [];
     /* v8 ignore stop */
     for (const word of words) {
         if (word.length < 3) {
             continue;
         }
+        if (matchVocabulary(normalizeField(word)) === null) {
+            continue;
+        }
         const wordIndex = lower.indexOf(word.toLowerCase());
-        const contextWindow = text.substring(Math.max(0, wordIndex - 100), wordIndex + 100);
+        const contextWindow = cleaned.substring(Math.max(0, wordIndex - 100), wordIndex + 100);
         const context = inferModelContext(contextWindow);
-        candidates.push({ field: word, context });
+        if (isWhitelistedContext(context) ||
+            (hasFieldCue(contextWindow) && !isBlacklistedContext(contextWindow)) ||
+            (hasCollectionCue(contextWindow) && isWhitelistedContext(contextWindow))) {
+            candidates.push({ field: word, context });
+        }
     }
     return candidates;
 }

package/dist/engine/text-signal-boundaries.d.ts

@@ -0,0 +1,6 @@
+/** Remove fenced code and quoted examples before keyword-driven inference. */
+export declare function stripNonContractText(text: string): string;
+/** True only when a regex match appears in contract prose and is not negated/excluded. */
+export declare function hasAffirmedMatch(text: string, pattern: RegExp): boolean;
+export declare function hasAnyAffirmedMatch(text: string, patterns: RegExp[]): boolean;
+//# sourceMappingURL=text-signal-boundaries.d.ts.map

package/dist/engine/text-signal-boundaries.js

@@ -0,0 +1,62 @@
+// engine/text-signal-boundaries.ts — Boundary-aware keyword matching for advisory signals.
+const NEGATION_WINDOW_WORDS = 5;
+const NEGATION_TERMS = new Set([
+    'no',
+    'not',
+    'without',
+    'avoid',
+    'exclude',
+    'excluding',
+    'except',
+    'skip',
+    'remove',
+    'disable',
+    'disallow',
+    'never',
+]);
+const OUT_OF_SCOPE_RE = /\b(?:out\s+of\s+scope|not\s+in\s+scope|no\s+scope|do\s+not|don't)\b/i;
+/** Remove fenced code and quoted examples before keyword-driven inference. */
+export function stripNonContractText(text) {
+    return text
+        .replace(/```[\s\S]*?```/g, ' ')
+        .replace(/`[^`\n]+`/g, ' ')
+        .replace(/"[^"\n]+"/g, ' ')
+        .replace(/'[^'\n]+'/g, ' ');
+}
+function wordTokensBefore(text, index) {
+    return text
+        .slice(Math.max(0, index - 160), index)
+        .toLowerCase()
+        .split(/[^a-z0-9]+/i)
+        .filter(Boolean);
+}
+function isNegatedAt(text, index) {
+    const before = wordTokensBefore(text, index);
+    const recent = before.slice(-NEGATION_WINDOW_WORDS);
+    return recent.some((word) => NEGATION_TERMS.has(word));
+}
+function isOutOfScopeLine(line, indexInLine) {
+    return OUT_OF_SCOPE_RE.test(line.slice(0, Math.max(indexInLine, 0) + 80));
+}
+/** True only when a regex match appears in contract prose and is not negated/excluded. */
+export function hasAffirmedMatch(text, pattern) {
+    const cleaned = stripNonContractText(text);
+    const flags = pattern.flags.includes('g') ? pattern.flags : `${pattern.flags}g`;
+    const re = new RegExp(pattern.source, flags);
+    let match = re.exec(cleaned);
+    while (match) {
+        const index = match.index;
+        const lineStart = cleaned.lastIndexOf('\n', index) + 1;
+        const lineEnd = cleaned.indexOf('\n', index);
+        const line = cleaned.slice(lineStart, lineEnd === -1 ? cleaned.length : lineEnd);
+        if (!isNegatedAt(cleaned, index) && !isOutOfScopeLine(line, index - lineStart)) {
+            return true;
+        }
+        match = re.exec(cleaned);
+    }
+    return false;
+}
+export function hasAnyAffirmedMatch(text, patterns) {
+    return patterns.some((pattern) => hasAffirmedMatch(text, pattern));
+}
+//# sourceMappingURL=text-signal-boundaries.js.map

package/dist/tools/challenge-spec/scenarios-data.js

@@ -1,14 +1,18 @@
 // tools/challenge-spec/scenarios-data.ts — Data consistency and partial write scenarios
-import { contentMentions } from './scenarios-utils.js';
+import { contentMentions, hasAnyAffirmedMatch } from './scenarios-utils.js';
+const WRITE_SIGNALS = [
+    /\b(transaction|persist|database write|save record|create record|update record|delete record)\b/i,
+    /\b(order|checkout|submit form|mutation|multi-step write)\b/i,
+];
+const CACHE_SIGNALS = [/\b(cache|real-time|realtime|concurrent|websocket|stale data)\b/i];
+const DUPLICATE_OPERATION_SIGNALS = [
+    /\b(submit|form|checkout|order|payment|create record|mutation|button click)\b/i,
+];
 export function generateDataConsistencyScenarios(_spec, content, _knowledge) {
     const scenarios = [];
     const lower = content.toLowerCase();
     // Partial writes
-    if (lower.includes('transaction') ||
-        lower.includes('update') ||
-        lower.includes('create') ||
-        lower.includes('modify') ||
-        lower.includes('save')) {
+    if (hasAnyAffirmedMatch(content, WRITE_SIGNALS)) {
         scenarios.push({
             scenario: 'Partial write: server crashes mid-transaction',
             probability: 'low',
@@ -22,7 +26,7 @@ export function generateDataConsistencyScenarios(_spec, content, _knowledge) {
         });
     }
     // Stale data
-    if (lower.includes('cache') || lower.includes('real-time') || lower.includes('concurrent')) {
+    if (hasAnyAffirmedMatch(content, CACHE_SIGNALS)) {
         scenarios.push({
             scenario: 'Stale data served from cache after underlying data changes',
             probability: 'high',
@@ -35,18 +39,20 @@ export function generateDataConsistencyScenarios(_spec, content, _knowledge) {
             userExperience: 'Show "last updated" timestamp. Offer manual refresh option.',
         });
     }
-    // Duplicate operations
-    scenarios.push({
-        scenario: 'User double-clicks submit, causing duplicate records',
-        probability: 'high',
-        impact: 'medium',
-        currentHandling: contentMentions(lower, ['idempoten', 'debounce', 'disable', 'lock'])
-            ? 'Some prevention mentioned'
-            : 'Not addressed',
-        requiredHandling: 'Implement idempotency keys for mutations. Disable submit button on click. Use unique constraints in DB.',
-        dataConsistency: 'No duplicate records from repeated submissions.',
-        userExperience: 'Button disabled during submission. Clear success/error feedback.',
-    });
+    // Duplicate operations only apply to explicit user-triggered mutations.
+    if (hasAnyAffirmedMatch(content, DUPLICATE_OPERATION_SIGNALS)) {
+        scenarios.push({
+            scenario: 'User double-clicks submit, causing duplicate records',
+            probability: 'high',
+            impact: 'medium',
+            currentHandling: contentMentions(lower, ['idempoten', 'debounce', 'disable', 'lock'])
+                ? 'Some prevention mentioned'
+                : 'Not addressed',
+            requiredHandling: 'Implement idempotency keys for mutations. Disable submit button on click. Use unique constraints in DB.',
+            dataConsistency: 'No duplicate records from repeated submissions.',
+            userExperience: 'Button disabled during submission. Clear success/error feedback.',
+        });
+    }
     return scenarios;
 }
 //# sourceMappingURL=scenarios-data.js.map

package/dist/tools/challenge-spec/scenarios-security.js

@@ -1,14 +1,20 @@
 // tools/challenge-spec/scenarios-security.ts — Authentication, injection, and CSRF scenarios
-import { contentMentions } from './scenarios-utils.js';
+import { contentMentions, hasAnyAffirmedMatch } from './scenarios-utils.js';
+const AUTH_SIGNALS = [
+    /\b(auth|authentication|login|session|token|jwt|oauth|permission|role|rbac)\b/i,
+];
+const INPUT_SIGNALS = [
+    /\b(user input|form|query param|search input|request body|payload|html input)\b/i,
+];
+const STATE_CHANGING_WEB_SIGNALS = [
+    /\b(form submit|post request|put request|delete request|mutation|state-changing|cookie auth)\b/i,
+];
 export function generateSecurityScenarios(_spec, content, _knowledge) {
     const scenarios = [];
     const lower = content.toLowerCase();
+    const text = content;
     // Authentication bypass
-    if (lower.includes('auth') ||
-        lower.includes('login') ||
-        lower.includes('user') ||
-        lower.includes('permission') ||
-        lower.includes('role')) {
+    if (hasAnyAffirmedMatch(text, AUTH_SIGNALS)) {
         scenarios.push({
             scenario: 'Unauthorized access attempt / authentication bypass',
             probability: 'high',
@@ -22,11 +28,7 @@ export function generateSecurityScenarios(_spec, content, _knowledge) {
         });
     }
     // Injection attacks
-    if (lower.includes('input') ||
-        lower.includes('form') ||
-        lower.includes('query') ||
-        lower.includes('search') ||
-        lower.includes('user')) {
+    if (hasAnyAffirmedMatch(text, INPUT_SIGNALS)) {
         scenarios.push({
             scenario: 'SQL injection / XSS / command injection via user input',
             probability: 'high',
@@ -39,18 +41,22 @@ export function generateSecurityScenarios(_spec, content, _knowledge) {
             userExperience: 'Transparent to user. Invalid input is silently sanitized.',
         });
     }
-    // CSRF / rate limiting
-    scenarios.push({
-        scenario: 'CSRF attack or brute-force attempt',
-        probability: 'medium',
-        impact: 'high',
-        currentHandling: contentMentions(lower, ['csrf', 'rate limit', 'throttle', 'captcha'])
-            ? 'Some protection mentioned'
-            : 'Not addressed',
-        requiredHandling: 'Implement CSRF tokens for state-changing operations. Rate-limit sensitive endpoints. Add CAPTCHA for auth endpoints.',
-        dataConsistency: 'Prevent mass data modifications from automated attacks.',
-        userExperience: 'Show rate limit message. Require CAPTCHA after N failed attempts.',
-    });
+    // CSRF / rate limiting only applies when the spec explicitly involves auth or
+    // state-changing web input. Tooling/spec-cleanup tasks should not get this as noise.
+    if (hasAnyAffirmedMatch(text, AUTH_SIGNALS) ||
+        hasAnyAffirmedMatch(text, STATE_CHANGING_WEB_SIGNALS)) {
+        scenarios.push({
+            scenario: 'CSRF attack or brute-force attempt',
+            probability: 'medium',
+            impact: 'high',
+            currentHandling: contentMentions(lower, ['csrf', 'rate limit', 'throttle', 'captcha'])
+                ? 'Some protection mentioned'
+                : 'Not addressed',
+            requiredHandling: 'Implement CSRF tokens for state-changing operations. Rate-limit sensitive endpoints. Add CAPTCHA for auth endpoints.',
+            dataConsistency: 'Prevent mass data modifications from automated attacks.',
+            userExperience: 'Show rate limit message. Require CAPTCHA after N failed attempts.',
+        });
+    }
     return scenarios;
 }
 //# sourceMappingURL=scenarios-security.js.map

package/dist/tools/challenge-spec/scenarios-utils.d.ts

@@ -3,4 +3,5 @@
  * lowerContent is expected to already be lowercased by the caller.
  */
 export declare function contentMentions(lowerContent: string, keywords: string[]): boolean;
+export { hasAffirmedMatch, hasAnyAffirmedMatch, stripNonContractText, } from '../../engine/text-signal-boundaries.js';
 //# sourceMappingURL=scenarios-utils.d.ts.map

package/dist/tools/challenge-spec/scenarios-utils.js

@@ -6,4 +6,5 @@
 export function contentMentions(lowerContent, keywords) {
     return keywords.some((kw) => lowerContent.includes(kw.toLowerCase()));
 }
+export { hasAffirmedMatch, hasAnyAffirmedMatch, stripNonContractText, } from '../../engine/text-signal-boundaries.js';
 //# sourceMappingURL=scenarios-utils.js.map

package/dist/tools/create-spec/spec-builder.js

@@ -182,6 +182,15 @@ const EN_STOPWORDS = new Set([
     'it',
     'be',
     'as',
+    'spec',
+    'create',
+    'workflow',
+    'files',
+    'file',
+    'example',
+    'avoid',
+    'planu',
+    'feature',
 ]);
 /** Infer meaningful tags from title and description when no tags were provided. */
 export function inferTagsFromContent(title, description, type) {
@@ -213,13 +222,13 @@ export function inferTagsFromContent(title, description, type) {
     }
     return tags;
 }
-/** Build the final tags array for a spec, enforcing minimum 3 tags. */
-function buildTags(tags, feature, title, description, type) {
-    const result = feature ? [...new Set([...tags, slugify(feature)])] : [...tags];
-    if (result.length === 0) {
-        return inferTagsFromContent(title, description, type);
-    }
-    return result;
+/** Build the final tags array from explicit user/tool input only. */
+function buildTags(tags, feature, _title, _description, _type) {
+    const explicitTags = tags
+        .map((tag) => slugify(tag))
+        .filter((tag) => tag.length > 0 && !EN_STOPWORDS.has(tag));
+    const result = feature ? [...new Set([...explicitTags, slugify(feature)])] : explicitTags;
+    return [...new Set(result)];
 }
 /* v8 ignore start -- filesystem scanning is best-effort, tested via integration */
 /** Scan filesystem for SPEC-XXX directories to find max ID globally. */

package/dist/tools/create-spec.js

@@ -14,7 +14,7 @@ import { setupGitBranch, checkContradictions, fireSpecCreatedHook, generatePostC
 import { notifyStoreChange } from '../engine/doc-generator/portal/regen-hook.js';
 import { compactObj } from '../engine/compact-obj.js';
 import { buildCreateSpecSummary } from '../engine/human-summary.js';
-import { runAutoPostCreatePipeline, formatPipelineLines } from './create-spec/auto-pipeline.js';
+import { runAutoPostCreatePipeline } from './create-spec/auto-pipeline.js';
 import { generateLeanSpecContent } from '../engine/spec-format/lean-spec-generator.js';
 import { generateLeanTechnicalContent } from '../engine/spec-format/lean-technical-generator.js';
 import { buildUnifiedSpecContent } from '../engine/spec-format/unified-spec-builder.js';
@@ -133,6 +133,16 @@ function runSimplicityCheck(text, hours) {
         return null;
     }
 }
+function makeAdvisorySignal(args) {
+    return { ...args, persistable: false };
+}
+function buildAdvisoryCompat() {
+    return {
+        legacyTopLevelAdvisoryFields: true,
+        deprecatedAfter: 'vNext+2',
+        canonicalField: 'advisorySignals',
+    };
+}
 /** SPEC-612: resolve outOfScope items (provided by user, or auto-suggested from description). */
 function resolveOutOfScope(description, provided) {
     if (provided !== undefined && provided.length > 0) {
@@ -181,18 +191,6 @@ async function runComplexityAdvice(projectId, currentSpecId, tags, targetCriteri
         return null;
     }
 }
-function formatSimplicityLines(r) {
-    const icon = r.recommendation === 'simplify' ? '🔴' : r.recommendation === 'review' ? '🟡' : '🟢';
-    const signalNames = r.signals.map((s) => s.type).join(', ');
-    const lines = [
-        '',
-        `${icon} **Simplicity**: score ${String(r.score)}/100 — ${signalNames !== '' ? signalNames : 'no signals'}`,
-    ];
-    if (r.recommendation !== 'approve' && r.simpleAlternative !== null) {
-        lines.push(`   Suggestion: ${r.simpleAlternative}`);
-    }
-    return lines;
-}
 /** SPEC-783: Synthesize agent team findings into unified spec.md ## Technical section. */
 async function handleAgentTeamSynthesis(specId, projectPath, findings) {
     try {
@@ -723,9 +721,21 @@ export async function handleCreateSpec(inputParams, server) {
                 /* v8 ignore next -- requires real git repo */
                 ...(gitSetupResult ? { gitAutoSetup: gitSetupResult.data } : {}),
             };
+            const advisorySignals = [];
             const splitResult = buildSplitResult(splitSuggestion, knowledge?.experienceLevel);
             if (splitResult) {
                 result.splitSuggestion = splitResult;
+                advisorySignals.push(makeAdvisorySignal({
+                    key: 'split-suggestion',
+                    kind: 'complexity',
+                    message: 'Spec may benefit from splitting.',
+                    source: 'heuristic',
+                    evidence: ['spec-splitter heuristic'],
+                    confidence: 0.5,
+                    surface: 'structuredContent',
+                    value: splitResult,
+                    deprecatedAlias: 'splitSuggestion',
+                }));
             }
             // Dispatch hook event (fire-and-forget)
             fireSpecCreatedHook(projectId, spec, params.projectPath ?? '');
@@ -780,31 +790,97 @@ export async function handleCreateSpec(inputParams, server) {
             const qualityValue = unwrapBudget(qualityResult, null, budgetWarnings);
             if (qualityValue !== null) {
                 result.qualityScore = qualityValue;
+                advisorySignals.push(makeAdvisorySignal({
+                    key: 'quality-score',
+                    kind: 'quality',
+                    message: `Quality score ${String(qualityValue.total)}/100 (${qualityValue.grade}).`,
+                    source: 'validator',
+                    evidence: ['spec-quality-scorer'],
+                    confidence: 0.7,
+                    surface: 'structuredContent',
+                    value: qualityValue,
+                    deprecatedAlias: 'qualityScore',
+                }));
             }
             // SPEC-485: Simplicity autopilot — detect over-engineering signals (best-effort, sync)
             const simplicityResult = runSimplicityCheck([params.description, ...filteredCriteria].join('\n'), estimation.devHours);
             if (simplicityResult) {
                 result.simplicityCheck = simplicityResult;
+                advisorySignals.push(makeAdvisorySignal({
+                    key: 'simplicity-check',
+                    kind: 'simplicity',
+                    message: `Simplicity recommendation: ${simplicityResult.recommendation}.`,
+                    source: 'heuristic',
+                    evidence: simplicityResult.signals.map((signal) => signal.type),
+                    confidence: 0.55,
+                    surface: 'structuredContent',
+                    value: simplicityResult,
+                    deprecatedAlias: 'simplicityCheck',
+                }));
             }
             // SPEC-514: duplicate results
             const possibleDuplicates = unwrapBudget(duplicatesResult, [], budgetWarnings);
             if (possibleDuplicates.length > 0) {
                 result.possibleDuplicates = possibleDuplicates;
+                advisorySignals.push(makeAdvisorySignal({
+                    key: 'possible-duplicates',
+                    kind: 'duplicate',
+                    message: `${String(possibleDuplicates.length)} possible duplicate spec(s) detected.`,
+                    source: 'heuristic',
+                    evidence: possibleDuplicates.map((dup) => dup.specId),
+                    confidence: 0.5,
+                    surface: 'structuredContent',
+                    value: possibleDuplicates,
+                    deprecatedAlias: 'possibleDuplicates',
+                }));
             }
             // SPEC-222 Trigger 2: Auto-challenge hint for high-risk specs
             if (spec.risk === 'high' || spec.difficulty >= 4) {
                 result.riskWarning = HIGH_RISK_WARNING;
+                advisorySignals.push(makeAdvisorySignal({
+                    key: 'risk-warning',
+                    kind: 'challenge',
+                    message: 'High-risk heuristic warning generated.',
+                    source: 'heuristic',
+                    evidence: [`risk:${spec.risk}`, `difficulty:${String(spec.difficulty)}`],
+                    confidence: 0.6,
+                    surface: 'structuredContent',
+                    value: HIGH_RISK_WARNING,
+                    deprecatedAlias: 'riskWarning',
+                }));
             }
             // SPEC-614 AC4: complexity advice
             const cAdvice = unwrapBudget(complexityResult, null, budgetWarnings);
             if (cAdvice) {
                 result.complexityAdvice = cAdvice;
+                advisorySignals.push(makeAdvisorySignal({
+                    key: 'complexity-advice',
+                    kind: 'complexity',
+                    message: cAdvice.reasoning,
+                    source: 'history',
+                    evidence: [`similarSpecs:${String(cAdvice.similarSpecsCount)}`],
+                    confidence: 0.6,
+                    surface: 'structuredContent',
+                    value: cAdvice,
+                    deprecatedAlias: 'complexityAdvice',
+                }));
             }
             // SPEC-615: prior decisions
             const priorLinks = unwrapBudget(priorLinksResult, [], budgetWarnings);
             if (priorLinks.length > 0) {
                 result.priorDecisions = priorLinks.map((l) => l.decisionId);
                 spec.priorDecisions = result.priorDecisions;
+                advisorySignals.push(makeAdvisorySignal({
+                    key: 'prior-decisions',
+                    kind: 'prior-decision',
+                    message: `${String(priorLinks.length)} prior decision link(s) found.`,
+                    source: 'history',
+                    evidence: priorLinks.map((link) => link.decisionId),
+                    confidence: 0.65,
+                    surface: 'structuredContent',
+                    value: result.priorDecisions,
+                    deprecatedAlias: 'priorDecisions',
+                }));
             }
             // Post-creation suggestions
             const nextSteps = unwrapBudget(nextStepsResult, [], budgetWarnings);
@@ -871,30 +947,13 @@ export async function handleCreateSpec(inputParams, server) {
             if (contradictionHint) {
                 lines.push('', `⚠️ ${contradictionHint}`);
             }
-            if (possibleDuplicates.length > 0) {
-                lines.push('', '⚠️ **Possible Duplicates** (semantic similarity > 30%):');
-                for (const dup of possibleDuplicates) {
-                    const pct = Math.round(dup.score * 100);
-                    lines.push(`- **${dup.specId}** — ${dup.title} (${String(pct)}% similar)`);
-                }
-            }
-            if (result.riskWarning) {
-                lines.push('', `⚠️ ${result.riskWarning}`);
-            }
-            if (splitResult) {
-                lines.push('', `💡 ${splitResult.formatted ?? 'Consider splitting this spec.'}`);
-            }
-            // SPEC-492: Quality score output
-            if (result.qualityScore) {
-                const qs = result.qualityScore;
-                lines.push('', `📊 **Quality score**: ${String(qs.total)}/100 (${qs.grade})`);
-            }
-            // SPEC-485: Simplicity autopilot output
-            if (simplicityResult) {
-                lines.push(...formatSimplicityLines(simplicityResult));
+            if (possibleDuplicates.length > 0 ||
+                result.riskWarning ||
+                splitResult ||
+                result.qualityScore ||
+                simplicityResult) {
+                lines.push('', 'Advisory signals were computed and are available in structuredContent.advisorySignals.');
             }
-            // Append auto-pipeline output (SPEC-445)
-            lines.push(...formatPipelineLines(pipelineResult));
             const allNextSteps = (result.nextSteps ?? []).map((step) => (typeof step === 'string' ? step : formatPostCreationSuggestion(step)));
             const markdownText = allNextSteps.length > 0
                 ? addNextSteps(formatSuccess(ti('tools.create_spec.success', { id: spec.id, title: spec.title }), lines.join('\n')), allNextSteps)
@@ -904,15 +963,54 @@ export async function handleCreateSpec(inputParams, server) {
             // SPEC-612: Record outOfScope auto-suggestion in autopilot summary
             if (outOfScopeSuggestionMsg !== null) {
                 collector.pushOk('scope-boundaries', outOfScopeSuggestionMsg);
+                advisorySignals.push(makeAdvisorySignal({
+                    key: 'out-of-scope-suggestions',
+                    kind: 'out-of-scope',
+                    message: outOfScopeSuggestionMsg,
+                    source: 'heuristic',
+                    evidence: ['scope-boundaries suggester'],
+                    confidence: 0.45,
+                    surface: 'structuredContent',
+                    value: spec.outOfScope ?? [],
+                }));
             }
             if (autopilot.detectedPatterns.length > 0) {
                 collector.pushOk('pattern-detection', `Detected patterns: ${autopilot.detectedPatterns.join(', ')}`);
+                advisorySignals.push(makeAdvisorySignal({
+                    key: 'detected-patterns',
+                    kind: 'domain',
+                    message: `Detected patterns: ${autopilot.detectedPatterns.join(', ')}`,
+                    source: 'heuristic',
+                    evidence: autopilot.detectedPatterns,
+                    confidence: 0.5,
+                    surface: 'structuredContent',
+                    value: autopilot.detectedPatterns,
+                }));
             }
             const totalSuggestedFiles = autopilot.suggestedFiles.create.length +
                 autopilot.suggestedFiles.modify.length +
                 autopilot.suggestedFiles.test.length;
             if (totalSuggestedFiles > 0) {
                 collector.pushOk('file-analysis', `Suggested ${String(totalSuggestedFiles)} files (${String(autopilot.suggestedFiles.create.length)} create, ${String(autopilot.suggestedFiles.modify.length)} modify, ${String(autopilot.suggestedFiles.test.length)} test)`);
+                advisorySignals.push(makeAdvisorySignal({
+                    key: 'suggested-files',
+                    kind: 'file',
+                    message: `${String(totalSuggestedFiles)} possible related file(s) detected.`,
+                    source: 'heuristic',
+                    evidence: [
+                        ...autopilot.suggestedFiles.create.map((f) => f.path),
+                        ...autopilot.suggestedFiles.modify.map((f) => f.path),
+                        ...autopilot.suggestedFiles.test.map((f) => f.path),
+                    ],
+                    confidence: 0.45,
+                    surface: 'structuredContent',
+                    value: {
+                        create: autopilot.suggestedFiles.create.map((f) => f.path),
+                        modify: autopilot.suggestedFiles.modify.map((f) => f.path),
+                        test: autopilot.suggestedFiles.test.map((f) => f.path),
+                    },
+                    deprecatedAlias: 'autopilotSummary.suggestedFiles',
+                }));
             }
             if (filteredCriteria.length > 0) {
                 collector.pushOk('criteria-enrichment', `Added ${String(filteredCriteria.length)} acceptance criteria from project context`);
@@ -926,15 +1024,37 @@ export async function handleCreateSpec(inputParams, server) {
                     ? ` — difficulty ${String(spec.difficulty)}: use Opus to add exact file paths + function names`
                     : '';
                 collector.pushOk('readiness', `Readiness score: ${String(pipelineResult.readinessScore)}/100${opusHint}`);
+                advisorySignals.push(makeAdvisorySignal({
+                    key: 'readiness-score',
+                    kind: 'readiness',
+                    message: `Readiness score: ${String(pipelineResult.readinessScore)}/100.`,
+                    source: 'validator',
+                    evidence: ['auto post-creation pipeline'],
+                    confidence: 0.6,
+                    surface: 'structuredContent',
+                    value: pipelineResult.readinessScore,
+                }));
             }
             else if (spec.difficulty >= 3) {
                 // SPEC-629: always surface the Opus hint for high-difficulty specs
                 collector.pushOk('recommend_model', `Difficulty ${String(spec.difficulty)} spec — use Opus to add exact file paths, function names and anticipated test breaks.`);
+                advisorySignals.push(makeAdvisorySignal({
+                    key: 'model-recommendation',
+                    kind: 'model',
+                    message: 'High-difficulty spec may benefit from a stronger model for review.',
+                    source: 'heuristic',
+                    evidence: [`difficulty:${String(spec.difficulty)}`],
+                    confidence: 0.4,
+                    surface: 'structuredContent',
+                    value: { recommendedTier: 'max' },
+                }));
             }
             if (calibrationEnrichment.calibrationNote) {
                 collector.pushOk('calibration', `📐 ${calibrationEnrichment.calibrationNote}`);
             }
             const humanSummary = buildCreateSpecSummary(spec.title, estimation.devHours);
+            result.advisorySignals = advisorySignals;
+            result.compat = buildAdvisoryCompat();
             const compactResult = compactObj(result);
             // SPEC-722: Issue a planner token for this spec creation.
             // Best-effort — token failure never blocks spec creation.
@@ -965,6 +1085,8 @@ export async function handleCreateSpec(inputParams, server) {
                 : undefined;
             const baseResult = toolResult(markdownText, {
                 ...compactResult,
+                advisorySignals,
+                compat: buildAdvisoryCompat(),
                 humanSummary,
                 ...(collector.hasEntries() ? { autopilotSummary: collector.getMessages() } : {}),
                 ...(suggestedFilesPayload !== undefined

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@planu/cli",
-  "version": "4.3.18",
+  "version": "4.3.19",
   "description": "Planu — MCP Server for Spec Driven Development with native Rust acceleration for hot paths. Cross-platform (Linux/macOS/Windows, x64/arm64, glibc/musl).",
   "type": "module",
   "main": "dist/index.js",
@@ -34,14 +34,14 @@
     "packageName": "@planu/core"
   },
   "optionalDependencies": {
-    "@planu/core-darwin-arm64": "4.3.18",
-    "@planu/core-darwin-x64": "4.3.18",
-    "@planu/core-linux-arm64-gnu": "4.3.18",
-    "@planu/core-linux-arm64-musl": "4.3.18",
-    "@planu/core-linux-x64-gnu": "4.3.18",
-    "@planu/core-linux-x64-musl": "4.3.18",
-    "@planu/core-win32-arm64-msvc": "4.3.18",
-    "@planu/core-win32-x64-msvc": "4.3.18"
+    "@planu/core-darwin-arm64": "4.3.19",
+    "@planu/core-darwin-x64": "4.3.19",
+    "@planu/core-linux-arm64-gnu": "4.3.19",
+    "@planu/core-linux-arm64-musl": "4.3.19",
+    "@planu/core-linux-x64-gnu": "4.3.19",
+    "@planu/core-linux-x64-musl": "4.3.19",
+    "@planu/core-win32-arm64-msvc": "4.3.19",
+    "@planu/core-win32-x64-msvc": "4.3.19"
   },
   "engines": {
     "node": ">=24.0.0"

package/planu-native.json

@@ -1,20 +1,26 @@
 {
   "name": "dev.planu.native",
   "displayName": "Planu Native Lightweight Surface",
-  "version": "4.3.18",
+  "version": "4.3.19",
   "packageName": "@planu/cli",
   "modes": {
     "lightweight": {
       "requiresMcp": false,
       "requiresDaemon": false,
-      "hosts": ["codex", "claude-code"],
+      "hosts": [
+        "codex",
+        "claude-code"
+      ],
       "commands": [
         {
           "id": "planu.status",
           "title": "Project status",
           "description": "Show the compact Planu project snapshot without loading the MCP tool graph.",
           "invocation": "planu status",
-          "hosts": ["codex", "claude-code"],
+          "hosts": [
+            "codex",
+            "claude-code"
+          ],
           "requiresMcp": false,
           "requiresDaemon": false,
           "mapsTo": "handlePlanStatus"
@@ -24,7 +30,10 @@
           "title": "Create spec",
           "description": "Create a new spec through the CLI-backed SDD contract.",
           "invocation": "planu spec create \"<title>\"",
-          "hosts": ["codex", "claude-code"],
+          "hosts": [
+            "codex",
+            "claude-code"
+          ],
           "requiresMcp": false,
           "requiresDaemon": false,
           "mapsTo": "handleCreateSpec"
@@ -34,7 +43,10 @@
           "title": "List specs",
           "description": "List specs in the current project with optional status/type filters.",
           "invocation": "planu spec list",
-          "hosts": ["codex", "claude-code"],
+          "hosts": [
+            "codex",
+            "claude-code"
+          ],
           "requiresMcp": false,
           "requiresDaemon": false,
           "mapsTo": "handleListSpecs"
@@ -44,7 +56,10 @@
           "title": "Validate spec",
           "description": "Validate a spec against the current codebase from the native CLI surface.",
           "invocation": "planu spec validate SPEC-001",
-          "hosts": ["codex", "claude-code"],
+          "hosts": [
+            "codex",
+            "claude-code"
+          ],
           "requiresMcp": false,
           "requiresDaemon": false,
           "mapsTo": "handleValidate"
@@ -54,7 +69,10 @@
           "title": "Audit technical debt",
           "description": "Run the read-only project audit path for lightweight debt checks.",
           "invocation": "planu audit debt",
-          "hosts": ["codex", "claude-code"],
+          "hosts": [
+            "codex",
+            "claude-code"
+          ],
           "requiresMcp": false,
           "requiresDaemon": false,
           "mapsTo": "handleAudit"
@@ -64,7 +82,10 @@
           "title": "Check release readiness",
           "description": "Check local branch cleanliness and main/develop/release sync readiness.",
           "invocation": "planu release check",
-          "hosts": ["codex", "claude-code"],
+          "hosts": [
+            "codex",
+            "claude-code"
+          ],
           "requiresMcp": false,
           "requiresDaemon": false,
           "mapsTo": "releaseCommand"

package/planu-plugin.json

@@ -2,9 +2,12 @@
   "name": "dev.planu.cli",
   "displayName": "Planu — Spec Driven Development",
   "description": "Manage software specs, estimations, and autonomous SDD workflows. Language-agnostic MCP server for Claude Code.",
-  "version": "4.3.18",
+  "version": "4.3.19",
   "icon": "assets/plugin/icon.svg",
-  "command": ["npx", "@planu/cli@latest"],
+  "command": [
+    "npx",
+    "@planu/cli@latest"
+  ],
   "packageName": "@planu/cli",
   "capabilities": {
     "tools": [
@@ -23,17 +26,42 @@
       "create_skill",
       "skill_search"
     ],
-    "resources": ["planu://specs/list", "planu://specs/{id}", "planu://project/status", "planu://roadmap"],
-    "prompts": ["create-spec-from-idea", "review-spec-readiness", "generate-implementation-plan"],
-    "subagents": ["sdd-orchestrator", "spec-challenger", "test-generator"]
+    "resources": [
+      "planu://specs/list",
+      "planu://specs/{id}",
+      "planu://project/status",
+      "planu://roadmap"
+    ],
+    "prompts": [
+      "create-spec-from-idea",
+      "review-spec-readiness",
+      "generate-implementation-plan"
+    ],
+    "subagents": [
+      "sdd-orchestrator",
+      "spec-challenger",
+      "test-generator"
+    ]
   },
   "compatibility": {
     "minimumHostVersion": "1.0.0",
-    "requiredFeatures": ["mcp-tools", "file-editing"]
+    "requiredFeatures": [
+      "mcp-tools",
+      "file-editing"
+    ]
   },
   "repository": "https://github.com/planu-dev/planu",
   "author": "Planu",
   "license": "MIT",
   "homepage": "https://planu.dev",
-  "keywords": ["sdd", "spec-driven-development", "mcp", "specs", "planning", "ai", "bdd", "tdd"]
+  "keywords": [
+    "sdd",
+    "spec-driven-development",
+    "mcp",
+    "specs",
+    "planning",
+    "ai",
+    "bdd",
+    "tdd"
+  ]
 }