@planu/cli 4.11.1 → 4.11.3

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

@@ -2,30 +2,13 @@
 // Generates backward-compatibility contract and idempotence challenges
 // for specs that produce or consume events.
 import { detectBrokers, getBrokerConfig, requiresIdempotence, } from '../../engine/event-detector.js';
+import { detectChallengeCapabilities } from './scenarios-utils.js';
 /**
  * Returns true when the spec or project has event-driven characteristics.
  */
 export function isEventDrivenSpec(spec, specContent, knowledge) {
-    const lower = `${spec.title} ${spec.tags.join(' ')} ${specContent}`.toLowerCase();
-    const specSignals = lower.includes('event') ||
-        lower.includes('kafka') ||
-        lower.includes('rabbitmq') ||
-        lower.includes('pubsub') ||
-        lower.includes('nats') ||
-        lower.includes('eventbridge') ||
-        lower.includes('sqs') ||
-        lower.includes('sns') ||
-        lower.includes('message') ||
-        lower.includes('consumer') ||
-        lower.includes('producer');
-    if (spec.target === 'frontend' && !specSignals) {
-        return false;
-    }
-    const brokers = detectBrokers(knowledge.stack);
-    if (specSignals) {
-        return true;
-    }
-    return brokers.length > 0 && brokers[0] !== 'unknown' && spec.target !== 'frontend';
+    void knowledge;
+    return detectChallengeCapabilities(spec, specContent).events;
 }
 /**
  * Generate event-driven failure scenarios for challenge_spec.
@@ -50,7 +33,7 @@ export function generateEventChallengeScenarios(spec, specContent, knowledge) {
         impact: 'critical',
         currentHandling: 'Schema change may not have a formal contract review — consumers may fail silently with unrecognized fields or crash on missing ones.',
         requiredHandling: 'Classify the change: additive (new optional field — safe), breaking (removed/type-changed field — requires dual-version emission), or deprecation (field marked deprecated with a sunset date). ' +
-            'For breaking changes: emit both old and new versions during the transition period (recommended: 2-4 weeks). ' +
+            'For breaking changes: emit both old and new versions during the transition period defined by the rollout plan. ' +
             'Update the event contract in event-contracts/ before merging.',
         dataConsistency: 'If the change is breaking and dual-version is not implemented, consumers will receive invalid events and may write corrupt state.',
         userExperience: 'Invisible to end users, but breaking event changes cause downstream service failures that eventually surface as user-facing errors.',
@@ -62,9 +45,7 @@ export function generateEventChallengeScenarios(spec, specContent, knowledge) {
             probability: 'high',
             impact: 'high',
             currentHandling: 'Consumer may lack a deduplication check — processing the same event twice could double-charge, double-ship, or create duplicate records.',
-            requiredHandling: 'Store the event ID (or a derived idempotency key) in a durable store (DB, Redis with TTL) before processing. ' +
-                'Check at the start of each consumer handler: if ID already processed, acknowledge and skip. ' +
-                'Choose the deduplication window based on expected redelivery window (typically 24h–7d).',
+            requiredHandling: 'Define the deduplication identifier, durable boundary, atomicity rule, and retention window from the event contract.',
             dataConsistency: 'The idempotency record must be written atomically with the side-effect (same DB transaction or two-phase commit) to avoid the "processed but not recorded" gap.',
             userExperience: 'Idempotence failure is invisible until users report duplicates (duplicate orders, double payments, etc.) — prevent, do not detect.',
         });
@@ -72,13 +53,13 @@ export function generateEventChallengeScenarios(spec, specContent, knowledge) {
     // 3. DLQ poisoned message challenge
     if (brokerConfig?.dlqSupport && brokerConfig.dlqSupport !== '') {
         scenarios.push({
-            scenario: `[${spec.id}] DLQ Poisoned Message: a consumer receives an event with a malformed payload (missing required field, wrong type, corrupt JSON). Does the consumer retry forever and block the queue? How many retries before the message goes to the DLQ?`,
+            scenario: `[${spec.id}] DLQ Poisoned Message: a consumer receives an event with a malformed payload. Does the consumer retry indefinitely and block the queue? Which declared failure condition moves the message to the DLQ?`,
             probability: 'medium',
             impact: 'high',
             currentHandling: 'Consumer may retry indefinitely on schema validation errors, blocking queue processing for all subsequent events.',
-            requiredHandling: 'Implement retry with exponential backoff (e.g., 1s, 2s, 4s, 8s, 16s). After max retries (e.g., 5), route to DLQ with original payload + error context. ' +
+            requiredHandling: 'Use the retry limit and delay policy declared by the event contract, then route terminal failures with enough diagnostic context. ' +
                 `DLQ support: ${brokerConfig.dlqSupport}. ` +
-                'Set an alert when DLQ depth exceeds threshold. Document the re-injection procedure for manual recovery.',
+                'Define the alert threshold and re-injection procedure from the operations contract.',
             dataConsistency: 'Messages in the DLQ must be investigated and re-injected only after the root cause is fixed — re-injecting without fix will loop back to DLQ.',
             userExperience: 'DLQ accumulation means events are not processed — monitor and alert before SLA is breached.',
         });

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

@@ -1,5 +1,6 @@
 // tools/challenge-spec/resilience-challenge-scenarios-a.ts — SPEC-034
 // Signal detectors + validation boundary + cascade failure scenarios
+import { contentMentions } from './scenarios-utils.js';
 // Keywords indicating external service calls or shared state
 export const EXTERNAL_CALL_KEYWORDS = [
     'api',
@@ -70,36 +71,31 @@ export const SAGA_KEYWORDS = [
  * Returns true when the spec describes an external service call.
  */
 export function hasExternalCallSignal(spec, specContent) {
-    const lower = `${spec.title} ${spec.tags.join(' ')} ${specContent}`.toLowerCase();
-    return EXTERNAL_CALL_KEYWORDS.some((kw) => lower.includes(kw));
+    return contentMentions(`${spec.title}\n${spec.tags.join(' ')}\n${specContent}`, EXTERNAL_CALL_KEYWORDS);
 }
 /**
  * Returns true when the spec describes input validation.
  */
 export function hasValidationSignal(spec, specContent) {
-    const lower = `${spec.title} ${spec.tags.join(' ')} ${specContent}`.toLowerCase();
-    return VALIDATION_KEYWORDS.some((kw) => lower.includes(kw));
+    return contentMentions(`${spec.title}\n${spec.tags.join(' ')}\n${specContent}`, VALIDATION_KEYWORDS);
 }
 /**
  * Returns true when the spec is a rate-limit-sensitive endpoint.
  */
 export function hasRateLimitSignal(spec, specContent) {
-    const lower = `${spec.title} ${spec.tags.join(' ')} ${specContent}`.toLowerCase();
-    return RATE_LIMIT_KEYWORDS.some((kw) => lower.includes(kw));
+    return contentMentions(`${spec.title}\n${spec.tags.join(' ')}\n${specContent}`, RATE_LIMIT_KEYWORDS);
 }
 /**
  * Returns true when the spec involves shared state.
  */
 export function hasConcurrencySignal(spec, specContent) {
-    const lower = `${spec.title} ${spec.tags.join(' ')} ${specContent}`.toLowerCase();
-    return CONCURRENCY_KEYWORDS.some((kw) => lower.includes(kw));
+    return contentMentions(`${spec.title}\n${spec.tags.join(' ')}\n${specContent}`, CONCURRENCY_KEYWORDS);
 }
 /**
  * Returns true when the spec describes a distributed saga.
  */
 export function hasSagaSignal(spec, specContent) {
-    const lower = `${spec.title} ${spec.tags.join(' ')} ${specContent}`.toLowerCase();
-    return SAGA_KEYWORDS.some((kw) => lower.includes(kw));
+    return contentMentions(`${spec.title}\n${spec.tags.join(' ')}\n${specContent}`, SAGA_KEYWORDS);
 }
 /**
  * Generate validation boundary challenge scenarios.
@@ -161,38 +157,26 @@ export function generateValidationBoundaryScenarios(spec) {
 export function generateCascadeFailureScenarios(spec) {
     return [
         {
-            scenario: `[${spec.id}] Cascade Failure — Connection Pool Exhaustion: ` +
-                'If the external service starts responding in 30 seconds (OS timeout) instead of the expected 200ms, ' +
-                'how many simultaneous requests accumulate in the connection pool before the circuit breaker activates? ' +
-                'If the pool has size N and each request holds a connection for T seconds, the pool fills in N * T seconds. ' +
-                'Calculate this with the actual pool size and timeout values. ' +
-                'Does the circuit breaker open before the pool is exhausted?',
+            scenario: `[${spec.id}] Cascade Failure — Dependency Latency Exhausts Local Capacity: ` +
+                'Which latency and capacity envelope is declared for the dependency? ' +
+                'Does failure isolation activate before workers, connections, or queued work are exhausted?',
             probability: 'medium',
             impact: 'critical',
-            currentHandling: 'Without a circuit breaker, slow external services cause connection pool exhaustion, ' +
-                'blocking all requests to this service (not just those calling the external service).',
-            requiredHandling: 'Set connect_timeout (2s) and read_timeout (10s) — never rely on OS timeout (30s+). ' +
-                'Circuit breaker must open before pool exhaustion: threshold 50% failures in 10 calls, open duration 60s. ' +
-                'When pool is at 80% capacity, emit a warning metric. ' +
-                'When circuit is open, return 503 immediately without touching the pool.',
+            currentHandling: 'Slow external services can exhaust local capacity and block unrelated work.',
+            requiredHandling: 'Define measurable connect/read bounds, local capacity, failure-isolation behavior, and alert thresholds from the dependency contract.',
             dataConsistency: 'Pool exhaustion can cascade: if this service pool is exhausted, callers of this service also accumulate requests.',
-            userExperience: 'Without fast-fail (circuit open), users wait for OS timeout (30s) instead of receiving a 503 in under 1s.',
+            userExperience: 'Use the dependency-failure response and latency bound declared by the client contract.',
         },
         {
-            scenario: `[${spec.id}] Resilience — Retry Thundering Herd: ` +
-                'If the external service recovers after a 60-second outage and the circuit breaker transitions to HALF-OPEN, ' +
-                'all queued retries fire simultaneously. ' +
-                'Does the retry strategy use jitter (random delay offset) to spread the load, ' +
-                'or do all retries hit the recovering service at the same time (thundering herd)?',
+            scenario: `[${spec.id}] Resilience — Coordinated Retries Overload a Recovering Dependency: ` +
+                'If automatic retries are declared, what prevents queued work from retrying simultaneously when the dependency recovers?',
             probability: 'medium',
             impact: 'high',
             currentHandling: 'Retry without jitter causes thundering herd: all retries fire simultaneously after backoff, ' +
                 'potentially re-overloading the service as it recovers.',
-            requiredHandling: 'Exponential backoff with jitter: delay = random(0, base * 2^attempt). ' +
-                'In HALF-OPEN state: limit to 1-3 probe requests, not all queued requests simultaneously. ' +
-                'If probes succeed, circuit closes gradually.',
+            requiredHandling: 'Define bounded retry, jitter, and recovery-probe behavior from the dependency contract, or confirm that automatic retries are not used.',
             dataConsistency: 'Thundering herd can cause the recovering service to fail again immediately after recovery.',
-            userExperience: 'Jitter is invisible to the user but prevents the oscillation pattern where the service flaps between healthy and degraded.',
+            userExperience: 'Use the recovery feedback and maximum wait declared by the client contract.',
         },
     ];
 }

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

@@ -7,17 +7,15 @@ export function generateRateLimitBypassScenarios(spec) {
     return [
         {
             scenario: `[${spec.id}] Rate Limit Bypass — Distributed Attack: ` +
-                'The rate limit is configured per-IP. An attacker uses 1000 different IPs (botnet or distributed scraper) ' +
+                'The rate limit is configured per-IP. An attacker uses many independent sources ' +
                 'to bypass the per-IP limit. What is the effective global rate of requests the system receives? ' +
                 'Does the system have any IP-independent rate limiting (per-account, global circuit breaker) to handle this?',
             probability: 'medium',
             impact: 'high',
-            currentHandling: 'Per-IP rate limiting is ineffective against distributed attacks — an attacker with 1000 IPs gets 1000x the per-IP limit.',
-            requiredHandling: 'Layer rate limits: per-IP (coarse), per-account/API-key (fine-grained), and global per-endpoint. ' +
-                'For authentication endpoints: per-account lockout after N failed attempts (regardless of source IP). ' +
-                'Use Redis-backed distributed rate limiting for consistency across multiple instances.',
+            currentHandling: 'Per-IP rate limiting alone may be ineffective against distributed attacks.',
+            requiredHandling: 'Define enforcement dimensions, shared-state boundaries, and rejection behavior from the rate-limit contract.',
             dataConsistency: 'In-memory rate limiting (local to one instance) allows the effective limit to be multiplied by the number of instances.',
-            userExperience: 'Rate limit responses must include Retry-After header so legitimate clients can back off gracefully.',
+            userExperience: 'Use the retry guidance declared by the client contract.',
         },
     ];
 }
@@ -39,12 +37,12 @@ export function generateConcurrencyScenarios(spec, concurrencyModel) {
                 'Use sync/atomic for simple counters. ' +
                 'Always run `go test -race ./...` in CI to detect race conditions before production.',
             dataConsistency: 'Race conditions on shared state lead to inconsistent reads and corrupted writes that are hard to reproduce.',
-            userExperience: 'A runtime panic from a race condition kills the entire goroutine group, causing an unexpected 500.',
+            userExperience: 'Use the failure response declared by the service contract.',
         },
         'async-await': {
             scenario: `[${spec.id}] Concurrency — Event Loop Blocking: ` +
                 'Does this feature perform any synchronous CPU-intensive or I/O-blocking operation inside an async function? ' +
-                'Examples: JSON.parse on large payloads (> 1MB), crypto operations (bcrypt without async), ' +
+                'Examples include parsing payloads above the declared size envelope or synchronous cryptography. ' +
                 'RegExp with catastrophic backtracking. ' +
                 'These block the single-threaded event loop and degrade ALL concurrent requests, not just this one.',
             probability: 'medium',
@@ -66,10 +64,10 @@ export function generateConcurrencyScenarios(spec, concurrencyModel) {
             impact: 'critical',
             currentHandling: 'Inconsistent lock ordering causes deadlocks that hang threads indefinitely, eventually exhausting the thread pool.',
             requiredHandling: 'Establish a canonical lock ordering (always A before B, never B before A). Document this ordering. ' +
-                'Use tryLock(timeout) in tests to detect deadlocks: if the lock is not acquired in N seconds, the test fails. ' +
+                'Use bounded lock acquisition in tests with the timeout declared by the concurrency contract. ' +
                 'Consider using ReentrantLock over synchronized blocks for more control.',
             dataConsistency: 'Deadlocked threads hold locks, preventing other threads from accessing the protected resources.',
-            userExperience: 'A deadlock causes the request to hang until the timeout is reached, resulting in a 503 or 504 for the user.',
+            userExperience: 'Use the timeout response declared by the service contract.',
         },
         'rust-ownership': {
             scenario: `[${spec.id}] Concurrency — Rust Logical Deadlock: ` +
@@ -95,9 +93,7 @@ export function generateConcurrencyScenarios(spec, concurrencyModel) {
             probability: 'medium',
             impact: 'high',
             currentHandling: 'Unbounded mailboxes cause memory exhaustion under load. Message drops without metrics cause silent data loss.',
-            requiredHandling: 'Configure a bounded mailbox with a drop strategy (drop-oldest or drop-newest). ' +
-                'Emit a metric when mailbox exceeds 80% capacity. ' +
-                'Consider back-pressure: if the producer is too fast, slow it down at the source instead of dropping at the destination.',
+            requiredHandling: 'Define mailbox bounds, overflow behavior, and observability from the actor contract.',
             dataConsistency: 'Dropped messages cause data loss that is not recoverable without event sourcing or DLQ.',
             userExperience: 'Mailbox overflow is invisible to users until they notice missing data or failed operations.',
         },
@@ -113,9 +109,9 @@ export function generateConcurrencyScenarios(spec, concurrencyModel) {
             requiredHandling: 'Choose the backpressure strategy explicitly based on business requirements. ' +
                 'For critical events: use ERROR or bounded BUFFER to prevent loss. ' +
                 'For metrics/logging: DROP or LATEST is acceptable. ' +
-                'Test with a producer that emits 10x faster than the subscriber to verify the strategy holds.',
+                'Test above the producer/subscriber rate envelope declared by the stream contract.',
             dataConsistency: 'Backpressure strategy determines whether data loss is acceptable or whether the stream must be slowed down.',
-            userExperience: 'Backpressure overflow can cause request failures for the publisher, which surfaces as 503 or timeout.',
+            userExperience: 'Use the overflow response declared by the stream contract.',
         },
     };
     const scenario = modelScenarios[concurrencyModel];
@@ -127,9 +123,9 @@ export function generateConcurrencyScenarios(spec, concurrencyModel) {
 export function generateSagaFailureScenarios(spec) {
     return [
         {
-            scenario: `[${spec.id}] Distributed Saga — Partial Failure at Step N: ` +
-                'If step 3 of 5 in the saga fails after steps 1 and 2 already executed in external services, ' +
-                'how long do the compensation events (rollback for steps 1 and 2) take to complete? ' +
+            scenario: `[${spec.id}] Distributed Saga — Partial Failure at a Later Step: ` +
+                'If a later saga step fails after earlier external actions completed, ' +
+                'how long may compensation take according to the saga contract? ' +
                 'How is it verified that the system is in a consistent state after compensation, ' +
                 'rather than in a partially-reverted state (step 1 rolled back but step 2 not yet)?',
             probability: 'medium',
@@ -138,8 +134,7 @@ export function generateSagaFailureScenarios(spec) {
                 '(some external services have committed while others have not).',
             requiredHandling: 'Each saga step must have a defined compensation operation. ' +
                 'Compensation must be idempotent (can be retried safely). ' +
-                'Track saga state in a durable store: if the orchestrator crashes mid-saga, it must resume from the last known state. ' +
-                'Add a saga status endpoint: GET /sagas/{id} returns the current step, status, and any failed compensations.',
+                'Persist enough saga state to resume from the last known step and expose status only through the interface declared by the contract.',
             dataConsistency: 'Partial compensation leaves distributed state inconsistent. The saga log must be the source of truth for rollback status.',
             userExperience: 'Users must receive a clear error explaining that the operation was rolled back and what state the system is in. ' +
                 'If rollback also failed, the user must be told that manual resolution is required.',

package/dist/tools/challenge-spec/scenario-collector.d.ts

@@ -0,0 +1,13 @@
+import type { ChallengeSpecFocus, FailureScenario, ProjectKnowledge, Spec } from '../../types/index.js';
+import { type ChallengeCapabilities } from './scenarios-utils.js';
+interface ScenarioCollectionInput {
+    spec: Spec;
+    specContent: string;
+    knowledge: ProjectKnowledge;
+    focusAreas: ChallengeSpecFocus[];
+    capabilities: ChallengeCapabilities;
+}
+/** Select scenario families before generation so unsupported templates never reach risk scoring. */
+export declare function collectCapabilityScenarios(input: ScenarioCollectionInput): FailureScenario[];
+export {};
+//# sourceMappingURL=scenario-collector.d.ts.map

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

