@planu/cli 5.0.0 → 5.2.0

package/dist/engine/worker-config-loader.js

@@ -103,9 +103,6 @@ export class WorkerConfigLoader {
         if (typeof raw.priority === 'number') {
             override.priority = raw.priority;
         }
-        if (raw.tier === 'free' || raw.tier === 'pro') {
-            override.tier = raw.tier;
-        }
         return override;
     }
     /**
@@ -113,7 +110,7 @@ export class WorkerConfigLoader {
      *
      * Slug-to-env: 'test-gaps' → 'TEST_GAPS'
      * Full pattern: PLANU_WORKER_{WORKER_ENV}_{SETTING}
-     * Known settings: ENABLED (bool), COOLDOWNMS (number), PRIORITY (number), TIER (string)
+     * Known settings: ENABLED (bool), COOLDOWNMS (number), PRIORITY (number)
      */
     parseEnvOverride(workerName) {
         const envName = workerName.toUpperCase().replace(/-/g, '_');
@@ -137,10 +134,6 @@ export class WorkerConfigLoader {
                 override.priority = parsed;
             }
         }
-        const tierRaw = process.env[`${prefix}TIER`];
-        if (tierRaw === 'free' || tierRaw === 'pro') {
-            override.tier = tierRaw;
-        }
         return override;
     }
     /**
@@ -158,9 +151,6 @@ export class WorkerConfigLoader {
         if (override.priority !== undefined) {
             result.priority = override.priority;
         }
-        if (override.tier !== undefined) {
-            result.tier = override.tier;
-        }
         return result;
     }
 }

package/dist/engine/workers/schema.d.ts

@@ -26,10 +26,6 @@ export declare const WorkerDefinitionSchema: z.ZodObject<{
     priority: z.ZodNumber;
     cooldownMs: z.ZodNumber;
     enabled: z.ZodBoolean;
-    tier: z.ZodEnum<{
-        free: "free";
-        pro: "pro";
-    }>;
 }, z.core.$strip>;
 export declare const WorkerRegistrySchema: z.ZodObject<{
     workers: z.ZodArray<z.ZodObject<{
@@ -49,10 +45,6 @@ export declare const WorkerRegistrySchema: z.ZodObject<{
         priority: z.ZodNumber;
         cooldownMs: z.ZodNumber;
         enabled: z.ZodBoolean;
-        tier: z.ZodEnum<{
-            free: "free";
-            pro: "pro";
-        }>;
     }, z.core.$strip>>;
 }, z.core.$strip>;
 //# sourceMappingURL=schema.d.ts.map

package/dist/engine/workers/schema.js

@@ -33,7 +33,6 @@ export const WorkerDefinitionSchema = z.object({
     priority: z.number().int().min(1).max(10).describe('Priority 1-10, higher = more important'),
     cooldownMs: z.number().int().min(0).describe('Minimum milliseconds between executions'),
     enabled: z.boolean().describe('Whether the worker is active'),
-    tier: z.enum(['free', 'pro']).describe('License tier: free | pro'),
 });
 export const WorkerRegistrySchema = z.object({
     workers: z.array(WorkerDefinitionSchema).max(1000).describe('List of worker definitions'),

package/dist/i18n/index.d.ts

@@ -1,4 +1,22 @@
 import type { SupportedLocale } from '../types/index.js';
+/**
+ * SPEC-1347: Resolve the locale from environment variables only — no I/O.
+ * Priority: PLANU_LOCALE env var, then the LANG/LC_ALL prefix, then 'en'.
+ */
+export declare function resolveLocaleFromEnv(env?: NodeJS.ProcessEnv): SupportedLocale;
+/**
+ * SPEC-1347: Resolve the locale to use at startup. Priority order:
+ * (1) persisted global config value, (2) PLANU_LOCALE env var,
+ * (3) LANG/LC_ALL env prefix mapped to a supported locale, (4) 'en' fallback.
+ * Never throws — unreadable/missing config falls through to env detection.
+ */
+export declare function resolveInitialLocale(env?: NodeJS.ProcessEnv): SupportedLocale;
+/**
+ * SPEC-1347: Recompute and apply the initial locale. Called once at module load to replace
+ * the previously hardcoded 'en' default; also exported so tests (and any future explicit
+ * re-init after a config change) can force recomputation deterministically.
+ */
+export declare function initLocale(env?: NodeJS.ProcessEnv): SupportedLocale;
 /**
  * Get the currently active locale.
  */

