@planu/cli 4.14.1 → 5.1.1

package/dist/tools/challenge-spec-helpers.js

@@ -1,55 +1,96 @@
 // tools/challenge-spec-helpers.ts — Concurrency, risk, and spec-reader helpers for challenge-spec
 import { readFile } from 'node:fs/promises';
 import { readSpecTechnicalSection } from '../engine/spec-format/read-technical-section.js';
-// --- Concurrency analysis ---
+import { hasAffirmedMatch, stripMetaAnalysisText, stripNonContractText, } from '../engine/text-signal-boundaries.js';
+// Bare keyword matches (counter, status, draft, ...) are common in unrelated
+// prose (variable names, file paths, section headers, bug narratives). They
+// only ground a race-condition/shared-state finding when the spec content
+// also affirms an explicit concurrency context — otherwise they are boilerplate.
+const CONCURRENCY_CONTEXT_PATTERN = /\b(?:concurrent(?:ly)?|simultaneous(?:ly)?|in\s+parallel|parallel\s+writes?|race\s+condition|multiple\s+users?|at\s+the\s+same\s+time|two\s+users|shared\s+state|atomic(?:ally)?|thread-safe|synchroniz(?:e|es|ed|ing|ation)|multiple\s+(?:tabs|devices|requests|clients))\b/i;
+const AUTH_PATTERN = /\b(?:login|auth)\b/i;
+const LIST_SEARCH_PATTERN = /\b(?:list|search|feed)\b/i;
+const WRITE_PATTERN = /\b(?:submit|create|update)\b/i;
+const COUNTER_PATTERN = /\b(?:counter|increment|balance|stock|quantity|vote)\b/i;
+const STATUS_PATTERN = /\bstatus\b/i;
+const TRANSITION_PATTERN = /\b(?:update|transition)\b/i;
+const FILE_PATTERN = /\b(?:file|upload|resource)\b/i;
+const SESSION_PATTERN = /\b(?:session|cart|draft)\b/i;
+const CACHE_PATTERN = /\b(?:cache|global|config)\b/i;
+/** Grounded, boundary-aware, negation-aware match against contract prose only. */
+function affirms(content, pattern) {
+    return hasAffirmedMatch(content, pattern);
+}
 export function generateConcurrencyAnalysis(_spec, content, _knowledge) {
-    const lower = content.toLowerCase();
+    // Drop frontmatter, code fences, and quoted/backticked examples before
+    // keyword inference — mirrors detectChallengeCapabilities so this generator
+    // reads the same "contract prose" the capability gate already reads.
+    const contract = stripMetaAnalysisText(stripNonContractText(content));
     const hotPaths = [];
     const raceConditions = [];
     const sharedState = [];
     const recommendations = [];
-    // Detect hot paths
-    if (lower.includes('login') || lower.includes('auth')) {
+    let suppressedCount = 0;
+    // Hot paths are informational only (they do not feed overallRisk), so a
+    // plain boundary-aware match is sufficient here — no context gate needed.
+    if (affirms(contract, AUTH_PATTERN)) {
         hotPaths.push('Authentication endpoint (high-frequency, shared session state)');
     }
-    if (lower.includes('list') || lower.includes('search') || lower.includes('feed')) {
+    if (affirms(contract, LIST_SEARCH_PATTERN)) {
         hotPaths.push('List/search endpoints (high read frequency)');
     }
-    if (lower.includes('submit') || lower.includes('create') || lower.includes('update')) {
+    if (affirms(contract, WRITE_PATTERN)) {
         hotPaths.push('Write endpoints (mutation-heavy, lock-prone)');
     }
-    // Detect race conditions
-    if (lower.includes('counter') ||
-        lower.includes('increment') ||
-        lower.includes('balance') ||
-        lower.includes('stock') ||
-        lower.includes('quantity') ||
-        lower.includes('vote')) {
+    const hasConcurrencyContext = affirms(contract, CONCURRENCY_CONTEXT_PATTERN);
+    const counterMatched = affirms(contract, COUNTER_PATTERN);
+    if (counterMatched && hasConcurrencyContext) {
         raceConditions.push('Counter/balance updates may lose increments under concurrent writes');
         recommendations.push('Use database-level atomic increments (UPDATE SET count = count + 1) instead of read-modify-write');
     }
-    if (lower.includes('status') && (lower.includes('update') || lower.includes('transition'))) {
+    else if (counterMatched) {
+        suppressedCount += 1;
+    }
+    const statusMatched = affirms(contract, STATUS_PATTERN) && affirms(contract, TRANSITION_PATTERN);
+    if (statusMatched && hasConcurrencyContext) {
         raceConditions.push('Status transitions may conflict when two users update simultaneously');
         recommendations.push('Use optimistic locking (version column) or pessimistic locking (SELECT FOR UPDATE)');
     }
-    if (lower.includes('file') || lower.includes('upload') || lower.includes('resource')) {
+    else if (statusMatched) {
+        suppressedCount += 1;
+    }
+    const fileMatched = affirms(contract, FILE_PATTERN);
+    if (fileMatched && hasConcurrencyContext) {
         raceConditions.push('Concurrent file writes to same resource may corrupt data');
         recommendations.push('Use advisory locks or rename-and-swap pattern for file operations');
     }
-    // Detect shared state
-    if (lower.includes('session') || lower.includes('cart') || lower.includes('draft')) {
+    else if (fileMatched) {
+        suppressedCount += 1;
+    }
+    const sessionMatched = affirms(contract, SESSION_PATTERN);
+    if (sessionMatched && hasConcurrencyContext) {
         sharedState.push('User session state (may be accessed from multiple tabs/devices)');
     }
-    if (lower.includes('cache') || lower.includes('global') || lower.includes('config')) {
+    else if (sessionMatched) {
+        suppressedCount += 1;
+    }
+    const cacheMatched = affirms(contract, CACHE_PATTERN);
+    if (cacheMatched && hasConcurrencyContext) {
         sharedState.push('Global cache or configuration (requires synchronized access)');
     }
-    // General recommendations
+    else if (cacheMatched) {
+        suppressedCount += 1;
+    }
+    // General recommendations — only emitted once a race condition is actually
+    // grounded, otherwise a formatting-only spec would still surface generic
+    // "use database transactions" boilerplate (SPEC-1350 AC1).
     if (raceConditions.length === 0) {
         recommendations.push('No obvious race conditions detected, but test concurrent scenarios in integration tests');
     }
-    recommendations.push('Use database transactions for multi-step operations');
-    recommendations.push('Implement idempotency keys for all mutation endpoints');
-    return { hotPaths, raceConditions, sharedState, recommendations };
+    else {
+        recommendations.push('Use database transactions for multi-step operations');
+        recommendations.push('Implement idempotency keys for all mutation endpoints');
+    }
+    return { hotPaths, raceConditions, sharedState, recommendations, suppressedCount };
 }
 // --- Scalability and risk ---
 export function buildScalabilityAssessment(spec, knowledge, scenarios) {

package/dist/tools/challenge-spec.js

@@ -19,6 +19,7 @@ import { analyzeMinimalImplementation, loadMinimalImplementationPolicy, } from '
 import { detectChallengeCapabilities, } from './challenge-spec/scenarios-utils.js';
 import { collectCapabilityScenarios } from './challenge-spec/scenario-collector.js';
 import { buildChallengeReport, parseChallengeResolutionEvidence, } from './challenge-spec/challenge-report.js';
+import { extractListItems, findMarkdownSectionRange, } from '../engine/spec-format/markdown-sections.js';
 const ALL_FOCUS_AREAS = [
     'failures',
     'concurrency',
@@ -150,11 +151,10 @@ export async function handleChallengeSpec(args, server) {
     failureScenarios.push(...collectCapabilityScenarios({ spec, specContent, knowledge, focusAreas, capabilities }));
     // SPEC-612: Check for contradictions between outOfScope and acceptance criteria
     if (spec.outOfScope !== undefined && spec.outOfScope.length > 0) {
-        const criteriaTexts = specContent
-            .split('\n')
-            .filter((line) => line.trim().startsWith('-') || line.trim().startsWith('*'))
-            .map((line) => line.replace(/^[\s\-*]+/, '').trim())
-            .filter((line) => line.length > 0);
+        const criteriaRange = findMarkdownSectionRange(specContent, 'Acceptance Criteria');
+        const criteriaTexts = criteriaRange === null
+            ? []
+            : extractListItems(specContent.slice(criteriaRange.contentStart, criteriaRange.end));
         const contradictionResult = checkScopeContradictions(spec.outOfScope, criteriaTexts);
         for (const c of contradictionResult.contradictions) {
             failureScenarios.push({
@@ -171,9 +171,24 @@ export async function handleChallengeSpec(args, server) {
     // SPEC-615 AC3: Check criteria against prior decisions for technology contradictions
     await runPriorDecisionContradictions(projectId, spec.title, spec.tags, specContent, failureScenarios);
     // 6. Generate concurrency analysis
-    const concurrencyAnalysis = focusAreas.includes('concurrency') && capabilities.concurrency
+    const concurrencyResult = focusAreas.includes('concurrency') && capabilities.concurrency
         ? generateConcurrencyAnalysis(spec, specContent, knowledge)
-        : { hotPaths: [], raceConditions: [], sharedState: [], recommendations: [] };
+        : {
+            hotPaths: [],
+            raceConditions: [],
+            sharedState: [],
+            recommendations: [],
+            suppressedCount: 0,
+        };
+    // SPEC-1350: concurrency candidates that matched a domain keyword but lacked
+    // a corroborating concurrency context are suppressed before risk/summary math.
+    const concurrencySuppressedCount = concurrencyResult.suppressedCount;
+    const concurrencyAnalysis = {
+        hotPaths: concurrencyResult.hotPaths,
+        raceConditions: concurrencyResult.raceConditions,
+        sharedState: concurrencyResult.sharedState,
+        recommendations: concurrencyResult.recommendations,
+    };
     // Unsupported domain templates are removed before prioritization and risk calculation.
     const actionableFailureScenarios = failureScenarios.filter((scenario) => isScenarioSupportedByCapabilities(scenario, capabilities));
     const suppressedScenarioCount = failureScenarios.length - actionableFailureScenarios.length;
@@ -219,7 +234,7 @@ export async function handleChallengeSpec(args, server) {
         summary: {
             totalScenarios: failureScenarios.length,
             actionableScenarios: failureScenariosScored.length,
-            suppressedLowRelevanceScenarios: suppressedScenarioCount,
+            suppressedLowRelevanceScenarios: suppressedScenarioCount + concurrencySuppressedCount,
             shownByDefault: 3,
             mustAddressBeforeCoding: prioritizedSummary,
             criticalImpact: actionableFailureScenarios.filter((s) => s.impact === 'critical').length,

package/dist/tools/check-readiness.js

@@ -1,7 +1,5 @@
 // tools/check-readiness.ts — Completeness checkpoint tool (SPEC-039, SPEC-314, SPEC-716)
 import { specStore } from '../storage/index.js';
-import { checkSpecReadiness } from '../engine/readiness-checker.js';
-import { scoreSpecQuality } from '../engine/spec-quality-scorer.js';
 import { buildCheckReadinessSummary } from '../engine/human-summary.js';
 import { validateSpecFormat } from '../core/spec-validator.js';
 import { resolveProjectId } from './resolve-project-id.js';
@@ -9,6 +7,7 @@ import { resolveProjectId } from './resolve-project-id.js';
 const MAX_VISIBLE_BLOCKERS = 8;
 const MAX_VISIBLE_WARNINGS = 8;
 const MAX_VISIBLE_RECOMMENDATIONS = 5;
+const CANONICAL_CRITERIA_MISSING = 'CANONICAL_CRITERIA_MISSING';
 function formatScore(score) {
     if (score >= 90) {
         return `${score}/100 (Excellent)`;
@@ -21,6 +20,23 @@ function formatScore(score) {
     }
     return `${score}/100 (Not Ready)`;
 }
+function canonicalReadinessFailure(validationResult) {
+    const metrics = validationResult.metrics;
+    if (metrics === undefined || metrics.criteriaCount === 0) {
+        return CANONICAL_CRITERIA_MISSING;
+    }
+    return null;
+}
+function createFailClosedReport(specId, mode) {
+    return {
+        specId,
+        score: 0,
+        ready: false,
+        mode,
+        issues: { score: 0, breakdown: {}, blockers: [], warnings: [] },
+        recommendations: [],
+    };
+}
 function formatReport(report) {
     const lines = [];
     lines.push(`# Readiness Report — ${report.specId}`);
@@ -109,20 +125,15 @@ export async function handleCheckReadiness(args) {
             isError: true,
         };
     }
-    // SPEC-716: Ground yes/no decision in validateSpecFormat.
-    // The existing checkSpecReadiness call and formatReport are preserved for
-    // the rich human-readable output. validateSpecFormat drives the yes/no gate
-    // and its errors/warnings are surfaced in structuredContent.validationResult.
-    const [report, qualityReport, validationResult] = await Promise.all([
-        checkSpecReadiness(spec, mode),
-        scoreSpecQuality(spec),
-        validateSpecFormat(spec, { readinessMode: mode, skipQuality: true }),
-    ]);
-    // SPEC-716: Ground ready flag in unified ValidationResult.
+    // validateSpecFormat owns the readiness and quality evaluation so the response
+    // cannot combine separately computed evidence from different reads of spec.md.
+    const validationResult = await validateSpecFormat(spec, { readinessMode: mode });
+    // SPEC-716: Ground ready flag in unified SpecValidationResult.
     // Only non-file-access errors from validateSpecFormat are surfaced in the
     // report — MISSING_FRONTMATTER due to file-not-found is best-effort since
     // the readiness checker already handles missing files gracefully.
     const vr = validationResult;
+    const report = vr.readinessReport ?? createFailClosedReport(spec.id, mode);
     const hardFormatErrors = vr.errors.filter((e) => e.code !== 'MISSING_FRONTMATTER' && !(e.code === 'READINESS_CHECK_FAILED'));
     const hardFormatMessages = hardFormatErrors.map((e) => e.message);
     const formatWarnings = vr.warnings
@@ -142,11 +153,24 @@ export async function handleCheckReadiness(args) {
     // Ground ready: only false if BOTH readiness report and format gate agree
     // (or format has hard non-file errors)
     report.ready = report.ready && hardFormatErrors.length === 0;
+    const canonicalFailure = canonicalReadinessFailure(vr);
+    if (canonicalFailure !== null) {
+        const target = mode === 'strict' ? report.issues.blockers : report.issues.warnings;
+        if (!target.includes(canonicalFailure)) {
+            target.push(canonicalFailure);
+        }
+        if (!report.recommendations.includes(`Resolve ${canonicalFailure} before implementation.`)) {
+            report.recommendations.push(`Resolve ${canonicalFailure} before implementation.`);
+        }
+        // Lenient mode is advisory, but it must not present a contradictory
+        // canonical validation result as an implementation-ready pass.
+        report.ready = false;
+    }
     // SPEC-612: recommend adding outOfScope items when none are declared
     if (spec.outOfScope === undefined || spec.outOfScope.length === 0) {
         report.recommendations.push('Add outOfScope items to the spec frontmatter to declare explicit scope boundaries (SPEC-612). This reduces scope creep during implementation.');
     }
-    const qualityScore = qualityReport.score;
+    const qualityScore = vr.qualityReport?.score;
     const formatted = formatReport(report);
     const humanSummary = buildCheckReadinessSummary(report.score, report.issues.blockers.length);
     return {
@@ -161,7 +185,7 @@ export async function handleCheckReadiness(args) {
             mode: report.mode,
             issues: report.issues,
             recommendations: report.recommendations,
-            qualityScore,
+            ...(qualityScore === undefined ? {} : { qualityScore }),
             humanSummary,
             validationResult: vr,
         },

package/dist/tools/configure-telemetry.js

@@ -1,9 +1,30 @@
 import { readTelemetryConfig, writeTelemetryConfig, TELEMETRY_CONSENT_VERSION, } from '../engine/telemetry/index.js';
 import { compactResult, compactError, formatKeyValue } from './output-formatter.js';
+function isLoopbackHost(hostname) {
+    return hostname === 'localhost' || hostname === '127.0.0.1' || hostname === '[::1]';
+}
+function isTelemetryConfigured() {
+    const endpoint = process.env.PLANU_TELEMETRY_ENDPOINT?.trim();
+    const token = process.env.PLANU_TELEMETRY_TOKEN?.trim();
+    if (!endpoint || !token) {
+        return false;
+    }
+    try {
+        const parsed = new URL(endpoint);
+        return (parsed.username === '' &&
+            parsed.password === '' &&
+            (parsed.protocol === 'https:' ||
+                (parsed.protocol === 'http:' && isLoopbackHost(parsed.hostname))));
+    }
+    catch {
+        return false;
+    }
+}
 export async function handleConfigureTelemetry(input) {
     try {
         const existing = await readTelemetryConfig();
         const enabled = existing?.enabled === true && existing.consentVersion === TELEMETRY_CONSENT_VERSION;
+        const configured = isTelemetryConfigured();
         if (input.action === 'status') {
             const observatoryStatus = existing?.enableObservatory === true
                 ? ' Observatory: ENABLED (cross-project insights active).'
@@ -11,9 +32,12 @@ export async function handleConfigureTelemetry(input) {
             const result = {
                 action: 'status',
                 enabled,
+                configured,
                 consentVersion: existing?.consentVersion,
                 message: (enabled
-                    ? 'Telemetry is ENABLED. Anonymous usage events are being sent to help improve Planu.'
+                    ? configured
+                        ? 'Telemetry is ENABLED and configured. Anonymous usage events may be sent to help improve Planu.'
+                        : 'Telemetry consent is ENABLED, but delivery is inactive: configure valid PLANU_TELEMETRY_ENDPOINT and PLANU_TELEMETRY_TOKEN values.'
                     : 'Telemetry is DISABLED. No data is being collected.') + observatoryStatus,
             };
             return compactResult(formatKeyValue(result));
@@ -31,8 +55,11 @@ export async function handleConfigureTelemetry(input) {
             const result = {
                 action: 'enable',
                 enabled: true,
+                configured,
                 consentVersion: TELEMETRY_CONSENT_VERSION,
-                message: 'Telemetry ENABLED. Thank you! Only anonymous usage data is collected — ' +
+                message: (configured
+                    ? 'Telemetry ENABLED and configured. Only anonymous usage data is collected — '
+                    : 'Telemetry consent ENABLED, but delivery is inactive until valid PLANU_TELEMETRY_ENDPOINT and PLANU_TELEMETRY_TOKEN values are configured. ') +
                     'no paths, emails, identifiers, source content, or raw errors. ' +
                     'Run configure_telemetry with action=disable to opt out anytime.' +
                     observatoryNote,
@@ -49,6 +76,7 @@ export async function handleConfigureTelemetry(input) {
         const result = {
             action: 'disable',
             enabled: false,
+            configured,
             consentVersion: existing?.consentVersion,
             message: 'Telemetry DISABLED. No usage data will be sent.',
         };

package/dist/tools/create-spec/spec-builder.d.ts

@@ -13,4 +13,11 @@ export declare function buildSpecContext(params: CreateSpecInput): Promise<{
 export declare function buildSplitResult(splitSuggestion: ReturnType<typeof analyzeSplit>, experienceLevel: string | undefined): Record<string, unknown> | undefined;
 /** Infer meaningful tags from title and description when no tags were provided. */
 export declare function inferTagsFromContent(title: string, description: string, type?: string): string[];
+/**
+ * SPEC-1351: Recompute the next spec id from a fresh store + filesystem scan.
+ * Called once (unlocked) during prepare to pick a candidate id, and again
+ * inside the exclusive create-spec write lock immediately before persisting
+ * so the id actually written can never collide under concurrency.
+ */
+export declare function computeNextSpecId(projectPath: string, projectId: string): Promise<string>;
 //# sourceMappingURL=spec-builder.d.ts.map

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

@@ -2,8 +2,6 @@
 // tools/create-spec/spec-builder.ts — Builds the Spec object and estimation (SPEC-461: lean format).
 // Extracted from create-spec.ts to keep file sizes within limits.
 import { hashProjectPath, knowledgeStore, specStore, globalStore } from '../../storage/index.js';
-import { getCurrentTier } from '../license-gate.js';
-import { checkLimits } from '../../engine/license-validator.js';
 import { inferDifficulty, calculateEstimation } from '../../engine/estimator.js';
 import { analyzeSplit, formatSplitSuggestion } from '../../engine/spec-splitter.js';
 import { isLegacyLocation, getSpecFileNames } from '../../engine/planu-config-writer.js';
@@ -25,19 +23,13 @@ export async function buildSpecContext(params) {
     const projectId = hashProjectPath(projectPath);
     const knowledge = await knowledgeStore.getKnowledge(projectId);
     const existingSpecs = await specStore.listSpecs(projectId);
-    // License: check active spec limit (exclude completed specs)
-    const activeSpecs = existingSpecs.filter((s) => s.status !== 'done' && s.status !== 'discarded');
-    const tier = await getCurrentTier();
-    const specLimit = checkLimits(tier, activeSpecs.length, 'maxActiveSpecs');
-    /* v8 ignore start -- license limit requires paid tier test env */
-    if (!specLimit.allowed) {
-        return { ok: false, errorMessage: specLimit.message };
-    }
-    /* v8 ignore stop */
-    // Generate spec ID: combine store IDs + filesystem IDs for global max
-    const fsSpecIds = await scanFilesystemSpecIds(projectPath);
-    const allSpecs = [...existingSpecs, ...fsSpecIds.map((id) => ({ id }))];
-    const specId = generateSpecId(allSpecs);
+    // Generate spec ID: combine store IDs + filesystem IDs for global max.
+    // SPEC-1351: this snapshot read is NOT locked — under concurrency two callers
+    // can compute the same "next" id here. create-spec.ts re-derives the id via
+    // computeNextSpecId() again inside its exclusive per-project write lock right
+    // before persisting, so a stale id computed here is only ever a starting
+    // candidate, never the value that actually gets written to disk.
+    const specId = await computeNextSpecId(projectPath, projectId);
     const slug = slugify(title);
     // Check for duplicate title
     const duplicate = existingSpecs.find((s) => slugify(s.title) === slug);
@@ -220,6 +212,18 @@ function buildTags(tags, feature, _title, _description, _type) {
     const result = feature ? [...new Set([...explicitTags, slugify(feature)])] : explicitTags;
     return [...new Set(result)];
 }
+/**
+ * SPEC-1351: Recompute the next spec id from a fresh store + filesystem scan.
+ * Called once (unlocked) during prepare to pick a candidate id, and again
+ * inside the exclusive create-spec write lock immediately before persisting
+ * so the id actually written can never collide under concurrency.
+ */
+export async function computeNextSpecId(projectPath, projectId) {
+    const existingSpecs = await specStore.listSpecs(projectId);
+    const fsSpecIds = await scanFilesystemSpecIds(projectPath);
+    const allSpecs = [...existingSpecs, ...fsSpecIds.map((id) => ({ id }))];
+    return generateSpecId(allSpecs);
+}
 /* v8 ignore start -- filesystem scanning is best-effort, tested via integration */
 /** Scan filesystem for SPEC-XXX directories to find max ID globally. */
 async function scanFilesystemSpecIds(projectPath) {

package/dist/tools/create-spec.d.ts

@@ -1,4 +1,5 @@
 import type { CreateSpecInput, ToolResult } from '../types/index.js';
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function resolveGroundedVerificationCommands(projectPath: string, testPaths: string[]): Promise<string[]>;
 export declare function handleCreateSpec(inputParams: CreateSpecInput, server?: McpServer): Promise<ToolResult>;
 //# sourceMappingURL=create-spec.d.ts.map