@@ -0,0 +1,86 @@
+import { generateDataConsistencyScenarios, generateDesktopAutoUpdateChallenges, generateFailureScenarios, generateGameChallenges, generateScaleScenarios, generateSecurityScenarios, } from '../challenge-spec-scenarios.js';
+import { generateAgentChallengeScenarios, isAgentSpec } from './agent-challenge-scenarios.js';
+import { generateDddChallenges, generateXpPairClarityChallenge, } from './architecture-challenge-scenarios.js';
+import { generateEventChallengeScenarios } from './event-challenge-scenarios.js';
+import { generateImplementationContractChallengeScenarios } from './implementation-contract-challenge-scenarios.js';
+import { getPlatformChallenges } from './platform-challenge-scenarios.js';
+import { generatePrivacyChallengeScenarios } from './privacy-challenge-scenarios.js';
+import { generateResilienceChallengeScenarios } from './resilience-challenge-scenarios.js';
+import { generateSecurityChallengeScenarios } from './security-challenge-scenarios.js';
+import { hasAnyChallengeCapability } from './scenarios-utils.js';
+/** Select scenario families before generation so unsupported templates never reach risk scoring. */
+export function collectCapabilityScenarios(input) {
+    const { spec, specContent, knowledge, focusAreas, capabilities } = input;
+    const scenarios = [];
+    const hasFocus = (focus) => focusAreas.includes(focus);
+    const hasCapability = (names) => hasAnyChallengeCapability(capabilities, names);
+    if (hasFocus('failures') &&
+        hasCapability([
+            'networkApi',
+            'database',
+            'userInput',
+            'externalService',
+            'payment',
+            'fileTransfer',
+        ])) {
+        scenarios.push(...generateFailureScenarios(spec, specContent, knowledge));
+    }
+    if (hasFocus('security') &&
+        hasCapability(['authentication', 'authorization', 'userInput', 'database', 'payment'])) {
+        scenarios.push(...generateSecurityScenarios(spec, specContent, knowledge));
+    }
+    if (hasFocus('scale') && capabilities.scale) {
+        scenarios.push(...generateScaleScenarios(spec, specContent, knowledge));
+    }
+    if (hasFocus('data-consistency') && hasCapability(['dataWrite', 'cache', 'duplicateOperation'])) {
+        scenarios.push(...generateDataConsistencyScenarios(spec, specContent, knowledge));
+    }
+    const isGameProject = knowledge.projectCategory === 'game' ||
+        (knowledge.framework !== null &&
+            ['unity', 'godot', 'unreal', 'bevy', 'phaser', 'pygame'].includes(knowledge.framework));
+    if (isGameProject) {
+        scenarios.push(...generateGameChallenges(spec, specContent, knowledge));
+    }
+    if (capabilities.desktopUpdate) {
+        scenarios.push(...generateDesktopAutoUpdateChallenges(spec, specContent, knowledge));
+    }
+    if (capabilities.agent && isAgentSpec(spec, specContent)) {
+        scenarios.push(...generateAgentChallengeScenarios(spec, specContent, knowledge));
+    }
+    if (hasFocus('failures') && capabilities.implementationContract) {
+        scenarios.push(...generateImplementationContractChallengeScenarios(spec, specContent));
+    }
+    if (capabilities.platform) {
+        scenarios.push(...getPlatformChallenges(spec, specContent, knowledge));
+    }
+    if (hasFocus('security') &&
+        hasCapability(['authentication', 'authorization', 'database', 'payment'])) {
+        scenarios.push(...generateSecurityChallengeScenarios(spec, specContent, knowledge));
+    }
+    if (capabilities.privacy) {
+        scenarios.push(...generatePrivacyChallengeScenarios(spec, specContent, knowledge));
+    }
+    if (capabilities.events) {
+        scenarios.push(...generateEventChallengeScenarios(spec, specContent, knowledge));
+    }
+    const hasDdd = knowledge.architecture.primary === 'ddd' || knowledge.architecture.secondary.includes('ddd');
+    if (hasDdd && capabilities.ddd) {
+        scenarios.push(...generateDddChallenges(spec, specContent));
+    }
+    if (hasCapability([
+        'externalService',
+        'networkApi',
+        'validation',
+        'rateLimit',
+        'concurrency',
+        'saga',
+    ])) {
+        scenarios.push(...generateResilienceChallengeScenarios(spec, specContent, knowledge));
+    }
+    const agileConfig = knowledge.agileConfig;
+    if (agileConfig?.process === 'xp' && capabilities.xp) {
+        scenarios.push(...generateXpPairClarityChallenge(spec, specContent));
+    }
+    return scenarios;
+}
+//# sourceMappingURL=scenario-collector.js.map

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