package/dist/i18n/index.js

@@ -4,11 +4,50 @@
 import { readFileSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import { dirname, join } from 'node:path';
+import { readPersistedGlobalConfigSync } from '../storage/global-store.js';
 // ---------------------------------------------------------------------------
 // Internal state
 // ---------------------------------------------------------------------------
 const SUPPORTED_LOCALES = ['en', 'es', 'pt'];
-let currentLocale = 'en';
+/**
+ * SPEC-1347: Resolve the locale from environment variables only — no I/O.
+ * Priority: PLANU_LOCALE env var, then the LANG/LC_ALL prefix, then 'en'.
+ */
+export function resolveLocaleFromEnv(env = process.env) {
+    const explicit = env.PLANU_LOCALE;
+    if (explicit && isSupportedLocale(explicit)) {
+        return explicit;
+    }
+    const langRaw = env.LANG ?? env.LC_ALL;
+    const prefix = langRaw?.slice(0, 2).toLowerCase();
+    if (prefix && isSupportedLocale(prefix)) {
+        return prefix;
+    }
+    return 'en';
+}
+/**
+ * SPEC-1347: Resolve the locale to use at startup. Priority order:
+ * (1) persisted global config value, (2) PLANU_LOCALE env var,
+ * (3) LANG/LC_ALL env prefix mapped to a supported locale, (4) 'en' fallback.
+ * Never throws — unreadable/missing config falls through to env detection.
+ */
+export function resolveInitialLocale(env = process.env) {
+    const persisted = readPersistedGlobalConfigSync();
+    if (persisted && isSupportedLocale(persisted.defaultLocale)) {
+        return persisted.defaultLocale;
+    }
+    return resolveLocaleFromEnv(env);
+}
+/**
+ * SPEC-1347: Recompute and apply the initial locale. Called once at module load to replace
+ * the previously hardcoded 'en' default; also exported so tests (and any future explicit
+ * re-init after a config change) can force recomputation deterministically.
+ */
+export function initLocale(env = process.env) {
+    currentLocale = resolveInitialLocale(env);
+    return currentLocale;
+}
+let currentLocale = resolveInitialLocale();
 /** Locale -> flattened key->value map */
 const messageCache = new Map();
 // ---------------------------------------------------------------------------

package/dist/server/routes/specs.js

@@ -26,9 +26,7 @@ const VALID_STATUSES = [
     'discarded',
 ];
 function containsReconciliationAuthorityFields(body) {
-    return ('reconciliationRequestId' in body ||
-        'expectedImplementingTransitionId' in body ||
-        'implementationReviewDigest' in body);
+    return 'reconciliationRequestId' in body || 'expectedImplementingTransitionId' in body;
 }
 /** Resolve projectPath from the request Host header or fallback to process.cwd(). */
 function getProjectPath(ctx) {
@@ -192,10 +190,13 @@ export async function handleUpdateSpecStatus(ctx) {
         sendBadRequest(ctx.res, 'Request body must be a JSON object');
         return;
     }
-    const { status } = body;
+    const { status, implementationReviewDigest } = body;
     if (containsReconciliationAuthorityFields(body)) {
         ctx.res.writeHead(403, { 'Content-Type': 'application/json' });
-        ctx.res.end(JSON.stringify({ error: 'Reconciliation is available only through local MCP.' }));
+        ctx.res.end(JSON.stringify({
+            error: 'Reconciliation is available only through local MCP.',
+            code: 'RECONCILIATION_UNTRUSTED_SURFACE',
+        }));
         return;
     }
     if (typeof status !== 'string' || !VALID_STATUSES.includes(status)) {
@@ -219,6 +220,7 @@ export async function handleUpdateSpecStatus(ctx) {
             projectPath,
             trigger: 'http',
             actor: 'http-api',
+            implementationReviewDigest: implementationReviewDigest,
         });
         if (result.isError) {
             const reason = result.content[0]?.type === 'text' ? result.content[0].text : 'Gate blocked transition';

package/dist/storage/global-store.d.ts

@@ -15,6 +15,15 @@ export declare function updateGlobalConfig(updates: Partial<GlobalConfig>): Prom
  * Set the default locale globally.
  */
 export declare function setDefaultLocale(locale: SupportedLocale): Promise<GlobalConfig>;
+/**
+ * SPEC-1347: Synchronous, best-effort read of the persisted global config.
+ *
+ * i18n needs a locale value before any async I/O can complete (module init time), so this
+ * mirrors `getGlobalConfig()` but reads the file synchronously and returns `null` — instead
+ * of defaults — when no config has ever been persisted. That distinction lets callers tell
+ * "never configured" (fall back to env detection) apart from "explicitly persisted".
+ */
+export declare function readPersistedGlobalConfigSync(): GlobalConfig | null;
 /**
  * Set the default experience level globally.
  */

package/dist/storage/global-store.js

@@ -1,6 +1,8 @@
 import { readJson, writeJson, globalDataDir } from './base-store.js';
 import { withFileLock } from './file-mutex.js';
 import { applyLearnedLimit, markVerified } from '../engine/registry-extender.js';
+import { readFileSync } from 'node:fs';
+import { reportClassifiedDegradation } from '../errors/classified-degradation.js';
 // --- file paths ---
 function configFile() {
     return `${globalDataDir()}/config.json`;
@@ -45,6 +47,27 @@ export async function updateGlobalConfig(updates) {
 export async function setDefaultLocale(locale) {
     return updateGlobalConfig({ defaultLocale: locale });
 }
+/**
+ * SPEC-1347: Synchronous, best-effort read of the persisted global config.
+ *
+ * i18n needs a locale value before any async I/O can complete (module init time), so this
+ * mirrors `getGlobalConfig()` but reads the file synchronously and returns `null` — instead
+ * of defaults — when no config has ever been persisted. That distinction lets callers tell
+ * "never configured" (fall back to env detection) apart from "explicitly persisted".
+ */
+export function readPersistedGlobalConfigSync() {
+    try {
+        const raw = readFileSync(configFile(), 'utf-8');
+        return { ...DEFAULT_CONFIG, ...JSON.parse(raw) };
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            return null;
+        }
+        reportClassifiedDegradation('GLOBAL_CONFIG_SYNC_READ_FAILURE', error);
+        return null;
+    }
+}
 /**
  * Set the default experience level globally.
  */

package/dist/storage/semantic-index-store.d.ts

@@ -0,0 +1,23 @@
+import { TFIDFEngine } from '../engine/vector-store/tfidf.js';
+import type { SemanticIndexDoc } from '../types/index.js';
+/**
+ * Persists a TF-IDF index for one logical corpus (e.g. all specs in a search
+ * scope, or a pattern type) and reconciles it incrementally against the
+ * current documents each time it is loaded.
+ */
+export declare class SemanticIndexStore {
+    private readonly filePath;
+    constructor(projectId: string, indexKey: string);
+    /**
+     * Load the persisted index and reconcile it with `docs`.
+     * - Unchanged documents are never re-embedded (`addDocument` is not called for them).
+     * - Changed or new documents are individually re-embedded and the index is re-persisted.
+     * - A missing, corrupted, schema-mismatched, or doc-removed index triggers a
+     *   transparent full rebuild so search always returns results.
+     */
+    loadOrBuild(docs: SemanticIndexDoc[]): Promise<TFIDFEngine>;
+    /** Full rebuild: fresh engine, `addDocument` for every doc, persist a new snapshot. */
+    private rebuildFull;
+    private persist;
+}
+//# sourceMappingURL=semantic-index-store.d.ts.map

package/dist/storage/semantic-index-store.js

@@ -0,0 +1,105 @@
+// storage/semantic-index-store.ts — Persisted TF-IDF index with incremental updates (SPEC-1345).
+// Avoids full corpus rebuilds on every semantic_search / learn call: persists the TF-IDF
+// engine state plus a per-document content-hash manifest, and only re-embeds documents
+// whose content changed since the last snapshot. A missing, corrupted, schema-mismatched,
+// or doc-removed index self-heals via a transparent full rebuild — never errors out.
+import { createHash } from 'node:crypto';
+import { readJson, writeJson, projectDataDir } from './base-store.js';
+import { withFileLock } from './file-mutex.js';
+import { TFIDFEngine, TFIDF_SCHEMA_VERSION, tokenize } from '../engine/vector-store/tfidf.js';
+function hashContent(content) {
+    return createHash('sha256').update(content).digest('hex');
+}
+function uniqueTokens(content) {
+    return [...new Set(tokenize(content))];
+}
+function isValidPersistedIndex(value) {
+    if (!value || typeof value !== 'object') {
+        return false;
+    }
+    const v = value;
+    return (v.schemaVersion === TFIDF_SCHEMA_VERSION &&
+        typeof v.docHashes === 'object' &&
+        v.docHashes !== null &&
+        typeof v.docTokens === 'object' &&
+        v.docTokens !== null &&
+        typeof v.tfidfState === 'object' &&
+        v.tfidfState !== null);
+}
+/**
+ * Persists a TF-IDF index for one logical corpus (e.g. all specs in a search
+ * scope, or a pattern type) and reconciles it incrementally against the
+ * current documents each time it is loaded.
+ */
+export class SemanticIndexStore {
+    filePath;
+    constructor(projectId, indexKey) {
+        this.filePath = `${projectDataDir(projectId)}/semantic-index-${indexKey}.json`;
+    }
+    /**
+     * Load the persisted index and reconcile it with `docs`.
+     * - Unchanged documents are never re-embedded (`addDocument` is not called for them).
+     * - Changed or new documents are individually re-embedded and the index is re-persisted.
+     * - A missing, corrupted, schema-mismatched, or doc-removed index triggers a
+     *   transparent full rebuild so search always returns results.
+     */
+    async loadOrBuild(docs) {
+        const persisted = await readJson(this.filePath, null);
+        if (!isValidPersistedIndex(persisted)) {
+            return this.rebuildFull(docs);
+        }
+        const currentIds = new Set(docs.map((d) => d.id));
+        const hadRemoval = Object.keys(persisted.docHashes).some((id) => !currentIds.has(id));
+        if (hadRemoval) {
+            return this.rebuildFull(docs);
+        }
+        const engine = new TFIDFEngine();
+        engine.importState(persisted.tfidfState);
+        const docHashes = { ...persisted.docHashes };
+        const docTokens = { ...persisted.docTokens };
+        let changed = false;
+        for (const doc of docs) {
+            const hash = hashContent(doc.content);
+            if (docHashes[doc.id] === hash) {
+                continue;
+            }
+            const oldTokens = docTokens[doc.id];
+            if (oldTokens) {
+                engine.removeDocument(oldTokens);
+            }
+            engine.addDocument(doc.content);
+            docHashes[doc.id] = hash;
+            docTokens[doc.id] = uniqueTokens(doc.content);
+            changed = true;
+        }
+        if (changed) {
+            await this.persist(engine, docHashes, docTokens);
+        }
+        return engine;
+    }
+    /** Full rebuild: fresh engine, `addDocument` for every doc, persist a new snapshot. */
+    async rebuildFull(docs) {
+        const engine = new TFIDFEngine();
+        const docHashes = {};
+        const docTokens = {};
+        for (const doc of docs) {
+            engine.addDocument(doc.content);
+            docHashes[doc.id] = hashContent(doc.content);
+            docTokens[doc.id] = uniqueTokens(doc.content);
+        }
+        await this.persist(engine, docHashes, docTokens);
+        return engine;
+    }
+    async persist(engine, docHashes, docTokens) {
+        const state = {
+            schemaVersion: TFIDF_SCHEMA_VERSION,
+            docHashes,
+            docTokens,
+            tfidfState: engine.exportState(),
+        };
+        await withFileLock(this.filePath, async () => {
+            await writeJson(this.filePath, state);
+        });
+    }
+}
+//# sourceMappingURL=semantic-index-store.js.map

package/dist/storage/status-store/self-healing.js

@@ -110,7 +110,7 @@ export async function quarantineCorruptStatus(statusPath, projectPath) {
     }
     return { quarantinedAt: new Date().toISOString(), quarantinePath };
 }
-import { isNativeActive, fastScanSpecs } from '../../engine/core-bridge.js';
+import { fastScanSpecsAsync } from '../../engine/core-bridge.js';
 /**
  * Rebuild a fresh status.json by reading all spec.md frontmatters.
  * Returns the new ProjectStatus object (not written to disk — caller decides).
@@ -120,23 +120,21 @@ export async function rebuildStatusFromFrontmatters(params) {
     const byStatus = {};
     const byType = {};
     let totalSpecs = 0;
-    if (isNativeActive()) {
-        const briefs = fastScanSpecs(projectPath);
-        if (briefs) {
-            for (const b of briefs) {
-                totalSpecs++;
-                byStatus[b.status] = (byStatus[b.status] ?? 0) + 1;
-                byType[b.specType] = (byType[b.specType] ?? 0) + 1;
-            }
-            return {
-                updatedAt: new Date().toISOString(),
-                totalSpecs,
-                byStatus,
-                byType,
-                recentChanges: [],
-                version: PLANU_VERSION,
-            };
+    const { value: briefs } = await fastScanSpecsAsync(projectPath);
+    if (briefs) {
+        for (const b of briefs) {
+            totalSpecs++;
+            byStatus[b.status] = (byStatus[b.status] ?? 0) + 1;
+            byType[b.specType] = (byType[b.specType] ?? 0) + 1;
         }
+        return {
+            updatedAt: new Date().toISOString(),
+            totalSpecs,
+            byStatus,
+            byType,
+            recentChanges: [],
+            version: PLANU_VERSION,
+        };
     }
     const specsDir = join(projectPath, 'planu', 'specs');
     const byStatusResult = {};

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

@@ -61,7 +61,11 @@ const CAPABILITY_SIGNALS = {
         /\b(?:email\s+address|phone\s+number|social\s+security\s+number)\b/i,
     ],
     events: [
-        /\b(?:process|handle|publish|consume)\w*(?:\s+[a-z0-9_-]+){0,3}\s+event\b/i,
+        // Negative lookahead excludes runtime compounds like "event-loop"/"event-driven": a
+        // hyphen right after "event" means the match is a prefix of a different word, not the
+        // noun "event" itself (SPEC-1262 — handler identifiers must not cross clause boundaries
+        // into unrelated event-loop prose).
+        /\b(?:process|handle|publish|consume)\w*(?:\s+[a-z0-9_-]+){0,3}\s+event\b(?!-)/i,
         /\b(?:event\s+(?:schema|contract|producer|consumer|handler|stream)|message\s+(?:broker|queue|consumer|producer))\b/i,
         /\b(?:kafka|rabbitmq|pubsub|nats|eventbridge|sqs|sns|dead[ -]?letter\s+queue|dlq)\b/i,
         /\b(?:publish|produce|consume)(?:es|d|r|rs|ing)?\s+(?:an?\s+)?(?:event|message)\b/i,

package/dist/tools/challenge-spec-helpers.d.ts

@@ -1,5 +1,14 @@
 import type { FailureScenario, ConcurrencyAnalysis, RiskLevel, Spec, ProjectKnowledge } from '../types/index.js';
-export declare function generateConcurrencyAnalysis(_spec: Spec, content: string, _knowledge: ProjectKnowledge): ConcurrencyAnalysis;
+/**
+ * Result of generateConcurrencyAnalysis. `suppressedCount` tracks candidates
+ * that matched a domain keyword (counter/status/file/session/cache) but were
+ * dropped because the spec content contains no corroborating concurrency
+ * context (e.g. "concurrent", "simultaneously", "multiple users") — SPEC-1350.
+ */
+export interface ConcurrencyAnalysisResult extends ConcurrencyAnalysis {
+    suppressedCount: number;
+}
+export declare function generateConcurrencyAnalysis(_spec: Spec, content: string, _knowledge: ProjectKnowledge): ConcurrencyAnalysisResult;
 export declare function buildScalabilityAssessment(spec: Spec, knowledge: ProjectKnowledge, scenarios: FailureScenario[]): string;
 export declare function calculateOverallRisk(scenarios: FailureScenario[], concurrency: ConcurrencyAnalysis): RiskLevel;
 export declare function readSpecContent(spec: Spec): Promise<string>;

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

@@ -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,