@agile-vibe-coding/avc 0.2.3 → 0.3.2

package/cli/template-processor.js

@@ -599,7 +599,16 @@ Please carefully follow the output format requirements to avoid these issues.
    * @returns {Promise<LLMProvider>} LLM provider instance
    */
   async getProviderForStageInstance(stageName) {
-    const { provider, model } = this.getProviderForStage(stageName);
+    let { provider, model } = this.getProviderForStage(stageName);
+
+    // Resolve to an available provider if current one has no credentials
+    const resolved = await LLMProvider.resolveAvailableProvider(provider, model);
+    if (resolved.fellBack) {
+      debug(`Provider fallback for ${stageName}: ${provider}→${resolved.provider} (${resolved.model})`);
+      console.warn(`[WARN] ${provider} has no API key — falling back to ${resolved.provider} for stage "${stageName}"`);
+      provider = resolved.provider;
+      model = resolved.model;
+    }
 
     // Check if we already have a provider for this stage
     const cacheKey = `${stageName}:${provider}:${model}`;
@@ -627,7 +636,16 @@ Please carefully follow the output format requirements to avoid these issues.
    * @returns {Promise<LLMProvider>} LLM provider instance
    */
   async getValidationProviderForTypeInstance(validationType) {
-    const { provider, model } = this.getValidationProviderForType(validationType);
+    let { provider, model } = this.getValidationProviderForType(validationType);
+
+    // Resolve to an available provider if current one has no credentials
+    const resolved = await LLMProvider.resolveAvailableProvider(provider, model);
+    if (resolved.fellBack) {
+      debug(`Validation provider fallback for ${validationType}: ${provider}→${resolved.provider} (${resolved.model})`);
+      console.warn(`[WARN] ${provider} has no API key — falling back to ${resolved.provider} for validation "${validationType}"`);
+      provider = resolved.provider;
+      model = resolved.model;
+    }
 
     // Check if we already have a provider for this validation type
     const cacheKey = `validation:${validationType}:${provider}:${model}`;
@@ -1531,7 +1549,7 @@ ${TECHNICAL_CONSIDERATIONS}
 **Security and Compliance Requirements:**
 ${SECURITY_AND_COMPLIANCE_REQUIREMENTS}
 
-Decompose this project into Epics (3-7 domain-based groupings) and Stories (2-8 user-facing capabilities per Epic).
+Decompose this project into Epics (domain-based groupings) and Stories (user-facing capabilities per Epic) — create as many as needed to fully cover the scope.
 
 Return your response as JSON following the exact structure specified in your instructions.`;
   }
@@ -2564,6 +2582,35 @@ Return your response as JSON following the exact structure specified in your ins
         'question prefilling'
       );
 
+      // Normalize common field name variants that local LLMs sometimes produce.
+      // Maps known abbreviations/alternatives → canonical field names.
+      const FIELD_ALIASES = {
+        DEPLOY_TARGET: 'DEPLOYMENT_TARGET',
+        DEPLOY: 'DEPLOYMENT_TARGET',
+        DEPLOYMENT: 'DEPLOYMENT_TARGET',
+        TARGET_DEPLOYMENT: 'DEPLOYMENT_TARGET',
+        SECURITY_REQUIREMENTS: 'SECURITY_AND_COMPLIANCE_REQUIREMENTS',
+        SECURITY_COMPLIANCE: 'SECURITY_AND_COMPLIANCE_REQUIREMENTS',
+        COMPLIANCE_REQUIREMENTS: 'SECURITY_AND_COMPLIANCE_REQUIREMENTS',
+        SECURITY: 'SECURITY_AND_COMPLIANCE_REQUIREMENTS',
+        TECHNICAL: 'TECHNICAL_CONSIDERATIONS',
+        TECH_CONSIDERATIONS: 'TECHNICAL_CONSIDERATIONS',
+        TECH_STACK: 'TECHNICAL_CONSIDERATIONS',
+        USERS: 'TARGET_USERS',
+        TARGET_USER: 'TARGET_USERS',
+      };
+
+      for (const [alias, canonical] of Object.entries(FIELD_ALIASES)) {
+        if (result[alias] !== undefined) {
+          if (!result[canonical] && result[alias]) {
+            // Canonical missing or empty — use alias value
+            debug(`Normalizing field name: ${alias} → ${canonical}`);
+            result[canonical] = result[alias];
+          }
+          delete result[alias];
+        }
+      }
+
       debug('Question prefilling received', {
         hasTargetUsers: !!result.TARGET_USERS,
         hasDeploymentTarget: !!result.DEPLOYMENT_TARGET,

package/cli/token-tracker.js

@@ -92,31 +92,38 @@ export class TokenTracker {
 
   /**
    * Calculate cost for token usage based on model pricing
-   * @param {number} inputTokens - Input tokens consumed
+   * @param {number} inputTokens - Input tokens consumed (includes cached tokens)
    * @param {number} outputTokens - Output tokens consumed
    * @param {string} modelId - Model identifier (e.g., 'claude-sonnet-4-5-20250929')
-   * @returns {Object} Cost breakdown { input: number, output: number, total: number }
+   * @param {number} cachedTokens - Subset of inputTokens served from cache (billed at inputCached rate)
+   * @returns {Object} Cost breakdown { input, output, total, saved }
    */
-  calculateCost(inputTokens, outputTokens, modelId) {
+  calculateCost(inputTokens, outputTokens, modelId, cachedTokens = 0) {
     const config = this.readConfig();
     const modelConfig = config.settings?.models?.[modelId];
 
     if (!modelConfig || !modelConfig.pricing) {
       // Model not found or no pricing - return zero cost
-      return { input: 0, output: 0, total: 0 };
+      return { input: 0, output: 0, total: 0, saved: 0 };
     }
 
     const pricing = modelConfig.pricing;
     const divisor = pricing.unit === 'million' ? 1_000_000 : 1_000;
 
-    // Calculate costs (price per unit * tokens / divisor)
-    const inputCost = (pricing.input * inputTokens) / divisor;
+    // Cached tokens billed at reduced rate; fall back to full input rate if not configured
+    const cachedRate = pricing.inputCached ?? pricing.input;
+    const nonCachedInput = Math.max(0, inputTokens - cachedTokens);
+
+    const inputCost = (pricing.input * nonCachedInput + cachedRate * cachedTokens) / divisor;
     const outputCost = (pricing.output * outputTokens) / divisor;
+    // Savings vs. paying full rate for cached tokens
+    const saved = ((pricing.input - cachedRate) * cachedTokens) / divisor;
 
     return {
       input: inputCost,
       output: outputCost,
-      total: inputCost + outputCost
+      total: inputCost + outputCost,
+      saved,
     };
   }
 
@@ -139,20 +146,25 @@ export class TokenTracker {
       const tokenData = {
         input: tokens.input || 0,
         output: tokens.output || 0,
+        cached: tokens.cached || 0,
+        cacheWrite: tokens.cacheWrite || 0,
         total: (tokens.input || 0) + (tokens.output || 0),
         provider: tokens.provider || 'unknown',
         model: tokens.model || modelId || 'unknown'
       };
 
       // Calculate cost: prefer per-model pricing from avc.json, fall back to provider estimate
+      // Skip cost calculation for OAuth calls (flat-rate subscription — no per-token billing)
       let costData = null;
-      const effectiveModelId = tokens.model || modelId;
-      if (effectiveModelId) {
-        costData = this.calculateCost(tokenData.input, tokenData.output, effectiveModelId);
-      }
-      // If no per-model pricing configured but provider sent a pre-computed estimate, use it
-      if ((!costData || costData.total === 0) && tokens.estimatedCost) {
-        costData = { input: 0, output: 0, total: tokens.estimatedCost };
+      if (!tokens.skipCost) {
+        const effectiveModelId = tokens.model || modelId;
+        if (effectiveModelId) {
+          costData = this.calculateCost(tokenData.input, tokenData.output, effectiveModelId, tokenData.cached);
+        }
+        // If no per-model pricing configured but provider sent a pre-computed estimate, use it
+        if ((!costData || costData.total === 0) && tokens.estimatedCost) {
+          costData = { input: 0, output: 0, total: tokens.estimatedCost };
+        }
       }
 
       console.log(`   → Tracking tokens for ${ceremonyType}: ${tokenData.input} input, ${tokenData.output} output (${tokenData.provider})`);
@@ -211,17 +223,21 @@ export class TokenTracker {
       const tokenData = {
         input: delta.input || 0,
         output: delta.output || 0,
+        cached: delta.cached || 0,
+        cacheWrite: delta.cacheWrite || 0,
         total: (delta.input || 0) + (delta.output || 0),
         provider: delta.provider || 'unknown',
         model: delta.model || 'unknown'
       };
 
       let costData = null;
-      if (delta.model) {
-        costData = this.calculateCost(tokenData.input, tokenData.output, delta.model);
-      }
-      if ((!costData || costData.total === 0) && delta.estimatedCost) {
-        costData = { input: 0, output: 0, total: delta.estimatedCost };
+      if (!delta.skipCost) {
+        if (delta.model) {
+          costData = this.calculateCost(tokenData.input, tokenData.output, delta.model, tokenData.cached);
+        }
+        if ((!costData || costData.total === 0) && delta.estimatedCost) {
+          costData = { input: 0, output: 0, total: delta.estimatedCost };
+        }
       }
 
       if (!this.data[ceremonyType]) {
@@ -285,19 +301,22 @@ export class TokenTracker {
         date: dateKey,
         input: 0,
         output: 0,
+        cached: 0,
         total: 0,
         executions: 0,
-        cost: { input: 0, output: 0, total: 0 }
+        cost: { input: 0, output: 0, total: 0, saved: 0 }
       };
     }
     scope.daily[dateKey].input += tokenData.input;
     scope.daily[dateKey].output += tokenData.output;
+    scope.daily[dateKey].cached = (scope.daily[dateKey].cached || 0) + (tokenData.cached || 0);
     scope.daily[dateKey].total += tokenData.total;
     if (incExec) scope.daily[dateKey].executions++;
     if (costData) {
       scope.daily[dateKey].cost.input += costData.input;
       scope.daily[dateKey].cost.output += costData.output;
       scope.daily[dateKey].cost.total += costData.total;
+      scope.daily[dateKey].cost.saved = (scope.daily[dateKey].cost.saved || 0) + (costData.saved || 0);
     }
 
     // Update weekly
@@ -306,19 +325,22 @@ export class TokenTracker {
         week: weekKey,
         input: 0,
         output: 0,
+        cached: 0,
         total: 0,
         executions: 0,
-        cost: { input: 0, output: 0, total: 0 }
+        cost: { input: 0, output: 0, total: 0, saved: 0 }
       };
     }
     scope.weekly[weekKey].input += tokenData.input;
     scope.weekly[weekKey].output += tokenData.output;
+    scope.weekly[weekKey].cached = (scope.weekly[weekKey].cached || 0) + (tokenData.cached || 0);
     scope.weekly[weekKey].total += tokenData.total;
     if (incExec) scope.weekly[weekKey].executions++;
     if (costData) {
       scope.weekly[weekKey].cost.input += costData.input;
       scope.weekly[weekKey].cost.output += costData.output;
       scope.weekly[weekKey].cost.total += costData.total;
+      scope.weekly[weekKey].cost.saved = (scope.weekly[weekKey].cost.saved || 0) + (costData.saved || 0);
     }
 
     // Update monthly
@@ -327,35 +349,40 @@ export class TokenTracker {
         month: monthKey,
         input: 0,
         output: 0,
+        cached: 0,
         total: 0,
         executions: 0,
-        cost: { input: 0, output: 0, total: 0 }
+        cost: { input: 0, output: 0, total: 0, saved: 0 }
       };
     }
     scope.monthly[monthKey].input += tokenData.input;
     scope.monthly[monthKey].output += tokenData.output;
+    scope.monthly[monthKey].cached = (scope.monthly[monthKey].cached || 0) + (tokenData.cached || 0);
     scope.monthly[monthKey].total += tokenData.total;
     if (incExec) scope.monthly[monthKey].executions++;
     if (costData) {
       scope.monthly[monthKey].cost.input += costData.input;
       scope.monthly[monthKey].cost.output += costData.output;
       scope.monthly[monthKey].cost.total += costData.total;
+      scope.monthly[monthKey].cost.saved = (scope.monthly[monthKey].cost.saved || 0) + (costData.saved || 0);
     }
 
     // Update all-time
     scope.allTime.input += tokenData.input;
     scope.allTime.output += tokenData.output;
+    scope.allTime.cached = (scope.allTime.cached || 0) + (tokenData.cached || 0);
     scope.allTime.total += tokenData.total;
     if (incExec) scope.allTime.executions++;
 
     // Initialize cost tracking if not present
     if (!scope.allTime.cost) {
-      scope.allTime.cost = { input: 0, output: 0, total: 0 };
+      scope.allTime.cost = { input: 0, output: 0, total: 0, saved: 0 };
     }
     if (costData) {
       scope.allTime.cost.input += costData.input;
       scope.allTime.cost.output += costData.output;
       scope.allTime.cost.total += costData.total;
+      scope.allTime.cost.saved = (scope.allTime.cost.saved || 0) + (costData.saved || 0);
     }
 
     if (!scope.allTime.firstExecution) {

package/cli/tools/generate-story-validators.js

@@ -70,7 +70,7 @@ You are an expert ${domainTitle.toLowerCase()} reviewing user story implementati
 - [ ] Expected outcomes are precisely defined
 
 ### Scope & Dependencies (10 points)
-- [ ] Story is appropriately sized (completable in 1-3 days)
+- [ ] Story is appropriately scoped (single cohesive capability, 3-8 ACs)
 - [ ] Dependencies on other stories are explicit
 - [ ] Story is independent enough to be delivered incrementally
 

package/cli/validation-router.js

@@ -199,8 +199,8 @@ class ValidationRouter {
       featureValidators.forEach(v => validators.add(v));
     });
 
-    // Return unique validators (2-6 agents typically)
-    return Array.from(validators);
+    // Return unique validators (2-6 agents typically), filtered by project context
+    return this.filterByProjectContext(Array.from(validators), 'epic');
   }
 
   /**
@@ -233,8 +233,8 @@ class ValidationRouter {
       featureValidators.forEach(v => validators.add(v));
     });
 
-    // Return unique validators (3-8 agents typically)
-    return Array.from(validators);
+    // Return unique validators (3-8 agents typically), filtered by project context
+    return this.filterByProjectContext(Array.from(validators), 'story');
   }
 
   /**
@@ -391,6 +391,68 @@ class ValidationRouter {
     return validRoles.includes(role);
   }
 
+  /**
+   * Filter perspectives against project context using deterministic rules.
+   * Removes perspectives that are provably irrelevant based on project flags,
+   * regardless of what the LLM selector chose. Applied as a final pass after
+   * any selection method (static routing, LLM, or contextual selection).
+   *
+   * @param {string[]} validators - Full validator agent names
+   * @param {string}   type       - 'epic' or 'story'
+   * @returns {string[]} Filtered validators
+   */
+  filterByProjectContext(validators, type) {
+    const ctx = this.projectContext;
+    if (!ctx || Object.keys(ctx).length === 0) {
+      console.log(`   [context-filter] Skipped: projectContext is ${ctx ? 'empty' : 'null/undefined'}`);
+      return validators;
+    }
+
+    const excluded = new Set();
+
+    // Cloud: only if project explicitly uses cloud services
+    if (ctx.hasCloud === false) {
+      excluded.add('cloud');
+    }
+
+    // DevOps: only if project has CI/CD or uses Kubernetes/cloud orchestration
+    if (ctx.hasCI_CD === false && ctx.hasCloud === false) {
+      excluded.add('devops');
+    }
+
+    // Mobile: only if project has a mobile app
+    if (ctx.hasMobileApp === false) {
+      excluded.add('mobile');
+    }
+
+    // Frontend/UI/UX: only if project has a frontend
+    if (ctx.hasFrontend === false) {
+      excluded.add('frontend');
+      excluded.add('ui');
+      excluded.add('ux');
+    }
+
+    if (excluded.size === 0) {
+      console.log(`   [context-filter] No exclusions matched (hasCloud=${ctx.hasCloud}, hasCI_CD=${ctx.hasCI_CD}, hasMobileApp=${ctx.hasMobileApp}, hasFrontend=${ctx.hasFrontend})`);
+      return validators;
+    }
+
+    const prefix = `validator-${type}-`;
+    const filtered = validators.filter(v => {
+      const role = v.startsWith(prefix) ? v.slice(prefix.length) : v;
+      return !excluded.has(role);
+    });
+
+    // Log exclusions
+    const removedCount = validators.length - filtered.length;
+    if (removedCount > 0) {
+      const removedRoles = validators.filter(v => !filtered.includes(v));
+      console.log(`   [context-filter] Removed ${removedCount} irrelevant perspective(s): ${removedRoles.map(v => v.replace(prefix, '')).join(', ')}`);
+    }
+
+    return filtered;
+  }
+
   /**
    * Check if a domain is known (has predefined routing rules)
    * @private
@@ -432,7 +494,7 @@ class ValidationRouter {
       featureValidators.forEach(v => validators.add(v));
     });
 
-    return Array.from(validators);
+    return this.filterByProjectContext(Array.from(validators), 'epic');
   }
 
   /**
@@ -475,7 +537,7 @@ class ValidationRouter {
       featureValidators.forEach(v => validators.add(v));
     });
 
-    return Array.from(validators);
+    return this.filterByProjectContext(Array.from(validators), 'story');
   }
   /**
    * Select validators using project context + per-item LLM call (contextual selection).
@@ -535,8 +597,8 @@ class ValidationRouter {
         console.log(`   ✂ Excluding ${type} ${role}${reason}`);
       });
 
-      // Map short role names to full validator agent names
-      return safeSelected.map(r => `validator-${type}-${r}`);
+      // Map short role names to full validator agent names, then filter by project context
+      return this.filterByProjectContext(safeSelected.map(r => `validator-${type}-${r}`), type);
     } catch (err) {
       console.warn(`   ⚠ Contextual agent selection failed (${err.message}) — using static routing`);
       return type === 'epic'