@@ -7,6 +7,7 @@ const WRITE_SIGNALS = [
 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,
+    /\bduplicate\s+(?:request|submission|operation|record)\b/i,
 ];
 export function generateDataConsistencyScenarios(_spec, content, _knowledge) {
     const scenarios = [];
@@ -20,9 +21,9 @@ export function generateDataConsistencyScenarios(_spec, content, _knowledge) {
             currentHandling: contentMentions(lower, ['transaction', 'atomic', 'rollback'])
                 ? 'Transactions mentioned'
                 : 'Not addressed',
-            requiredHandling: 'Wrap multi-step writes in database transactions. Implement saga pattern for distributed operations.',
-            dataConsistency: 'ACID properties must be maintained. No orphaned records.',
-            userExperience: 'Transparent: user sees either success or clean failure with clear error message.',
+            requiredHandling: 'Define atomicity, rollback, and partial-failure behavior for the declared write boundary.',
+            dataConsistency: 'The write contract must state which states are valid after interruption.',
+            userExperience: 'Use the success and failure behavior declared by the interaction contract.',
         });
     }
     // Stale data
@@ -34,9 +35,9 @@ export function generateDataConsistencyScenarios(_spec, content, _knowledge) {
             currentHandling: contentMentions(lower, ['invalidat', 'ttl', 'websocket', 'real-time'])
                 ? 'Some cache strategy mentioned'
                 : 'Not addressed',
-            requiredHandling: 'Implement cache invalidation on writes. Use TTL for time-sensitive data. Consider event-driven invalidation.',
-            dataConsistency: 'Define acceptable staleness window per data type. Document cache strategy.',
-            userExperience: 'Show "last updated" timestamp. Offer manual refresh option.',
+            requiredHandling: 'Define invalidation and freshness behavior from the declared cache contract.',
+            dataConsistency: 'Define and verify the acceptable staleness boundary.',
+            userExperience: 'Use the freshness feedback declared by the interaction contract.',
         });
     }
     // Duplicate operations only apply to explicit user-triggered mutations.
