@planu/cli 4.14.1 → 5.0.0

package/dist/storage/status-store/atomic-status-write.js

@@ -0,0 +1,57 @@
+import { readdir, unlink } from 'node:fs/promises';
+import { basename, dirname } from 'node:path';
+import { reportClassifiedDegradation } from '../../errors/classified-degradation.js';
+import { atomicWriteFile } from '../../engine/safety/atomic-write-file.js';
+/** Publish one complete canonical status snapshot with same-directory atomic replacement. */
+export function atomicStatusWrite(statusPath, status) {
+    return atomicWriteFile(statusPath, JSON.stringify(status, null, 2));
+}
+function processIsDead(pid) {
+    try {
+        process.kill(pid, 0);
+        return false;
+    }
+    catch (error) {
+        if (error.code === 'ESRCH') {
+            return true;
+        }
+        reportClassifiedDegradation('STATUS_PROCESS_PROBE', error);
+        return false;
+    }
+}
+/** Remove only default atomic-write temporaries whose local owner process is dead. */
+export async function cleanupDeadStatusTemps(statusPath) {
+    const directory = dirname(statusPath);
+    const prefix = `${basename(statusPath)}.tmp.`;
+    let entries;
+    try {
+        entries = await readdir(directory, { withFileTypes: true });
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            return 0;
+        }
+        throw error;
+    }
+    let removed = 0;
+    for (const entry of entries) {
+        if (!entry.isFile() || !entry.name.startsWith(prefix)) {
+            continue;
+        }
+        const ownerPid = /^(\d+)\.[0-9a-f]{8}$/.exec(entry.name.slice(prefix.length))?.[1];
+        if (ownerPid === undefined || !processIsDead(Number(ownerPid))) {
+            continue;
+        }
+        try {
+            await unlink(`${directory}/${entry.name}`);
+            removed += 1;
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT') {
+                throw error;
+            }
+        }
+    }
+    return removed;
+}
+//# sourceMappingURL=atomic-status-write.js.map

package/dist/storage/status-store/file-lock.js

@@ -1,10 +1,10 @@
 // storage/status-store/file-lock.ts — SPEC-753: File-lock for status.json / pending.json writes
 //
-// Uses an in-memory async queue (same pattern as file-mutex.ts) with a 5-second timeout.
-// This prevents the concurrent-write race that corrupted status.json on 2026-04-24.
-//
-// Why not proper-lockfile? proper-lockfile requires process-level coordination; our server
-// is single-process, so in-memory serialization is sufficient and has zero dep overhead.
+// Uses a local FIFO for fair in-process ordering and the existing SQLite fenced lease for
+// exclusion across CLI, MCP, durable-worker, and background-side-effect processes.
+import { resolve } from 'node:path';
+import { acquireLock, releaseLock } from '../../engine/safety/file-mutex.js';
+import { cleanupDeadStatusTemps } from './atomic-status-write.js';
 const lockQueues = new Map();
 export const STATUS_LOCK_TIMEOUT_MS = 5_000;
 export const STATUS_LOCK_ERROR_CODE = 'status_lock_timeout';
@@ -14,11 +14,12 @@ export const STATUS_LOCK_ERROR_CODE = 'status_lock_timeout';
  * Throws with code `status_lock_timeout` if the lock is not acquired within 5 s.
  */
 export async function withStatusLock(filePath, fn) {
+    const startedAt = Date.now();
     // Race the wait for the previous lock against the timeout
     const prev = lockQueues.get(filePath) ?? Promise.resolve();
     let release;
-    const next = new Promise((resolve) => {
-        release = resolve;
+    const next = new Promise((resolveQueue) => {
+        release = resolveQueue;
     });
     lockQueues.set(filePath, next);
     let timeout;
@@ -52,14 +53,32 @@ export async function withStatusLock(filePath, fn) {
             clearTimeout(timeout);
         }
     }
+    let lease;
     try {
+        const remainingMs = Math.max(1, STATUS_LOCK_TIMEOUT_MS - (Date.now() - startedAt));
+        try {
+            lease = await acquireLock(resolve(filePath), remainingMs);
+        }
+        catch (error) {
+            const lockError = new Error(`[Planu] ${STATUS_LOCK_ERROR_CODE}: could not acquire cross-process write-lock on ${filePath}`, { cause: error });
+            lockError.code = STATUS_LOCK_ERROR_CODE;
+            throw lockError;
+        }
+        await cleanupDeadStatusTemps(resolve(filePath));
         return await fn();
     }
     finally {
-        release();
-        // Clean up only if no newer lock has been queued
-        if (lockQueues.get(filePath) === next) {
-            lockQueues.delete(filePath);
+        try {
+            if (lease) {
+                await releaseLock(lease);
+            }
+        }
+        finally {
+            release();
+            // Clean up only if no newer lock has been queued
+            if (lockQueues.get(filePath) === next) {
+                lockQueues.delete(filePath);
+            }
         }
     }
 }

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

@@ -5,9 +5,10 @@
 // a file where a valid JSON document is followed by trailing content from a second
 // partial write — i.e. JSON.parse fails at non-zero offset.
 import { readFile, writeFile, rename, mkdir, readdir } from 'node:fs/promises';
-import { join, dirname } from 'node:path';
+import { join } from 'node:path';
 import { reportClassifiedDegradation } from '../../errors/classified-degradation.js';
 import { PLANU_VERSION } from '../../config/version.js';
+import { atomicStatusWrite } from './atomic-status-write.js';
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
@@ -181,8 +182,7 @@ export async function rebuildStatusFromFrontmatters(params) {
  * Use this after `rebuildStatusFromFrontmatters` to persist the rebuild.
  */
 export async function writeRebuiltStatus(statusPath, status) {
-    await mkdir(dirname(statusPath), { recursive: true });
-    await writeFile(statusPath, JSON.stringify(status, null, 2), 'utf-8');
+    await atomicStatusWrite(statusPath, status);
 }
 // ---------------------------------------------------------------------------
 // Internal: minimal YAML frontmatter parser

package/dist/storage/status-store/version-sync.d.ts

@@ -1,7 +1,8 @@
 /**
  * Sync the `version` field in status.json with the current runtime.
  * No-op if the version is already current or the file doesn't exist.
- * Idempotent within a session (tracks synced paths to avoid redundant I/O).
+ * The snapshot is always revalidated under the cross-process lease because another
+ * Planu process may replace it after any local observation.
  */
 export declare function syncVersionField(statusPath: string, force?: boolean): Promise<{
     synced: boolean;

package/dist/storage/status-store/version-sync.js

@@ -1,57 +1,52 @@
 // storage/status-store/version-sync.ts — SPEC-753: Version sync at startup + per-session
 //
 // Ensures status.json.version always reflects the current runtime Planu version.
-import { readFile, writeFile, mkdir } from 'node:fs/promises';
-import { dirname } from 'node:path';
+import { readFile } from 'node:fs/promises';
 import { PLANU_VERSION } from '../../config/version.js';
-/** Track which status.json paths have already been synced this server session. */
-const syncedPaths = new Set();
+import { atomicStatusWrite } from './atomic-status-write.js';
+import { withStatusLock } from './file-lock.js';
 /**
  * Sync the `version` field in status.json with the current runtime.
  * No-op if the version is already current or the file doesn't exist.
- * Idempotent within a session (tracks synced paths to avoid redundant I/O).
+ * The snapshot is always revalidated under the cross-process lease because another
+ * Planu process may replace it after any local observation.
  */
 export async function syncVersionField(statusPath, force = false) {
-    if (!force && syncedPaths.has(statusPath)) {
-        return { synced: false };
-    }
-    let raw;
-    try {
-        raw = await readFile(statusPath, 'utf-8');
-    }
-    catch (error) {
-        if (error.code === 'ENOENT') {
-            syncedPaths.add(statusPath);
-            return { synced: false };
+    void force;
+    return withStatusLock(statusPath, async () => {
+        let raw;
+        try {
+            raw = await readFile(statusPath, 'utf-8');
+        }
+        catch (error) {
+            if (error.code === 'ENOENT') {
+                return { synced: false };
+            }
+            throw error;
+        }
+        let parsed;
+        try {
+            const p = JSON.parse(raw);
+            if (typeof p !== 'object' || p === null || Array.isArray(p)) {
+                return { synced: false };
+            }
+            parsed = p;
+        }
+        catch (error) {
+            throw new Error(`Status file is corrupt: ${statusPath}`, { cause: error });
         }
-        throw error;
-    }
-    let parsed;
-    try {
-        const p = JSON.parse(raw);
-        if (typeof p !== 'object' || p === null || Array.isArray(p)) {
-            syncedPaths.add(statusPath);
+        const currentVersion = typeof parsed.version === 'string' ? parsed.version : undefined;
+        if (currentVersion === PLANU_VERSION) {
             return { synced: false };
         }
-        parsed = p;
-    }
-    catch (error) {
-        throw new Error(`Status file is corrupt: ${statusPath}`, { cause: error });
-    }
-    const currentVersion = typeof parsed.version === 'string' ? parsed.version : undefined;
-    if (currentVersion === PLANU_VERSION) {
-        syncedPaths.add(statusPath);
-        return { synced: false };
-    }
-    parsed.version = PLANU_VERSION;
-    parsed.updatedAt = new Date().toISOString();
-    await mkdir(dirname(statusPath), { recursive: true });
-    await writeFile(statusPath, JSON.stringify(parsed, null, 2), 'utf-8');
-    syncedPaths.add(statusPath);
-    return { synced: true, from: currentVersion, to: PLANU_VERSION };
+        parsed.version = PLANU_VERSION;
+        parsed.updatedAt = new Date().toISOString();
+        await atomicStatusWrite(statusPath, parsed);
+        return { synced: true, from: currentVersion, to: PLANU_VERSION };
+    });
 }
 /** Clear the session sync cache — TEST USE ONLY. */
 export function clearVersionSyncCache() {
-    syncedPaths.clear();
+    // Compatibility no-op: correctness requires revalidating every snapshot under the lease.
 }
 //# sourceMappingURL=version-sync.js.map

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

@@ -1,9 +1,5 @@
-import type { UsageLog, UsageEvent, TrialState } from '../types/index.js';
+import type { UsageLog, UsageEvent } from '../types/index.js';
 export declare function getUsageLog(): Promise<UsageLog>;
 export declare function appendUsageEvent(event: UsageEvent): Promise<void>;
 export declare function rotateUsageLog(): Promise<void>;
-export declare function getTrialState(): Promise<TrialState | null>;
-export declare function ensureTrialState(): Promise<TrialState>;
-export declare function getDailyCallCount(date: string): Promise<number>;
-export declare function getLastCallTimestamp(): Promise<string | null>;
 //# sourceMappingURL=usage-store.d.ts.map

package/dist/storage/usage-store.js

@@ -10,9 +10,6 @@ const MAX_EVENTS = 10_000;
 function usageFile() {
     return `${globalDataDir()}/usage.json`;
 }
-function firstRunFile() {
-    return `${globalDataDir()}/first-run.json`;
-}
 // ---------------------------------------------------------------------------
 // Usage log (data/global/usage.json)
 // ---------------------------------------------------------------------------
@@ -42,36 +39,4 @@ export async function appendUsageEvent(event) {
 export async function rotateUsageLog() {
     await withFileLock(usageFile(), rotateUsageLogLocked);
 }
-// ---------------------------------------------------------------------------
-// Trial state (data/global/first-run.json)
-// ---------------------------------------------------------------------------
-export async function getTrialState() {
-    return readJson(firstRunFile(), null);
-}
-export async function ensureTrialState() {
-    const existing = await getTrialState();
-    if (existing !== null) {
-        return existing;
-    }
-    const state = { firstRunAt: new Date().toISOString() };
-    await writeJson(firstRunFile(), state);
-    return state;
-}
-// ---------------------------------------------------------------------------
-// Computed helpers (derived from usage.json — no extra file)
-// ---------------------------------------------------------------------------
-export async function getDailyCallCount(date) {
-    const log = await getUsageLog();
-    return log.events.filter((event) => event.timestamp.startsWith(date)).length;
-}
-export async function getLastCallTimestamp() {
-    const log = await getUsageLog();
-    if (log.events.length === 0) {
-        return null;
-    }
-    const last = log.events[log.events.length - 1];
-    /* v8 ignore start -- always defined when length > 0 */
-    return last?.timestamp ?? null;
-    /* v8 ignore stop */
-}
 //# sourceMappingURL=usage-store.js.map

package/dist/tools/auto-update-handler.d.ts

@@ -9,17 +9,17 @@ export interface PinVersionInput {
 }
 /**
  * Checks npm registry and local config for update status.
- * Free tool — no license check.
+ * Checks update status without changing local state.
  */
 export declare function handleCheckUpdateStatus(): Promise<ToolResult>;
 /**
  * Resolves a verified release and pins the MCP config to that exact version.
- * Free tool — always benefits the user.
+ * Enables update checks for the local installation.
  */
 export declare function handleEnableAutoUpdate(args: EnableAutoUpdateInput): Promise<ToolResult>;
 /**
  * Pins Planu to a specific version in the MCP config.
- * Pro tool — requires license.
+ * Pins the local installation to an explicit version.
  */
 export declare function handlePinVersion(args: PinVersionInput): Promise<ToolResult>;
 //# sourceMappingURL=auto-update-handler.d.ts.map

package/dist/tools/auto-update-handler.js

@@ -7,7 +7,7 @@ import { jsonResult, errText } from './response-helpers.js';
 // ---------------------------------------------------------------------------
 /**
  * Checks npm registry and local config for update status.
- * Free tool — no license check.
+ * Checks update status without changing local state.
  */
 export async function handleCheckUpdateStatus() {
     try {
@@ -20,7 +20,7 @@ export async function handleCheckUpdateStatus() {
 }
 /**
  * Resolves a verified release and pins the MCP config to that exact version.
- * Free tool — always benefits the user.
+ * Enables update checks for the local installation.
  */
 export async function handleEnableAutoUpdate(args) {
     const confirm = args.confirm ?? false;
@@ -35,7 +35,7 @@ export async function handleEnableAutoUpdate(args) {
 }
 /**
  * Pins Planu to a specific version in the MCP config.
- * Pro tool — requires license.
+ * Pins the local installation to an explicit version.
  */
 export async function handlePinVersion(args) {
     if (!args.version || args.version.trim() === '') {

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

@@ -1,8 +1,9 @@
 import type { FailureScenario, Spec, ProjectKnowledge } from '../../types/index.js';
+import { type ChallengeCapabilities } from './scenarios-utils.js';
 export { EXTERNAL_CALL_KEYWORDS, VALIDATION_KEYWORDS, RATE_LIMIT_KEYWORDS, CONCURRENCY_KEYWORDS, SAGA_KEYWORDS, hasExternalCallSignal, hasValidationSignal, hasRateLimitSignal, hasConcurrencySignal, hasSagaSignal, generateValidationBoundaryScenarios, generateCascadeFailureScenarios, } from './resilience-challenge-scenarios-a.js';
 export { generateRateLimitBypassScenarios, generateConcurrencyScenarios, generateSagaFailureScenarios, } from './resilience-challenge-scenarios-b.js';
 /**
  * Main entry: generate all SPEC-034 resilience/concurrency challenges for a spec.
  */
-export declare function generateResilienceChallengeScenarios(spec: Spec, specContent: string, knowledge: ProjectKnowledge): FailureScenario[];
+export declare function generateResilienceChallengeScenarios(spec: Spec, specContent: string, knowledge: ProjectKnowledge, capabilities?: ChallengeCapabilities): FailureScenario[];
 //# sourceMappingURL=resilience-challenge-scenarios.d.ts.map

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

@@ -2,32 +2,35 @@
 // Barrel re-export for resilience/concurrency challenge scenarios.
 // Signal detectors + validation + cascade: resilience-challenge-scenarios-a.ts
 // Rate limit + concurrency + saga: resilience-challenge-scenarios-b.ts
-import { hasValidationSignal, hasExternalCallSignal, hasRateLimitSignal, hasConcurrencySignal, hasSagaSignal, generateValidationBoundaryScenarios, generateCascadeFailureScenarios, } from './resilience-challenge-scenarios-a.js';
+import { generateValidationBoundaryScenarios, generateCascadeFailureScenarios, } from './resilience-challenge-scenarios-a.js';
 import { generateRateLimitBypassScenarios, generateConcurrencyScenarios, generateSagaFailureScenarios, } from './resilience-challenge-scenarios-b.js';
+import { detectChallengeCapabilities } from './scenarios-utils.js';
 export { EXTERNAL_CALL_KEYWORDS, VALIDATION_KEYWORDS, RATE_LIMIT_KEYWORDS, CONCURRENCY_KEYWORDS, SAGA_KEYWORDS, hasExternalCallSignal, hasValidationSignal, hasRateLimitSignal, hasConcurrencySignal, hasSagaSignal, generateValidationBoundaryScenarios, generateCascadeFailureScenarios, } from './resilience-challenge-scenarios-a.js';
 export { generateRateLimitBypassScenarios, generateConcurrencyScenarios, generateSagaFailureScenarios, } from './resilience-challenge-scenarios-b.js';
 /**
  * Main entry: generate all SPEC-034 resilience/concurrency challenges for a spec.
  */
-export function generateResilienceChallengeScenarios(spec, specContent, knowledge) {
+export function generateResilienceChallengeScenarios(spec, specContent, knowledge, capabilities) {
     const scenarios = [];
-    if (hasValidationSignal(spec, specContent)) {
+    const resolvedCapabilities = capabilities ?? detectChallengeCapabilities(spec, specContent);
+    if (resolvedCapabilities.validation &&
+        (resolvedCapabilities.userInput || resolvedCapabilities.networkApi)) {
         scenarios.push(...generateValidationBoundaryScenarios(spec));
     }
-    if (hasExternalCallSignal(spec, specContent)) {
+    if (resolvedCapabilities.externalService || resolvedCapabilities.payment) {
         scenarios.push(...generateCascadeFailureScenarios(spec));
     }
-    if (hasRateLimitSignal(spec, specContent)) {
+    if (resolvedCapabilities.rateLimit) {
         scenarios.push(...generateRateLimitBypassScenarios(spec));
     }
-    if (hasConcurrencySignal(spec, specContent)) {
+    if (resolvedCapabilities.concurrency) {
         // `concurrencyModel` may be present on enriched knowledge objects (ValidationResilienceProfile mixin)
         // but is not declared on the base ProjectKnowledge interface — intentional duck-type access.
         // ProjectKnowledge has no index signature, so `as unknown` intermediate is required.
         const concurrencyModel = knowledge.concurrencyModel;
         scenarios.push(...generateConcurrencyScenarios(spec, concurrencyModel ?? 'unknown'));
     }
-    if (hasSagaSignal(spec, specContent)) {
+    if (resolvedCapabilities.saga) {
         scenarios.push(...generateSagaFailureScenarios(spec));
     }
     return scenarios;

package/dist/tools/challenge-spec/scenario-collector.js

@@ -75,7 +75,7 @@ export function collectCapabilityScenarios(input) {
         'concurrency',
         'saga',
     ])) {
-        scenarios.push(...generateResilienceChallengeScenarios(spec, specContent, knowledge));
+        scenarios.push(...generateResilienceChallengeScenarios(spec, specContent, knowledge, capabilities));
     }
     const agileConfig = knowledge.agileConfig;
     if (agileConfig?.process === 'xp' && capabilities.xp) {

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

@@ -4,7 +4,7 @@ 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 CACHE_SIGNALS = [/\b(cache|cached|real-time|realtime|websocket|stale data)\b/i];
 const DUPLICATE_OPERATION_SIGNALS = [
     /\b(submit|form|checkout|order|payment|create record|mutation|button click)\b/i,
     /\bduplicate\s+(?:request|submission|operation|record)\b/i,

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

@@ -29,5 +29,5 @@ export interface ChallengeCapabilities {
 export declare function contentMentions(content: string, keywords: string[]): boolean;
 export declare function detectChallengeCapabilities(spec: Spec, specContent: string): ChallengeCapabilities;
 export declare function hasAnyChallengeCapability(capabilities: ChallengeCapabilities, names: (keyof ChallengeCapabilities)[]): boolean;
-export { hasAffirmedMatch, hasAnyAffirmedMatch, stripNonContractText, } from '../../engine/text-signal-boundaries.js';
+export { hasAffirmedMatch, hasAnyAffirmedMatch, stripMetaAnalysisText, stripNonContractText, } from '../../engine/text-signal-boundaries.js';
 //# sourceMappingURL=scenarios-utils.d.ts.map

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

@@ -1,5 +1,5 @@
 // tools/challenge-spec/scenarios-utils.ts — Shared utilities for scenario generators
-import { hasAnyAffirmedMatch } from '../../engine/text-signal-boundaries.js';
+import { hasAnyAffirmedMatch, stripMetaAnalysisText, stripNonContractText, } from '../../engine/text-signal-boundaries.js';
 const CAPABILITY_SIGNALS = {
     networkApi: [
         /(?<!compiler\s)\bapi\b(?!\s+(?:compatibility|surface|package|type))/i,
@@ -15,7 +15,7 @@ const CAPABILITY_SIGNALS = {
         /\b(?:orm|prisma|drizzle|typeorm|sequelize)\b/i,
     ],
     authentication: [
-        /\b(?:auth(?:entication)?|login|sign[ -]?in|password|jwt|oauth2?|session\s+auth)\b/i,
+        /\b(?:auth(?:entication|enticate)?|login|sign[ -]?in|password|jwt|oauth2?|session\s+auth)\b/i,
     ],
     authorization: [
         /\b(?:authori[sz]ation|permission|rbac|role-based|access\s+control|resource\s+ownership|tenant)\b/i,
@@ -26,10 +26,10 @@ const CAPABILITY_SIGNALS = {
         /\binputs?\s+(?:are\s+)?validat/i,
     ],
     externalService: [
-        /\b(?:third-party|external|remote|downstream)\s+(?:service|provider|dependency|system)\b/i,
+        /\b(?:third-party|external|remote|downstream)\s+(?:service|provider|dependency|system|api)\b/i,
         /\bwebhook\s+(?:provider|delivery|endpoint|request)\b/i,
     ],
-    payment: [/\b(?:payment|billing|checkout|invoice|stripe|paypal)\b/i],
+    payment: [/\b(?:payment|billing|invoice|stripe|paypal)\b/i],
     fileTransfer: [
         /\b(?:(?:large|binary|uploaded)\s+)?(?:file|image|media|attachment)\s+(?:upload|download|transfer|stream)\b/i,
         /\b(?:upload|download|stream)(?:ed|ing|s)?\s+(?:a\s+)?(?:(?:large|binary)\s+)?(?:file|image|media|attachment)\b/i,
@@ -43,8 +43,8 @@ const CAPABILITY_SIGNALS = {
     ],
     dataWrite: [
         /\b(?:database\s+transaction|persist(?:s|ed|ing)?\s+(?:record|entity|data)|write(?:s|ing)?\s+(?:record|entity|database))\b/i,
-        /\b(?:state-changing|data\s+mutation|atomic\s+database\s+write)\b/i,
-        /\b(?:transaction|atomic\s+write|update\s+(?:record|state)|modify\s+(?:record|state))\b/i,
+        /\b(?:state-changing|data\s+mutation|atomic\s+database\s+writes?)\b/i,
+        /\b(?:transaction|atomic\s+writes?|update\s+(?:record|state)|modify\s+(?:record|state))\b/i,
     ],
     cache: [/\b(?:cache|caching|cached\s+(?:data|response)|redis)\b/i],
     duplicateOperation: [
@@ -52,6 +52,7 @@ const CAPABILITY_SIGNALS = {
     ],
     concurrency: [
         /\b(?:concurren|race\s+condition|shared\s+state|parallel\s+write|atomic\s+increment|optimistic\s+lock)/i,
+        /\b(?:shared\b(?:\s+\w+){0,2}\s+(?:cache|resource|pool)|resource\s+(?:lock|pool))\b/i,
         /\b(?:counter|increment|balance|stock|quantity|vote|status\s+(?:update|transition))\b/i,
         /\b(?:file\s+upload|resource\s+manager|search\s+feed|list\s+endpoint|global\s+cache|session\s+state|cart\s+state|draft\s+state)\b/i,
     ],
@@ -76,8 +77,12 @@ const CAPABILITY_SIGNALS = {
     agent: [/\b(?:ai\s+agent|agent\s+contract|llm\s+agent|tool\s+call|autonomous\s+agent)\b/i],
     ddd: [/\b(?:domain-driven\s+design|ddd\s+aggregate|aggregate\s+root|bounded\s+context)\b/i],
     xp: [/\b(?:pair\s+programming|extreme\s+programming|xp\s+pair)\b/i],
-    validation: [/\b(?:input|payload|request|schema)\s+validat/i, /\b(?:zod|joi|json\s+schema)\b/i],
-    rateLimit: [/\b(?:rate[ -]?limit|throttl|request\s+quota)\b/i],
+    validation: [
+        /\b(?:input|payload|request|schema)\s+validat/i,
+        /\bvalidat(?:e|es|ed|ing|ion)\b/i,
+        /\b(?:zod|joi|json\s+schema)\b/i,
+    ],
+    rateLimit: [/\b(?:rate[ -]?limit(?:ing|ed|s)?|throttl|request\s+quota)\b/i],
     saga: [/\b(?:saga|compensating\s+transaction|distributed\s+transaction)\b/i],
     platform: [
         /\b(?:smart\s+contract|solidity|discord\s+bot|telegram\s+bot|iot\s+device|firmware|infrastructure\s+as\s+code|terraform|machine\s+learning\s+model)\b/i,
@@ -88,19 +93,38 @@ function keywordPattern(keyword) {
     const suffix = /^[a-z0-9]+$/i.test(keyword) && keyword.length > 3 ? '[a-z0-9_-]*' : '';
     return new RegExp(`\\b${escaped}${suffix}\\b`, 'i');
 }
+function whitespaceFlexiblePattern(text) {
+    return text
+        .trim()
+        .split(/\s+/)
+        .map((token) => token.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'))
+        .join('\\s+');
+}
+function stripReaderPrefix(spec, specContent) {
+    const readerPrefix = [spec.title, spec.type, spec.scope, spec.target, spec.tags.join(' ')]
+        .filter(Boolean)
+        .join(' ');
+    const prefixPattern = whitespaceFlexiblePattern(readerPrefix);
+    if (prefixPattern.length === 0) {
+        return specContent;
+    }
+    return specContent.replace(new RegExp(`^\\s*${prefixPattern}(?=\\s|$)`, 'u'), '').trimStart();
+}
 /** Boundary-aware, affirmative replacement for advisory substring checks. */
 export function contentMentions(content, keywords) {
     return hasAnyAffirmedMatch(content, keywords.map(keywordPattern));
 }
 export function detectChallengeCapabilities(spec, specContent) {
-    const text = `${spec.title}\n${spec.tags.join(' ')}\n${specContent}`;
+    const contractSource = stripReaderPrefix(spec, specContent);
+    const source = contractSource.trim().length > 0 ? contractSource : spec.title;
+    const contract = stripMetaAnalysisText(stripNonContractText(source));
     return Object.fromEntries(Object.entries(CAPABILITY_SIGNALS).map(([capability, patterns]) => [
         capability,
-        hasAnyAffirmedMatch(text, patterns),
+        hasAnyAffirmedMatch(contract, patterns),
     ]));
 }
 export function hasAnyChallengeCapability(capabilities, names) {
     return names.some((name) => capabilities[name]);
 }
-export { hasAffirmedMatch, hasAnyAffirmedMatch, stripNonContractText, } from '../../engine/text-signal-boundaries.js';
+export { hasAffirmedMatch, hasAnyAffirmedMatch, stripMetaAnalysisText, stripNonContractText, } from '../../engine/text-signal-boundaries.js';
 //# sourceMappingURL=scenarios-utils.js.map

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({

package/dist/tools/check-readiness.js

@@ -118,7 +118,7 @@ export async function handleCheckReadiness(args) {
         scoreSpecQuality(spec),
         validateSpecFormat(spec, { readinessMode: mode, skipQuality: true }),
     ]);
-    // SPEC-716: Ground ready flag in unified ValidationResult.
+    // 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.