@@ -48,9 +49,9 @@ export function generateDataConsistencyScenarios(_spec, content, _knowledge) {
             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.',
+            requiredHandling: 'Define duplicate-submission semantics and enforce them at the declared mutation boundary.',
+            dataConsistency: 'Repeated submissions must produce the result declared by the mutation contract.',
+            userExperience: 'Use the in-progress and completion feedback declared by the interaction contract.',
         });
     }
     return scenarios;

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

@@ -1,101 +1,85 @@
 // tools/challenge-spec/scenarios-failure.ts — Network, database, and resource failure scenarios
-import { contentMentions } from './scenarios-utils.js';
+import { contentMentions, detectChallengeCapabilities } from './scenarios-utils.js';
 export function generateFailureScenarios(spec, content, _knowledge) {
     const scenarios = [];
-    const lower = content.toLowerCase();
+    const capabilities = detectChallengeCapabilities(spec, content);
     // Network failures
-    if (spec.target === 'fullstack' ||
-        spec.target === 'frontend' ||
-        lower.includes('api') ||
-        lower.includes('fetch') ||
-        lower.includes('request')) {
+    if (capabilities.networkApi) {
         scenarios.push({
             scenario: 'API endpoint becomes unreachable (network timeout)',
             probability: 'medium',
             impact: 'high',
-            currentHandling: contentMentions(lower, ['timeout', 'retry', 'fallback'])
+            currentHandling: contentMentions(content, ['timeout', 'retry', 'fallback'])
                 ? 'Partially addressed in spec'
                 : 'Not addressed in spec',
-            requiredHandling: 'Implement request timeout (e.g. 10s), exponential backoff retry (3 attempts), and graceful fallback UI',
+            requiredHandling: 'Define the request timeout, retry policy, and degraded behavior from the endpoint contract.',
             dataConsistency: 'Ensure idempotent operations to prevent duplicate actions on retry',
-            userExperience: 'Show offline indicator, queue actions for retry, display stale data if available',
+            userExperience: 'Use the failure behavior defined by the client contract.',
         });
     }
     // Database failures
-    if (spec.target === 'backend' ||
-        spec.target === 'fullstack' ||
-        spec.target === 'database' ||
-        lower.includes('database') ||
-        lower.includes('query') ||
-        lower.includes('schema')) {
+    if (capabilities.database) {
         scenarios.push({
             scenario: 'Database connection pool exhausted',
             probability: 'low',
             impact: 'critical',
             currentHandling: 'Not addressed in spec',
-            requiredHandling: 'Configure connection pool limits, implement circuit breaker, add health check endpoint',
-            dataConsistency: 'In-flight transactions will fail; ensure rollback handling',
-            userExperience: 'Return 503 Service Unavailable with retry-after header',
+            requiredHandling: 'Define connection-pool bounds, exhaustion behavior, and recovery from the database contract.',
+            dataConsistency: 'Define how in-flight transactions remain consistent when capacity is exhausted.',
+            userExperience: 'Return the database-unavailable response defined by the service contract.',
         });
         scenarios.push({
             scenario: 'Migration fails halfway through',
             probability: 'medium',
             impact: 'high',
-            currentHandling: contentMentions(lower, ['migration', 'rollback', 'reversible'])
+            currentHandling: contentMentions(content, ['migration', 'rollback', 'reversible'])
                 ? 'Partially addressed'
                 : 'Not addressed',
-            requiredHandling: 'Use transactional migrations. Every migration must have a reverse. Test migrations on staging first.',
-            dataConsistency: 'Partial schema changes can leave database in inconsistent state',
-            userExperience: 'Deploy downtime or maintenance mode during migration',
+            requiredHandling: 'Define migration atomicity, recovery, rollback expectations, and verification evidence.',
+            dataConsistency: 'Partial schema changes must have an explicit recovery contract.',
+            userExperience: 'Use the availability behavior declared by the deployment contract.',
         });
     }
     // Input validation failures
-    scenarios.push({
-        scenario: 'Malformed or oversized input data',
-        probability: 'high',
-        impact: 'medium',
-        currentHandling: contentMentions(lower, ['validat', 'sanitiz', 'schema', 'zod'])
-            ? 'Validation mentioned in spec'
-            : 'Not explicitly addressed',
-        requiredHandling: 'Validate all inputs at API boundary. Use schema validation (Zod, Joi, etc.). Set payload size limits.',
-        dataConsistency: 'Invalid data must never reach the database',
-        userExperience: 'Clear validation error messages with field-level detail',
-    });
+    if (capabilities.userInput) {
+        scenarios.push({
+            scenario: 'Malformed or oversized input data',
+            probability: 'high',
+            impact: 'medium',
+            currentHandling: contentMentions(content, ['validat', 'sanitiz', 'schema', 'zod'])
+                ? 'Validation mentioned in spec'
+                : 'Not explicitly addressed',
+            requiredHandling: 'Validate input at the declared boundary and define payload limits.',
+            dataConsistency: 'Invalid input must not reach the declared persistence boundary.',
+            userExperience: 'Return the validation feedback defined by the interaction contract.',
+        });
+    }
     // Third-party service failures
-    if (lower.includes('stripe') ||
-        lower.includes('payment') ||
-        lower.includes('email') ||
-        lower.includes('auth') ||
-        lower.includes('external') ||
-        lower.includes('webhook')) {
+    if (capabilities.externalService || capabilities.payment) {
         scenarios.push({
-            scenario: 'Third-party service (payment/auth/email) goes down',
+            scenario: 'Third-party service declared by the spec becomes unavailable',
             probability: 'medium',
             impact: 'critical',
-            currentHandling: contentMentions(lower, ['fallback', 'queue', 'retry', 'circuit'])
+            currentHandling: contentMentions(content, ['fallback', 'queue', 'retry', 'circuit'])
                 ? 'Partially addressed'
                 : 'Not addressed',
-            requiredHandling: 'Implement circuit breaker pattern. Queue operations for retry. Have degraded-mode behavior.',
-            dataConsistency: 'Use idempotency keys for payment operations. Log all attempts.',
-            userExperience: 'Inform user of degraded state. Offer alternative or queue the action.',
+            requiredHandling: 'Define observable failure and recovery behavior from the declared dependency contract.',
+            dataConsistency: 'Preserve idempotence for any operation the spec marks as retryable.',
+            userExperience: 'Use the degraded behavior defined by the dependency contract.',
         });
     }
     // Memory/resource exhaustion
-    if (lower.includes('upload') ||
-        lower.includes('file') ||
-        lower.includes('stream') ||
-        lower.includes('batch') ||
-        lower.includes('bulk')) {
+    if (capabilities.fileTransfer) {
         scenarios.push({
             scenario: 'Memory exhaustion from large file upload or batch operation',
             probability: 'medium',
             impact: 'high',
-            currentHandling: contentMentions(lower, ['limit', 'stream', 'chunk', 'pagination'])
+            currentHandling: contentMentions(content, ['limit', 'stream', 'chunk', 'pagination'])
                 ? 'Partially addressed'
                 : 'Not addressed',
-            requiredHandling: 'Use streaming for large files. Implement file size limits. Process batches in chunks.',
-            dataConsistency: 'Partial batch processing must be resumable. Track progress.',
-            userExperience: 'Show progress indicator for long operations. Allow cancellation.',
+            requiredHandling: 'Define resource bounds and processing behavior for over-limit files or batches.',
+            dataConsistency: 'Define the consistency guarantee for interrupted file or batch processing.',
+            userExperience: 'Use the progress and cancellation behavior declared by the interaction contract.',
         });
     }
     return scenarios;