sequant 1.15.2 → 1.15.3

package/dist/src/commands/stats.js

@@ -248,6 +248,13 @@ function calculateMetricsAnalytics(metrics) {
             chainModeSuccessRate: 0,
             singleIssueSuccessRate: 0,
             insights: [],
+            // Token breakdown
+            totalInputTokens: 0,
+            totalOutputTokens: 0,
+            totalCacheTokens: 0,
+            avgInputTokens: 0,
+            avgOutputTokens: 0,
+            avgCacheTokens: 0,
         };
     }
     const successCount = runs.filter((r) => r.outcome === "success").length;
@@ -273,6 +280,10 @@ function calculateMetricsAnalytics(metrics) {
         : 0;
     // Generate insights
     const insights = generateInsights(runs, successRate, avgFilesChanged, avgLinesAdded, chainModeSuccessRate, singleIssueSuccessRate);
+    // Token breakdown (AC-10)
+    const totalInputTokens = runs.reduce((sum, r) => sum + (r.metrics.inputTokens ?? 0), 0);
+    const totalOutputTokens = runs.reduce((sum, r) => sum + (r.metrics.outputTokens ?? 0), 0);
+    const totalCacheTokens = runs.reduce((sum, r) => sum + (r.metrics.cacheTokens ?? 0), 0);
     return {
         totalRuns: runs.length,
         successCount,
@@ -286,6 +297,13 @@ function calculateMetricsAnalytics(metrics) {
         chainModeSuccessRate,
         singleIssueSuccessRate,
         insights,
+        // Token breakdown
+        totalInputTokens,
+        totalOutputTokens,
+        totalCacheTokens,
+        avgInputTokens: runs.length > 0 ? totalInputTokens / runs.length : 0,
+        avgOutputTokens: runs.length > 0 ? totalOutputTokens / runs.length : 0,
+        avgCacheTokens: runs.length > 0 ? totalCacheTokens / runs.length : 0,
     };
 }
 /**
@@ -375,6 +393,27 @@ function displayMetricsAnalytics(analytics) {
     }
     avgData["Duration"] = formatDuration(analytics.avgDuration);
     console.log(ui.keyValueTable(avgData));
+    // Token breakdown (AC-10)
+    const hasTokenBreakdown = analytics.totalInputTokens > 0 ||
+        analytics.totalOutputTokens > 0 ||
+        analytics.totalCacheTokens > 0;
+    if (hasTokenBreakdown) {
+        console.log(ui.sectionHeader("Token Usage"));
+        const tokenData = {};
+        if (analytics.totalInputTokens > 0) {
+            tokenData["Input tokens"] = analytics.totalInputTokens.toLocaleString();
+            tokenData["Avg input/run"] = Math.round(analytics.avgInputTokens).toLocaleString();
+        }
+        if (analytics.totalOutputTokens > 0) {
+            tokenData["Output tokens"] = analytics.totalOutputTokens.toLocaleString();
+            tokenData["Avg output/run"] = Math.round(analytics.avgOutputTokens).toLocaleString();
+        }
+        if (analytics.totalCacheTokens > 0) {
+            tokenData["Cache tokens"] = analytics.totalCacheTokens.toLocaleString();
+            tokenData["Avg cache/run"] = Math.round(analytics.avgCacheTokens).toLocaleString();
+        }
+        console.log(ui.keyValueTable(tokenData));
+    }
     // Insights
     if (analytics.insights.length > 0) {
         console.log(ui.sectionHeader("Insights"));
@@ -409,6 +448,15 @@ export async function statsCommand(options) {
                 chainModeSuccessRate: analytics.chainModeSuccessRate,
                 singleIssueSuccessRate: analytics.singleIssueSuccessRate,
                 insights: analytics.insights,
+                // Token breakdown (AC-10)
+                tokenBreakdown: {
+                    totalInputTokens: analytics.totalInputTokens,
+                    totalOutputTokens: analytics.totalOutputTokens,
+                    totalCacheTokens: analytics.totalCacheTokens,
+                    avgInputTokens: analytics.avgInputTokens,
+                    avgOutputTokens: analytics.avgOutputTokens,
+                    avgCacheTokens: analytics.avgCacheTokens,
+                },
                 runs: metrics.runs,
             };
             console.log(JSON.stringify(output, null, 2));

package/dist/src/lib/scope/index.d.ts

@@ -22,6 +22,7 @@ export { DEFAULT_SCOPE_CONFIG, ScopeAssessmentSchema } from "./types.js";
 export { clusterACByKeyword, detectTitleVerbs, estimateDirectorySpread, calculateFeatureCount, detectFeatures, parseNonGoals, shouldSkipAssessment, } from "./analyzer.js";
 export { getMetricStatus, createScopeMetrics, calculateVerdict, generateRecommendation, getVerdictEmoji, getStatusEmoji, shouldEnableQualityLoop, } from "./verdict.js";
 export { formatNonGoals, formatMetricsTable, formatVerdict, formatScopeAssessment, formatCondensedAssessment, } from "./formatter.js";
+export { convertSettingsToConfig } from "./settings-converter.js";
 /**
  * Perform complete scope assessment
  *

package/dist/src/lib/scope/index.js

@@ -25,6 +25,8 @@ export { clusterACByKeyword, detectTitleVerbs, estimateDirectorySpread, calculat
 export { getMetricStatus, createScopeMetrics, calculateVerdict, generateRecommendation, getVerdictEmoji, getStatusEmoji, shouldEnableQualityLoop, } from "./verdict.js";
 // Re-export formatter functions
 export { formatNonGoals, formatMetricsTable, formatVerdict, formatScopeAssessment, formatCondensedAssessment, } from "./formatter.js";
+// Re-export settings converter
+export { convertSettingsToConfig } from "./settings-converter.js";
 /**
  * Perform complete scope assessment
  *

package/dist/src/lib/scope/settings-converter.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Settings to Config Converter
+ *
+ * Converts ScopeAssessmentSettings (from .sequant/settings.json)
+ * to ScopeAssessmentConfig (used by performScopeAssessment).
+ *
+ * This enables users to configure custom scope thresholds
+ * via their project settings file.
+ */
+import type { ScopeAssessmentSettings } from "../settings.js";
+import type { ScopeAssessmentConfig } from "./types.js";
+/**
+ * Convert ScopeAssessmentSettings to ScopeAssessmentConfig
+ *
+ * Merges user settings with defaults to produce a valid config.
+ * Any missing fields are filled from DEFAULT_SCOPE_CONFIG.
+ *
+ * @param settings - User settings from .sequant/settings.json
+ * @returns Complete config ready for performScopeAssessment
+ *
+ * @example
+ * ```typescript
+ * const settings = await getSettings();
+ * const config = convertSettingsToConfig(settings.scopeAssessment);
+ * const assessment = performScopeAssessment(criteria, body, title, config);
+ * ```
+ */
+export declare function convertSettingsToConfig(settings?: Partial<ScopeAssessmentSettings>): ScopeAssessmentConfig;

package/dist/src/lib/scope/settings-converter.js

@@ -0,0 +1,53 @@
+/**
+ * Settings to Config Converter
+ *
+ * Converts ScopeAssessmentSettings (from .sequant/settings.json)
+ * to ScopeAssessmentConfig (used by performScopeAssessment).
+ *
+ * This enables users to configure custom scope thresholds
+ * via their project settings file.
+ */
+import { DEFAULT_SCOPE_CONFIG } from "./types.js";
+/**
+ * Convert ScopeAssessmentSettings to ScopeAssessmentConfig
+ *
+ * Merges user settings with defaults to produce a valid config.
+ * Any missing fields are filled from DEFAULT_SCOPE_CONFIG.
+ *
+ * @param settings - User settings from .sequant/settings.json
+ * @returns Complete config ready for performScopeAssessment
+ *
+ * @example
+ * ```typescript
+ * const settings = await getSettings();
+ * const config = convertSettingsToConfig(settings.scopeAssessment);
+ * const assessment = performScopeAssessment(criteria, body, title, config);
+ * ```
+ */
+export function convertSettingsToConfig(settings) {
+    // Handle undefined/null settings
+    if (!settings) {
+        return DEFAULT_SCOPE_CONFIG;
+    }
+    // Helper to merge threshold with defaults
+    const mergeThreshold = (userThreshold, defaultThreshold) => ({
+        yellow: userThreshold?.yellow ?? defaultThreshold?.yellow ?? 0,
+        red: userThreshold?.red ?? defaultThreshold?.red ?? 0,
+    });
+    return {
+        enabled: settings.enabled ?? DEFAULT_SCOPE_CONFIG.enabled,
+        skipIfSimple: settings.skipIfSimple ?? DEFAULT_SCOPE_CONFIG.skipIfSimple,
+        trivialThresholds: {
+            maxACItems: settings.trivialThresholds?.maxACItems ??
+                DEFAULT_SCOPE_CONFIG.trivialThresholds.maxACItems,
+            maxDirectories: settings.trivialThresholds?.maxDirectories ??
+                DEFAULT_SCOPE_CONFIG.trivialThresholds.maxDirectories,
+        },
+        thresholds: {
+            featureCount: mergeThreshold(settings.thresholds?.featureCount, DEFAULT_SCOPE_CONFIG.thresholds.featureCount),
+            acItems: mergeThreshold(settings.thresholds?.acItems, DEFAULT_SCOPE_CONFIG.thresholds.acItems),
+            fileEstimate: mergeThreshold(settings.thresholds?.fileEstimate, DEFAULT_SCOPE_CONFIG.thresholds.fileEstimate),
+            directorySpread: mergeThreshold(settings.thresholds?.directorySpread, DEFAULT_SCOPE_CONFIG.thresholds.directorySpread),
+        },
+    };
+}

package/dist/src/lib/settings.d.ts

@@ -80,6 +80,13 @@ export interface RunSettings {
      * Default: true
      */
     mcp: boolean;
+    /**
+     * Enable automatic retry with MCP fallback.
+     * When true (default), failed phases are retried with MCP disabled.
+     * When false or --no-retry flag is used, no retry attempts are made.
+     * Default: true
+     */
+    retry: boolean;
 }
 /**
  * Scope assessment threshold configuration
@@ -90,14 +97,40 @@ export interface ScopeThreshold {
     /** Value at which status becomes red */
     red: number;
 }
+/**
+ * Trivial issue thresholds for skipping scope assessment
+ */
+export interface TrivialThresholds {
+    /**
+     * Maximum AC items for trivial classification.
+     * Issues with fewer AC items are considered trivial.
+     * Default: 3
+     */
+    maxACItems: number;
+    /**
+     * Maximum directories touched for trivial classification.
+     * Issues affecting fewer directories are considered trivial.
+     * Default: 1
+     */
+    maxDirectories: number;
+}
 /**
  * Scope assessment settings
+ *
+ * Configuration for scope assessment during /spec phase.
+ * These settings control how issue scope is evaluated and
+ * what thresholds trigger warnings.
  */
 export interface ScopeAssessmentSettings {
     /** Whether scope assessment is enabled (default: true) */
     enabled: boolean;
     /** Skip assessment for trivial issues (default: true) */
     skipIfSimple: boolean;
+    /**
+     * Trivial issue thresholds (skip if below all).
+     * Issues that fall below all these thresholds are skipped.
+     */
+    trivialThresholds: TrivialThresholds;
     /** Thresholds for scope metrics */
     thresholds: {
         /** Feature count thresholds (default: yellow=2, red=3) */
@@ -106,6 +139,8 @@ export interface ScopeAssessmentSettings {
         acItems: ScopeThreshold;
         /** File estimate thresholds (default: yellow=8, red=13) */
         fileEstimate: ScopeThreshold;
+        /** Directory spread thresholds (default: yellow=3, red=5) */
+        directorySpread: ScopeThreshold;
     };
 }
 /**
@@ -129,8 +164,18 @@ export declare const DEFAULT_ROTATION_SETTINGS: RotationSettings;
  * Default agent settings (cost-optimized)
  */
 export declare const DEFAULT_AGENT_SETTINGS: AgentSettings;
+/**
+ * Default trivial thresholds for scope assessment
+ *
+ * Issues that fall below ALL of these thresholds are considered trivial
+ * and scope assessment is skipped.
+ */
+export declare const DEFAULT_TRIVIAL_THRESHOLDS: TrivialThresholds;
 /**
  * Default scope assessment settings
+ *
+ * These defaults match the values in DEFAULT_SCOPE_CONFIG from
+ * src/lib/scope/types.ts to ensure consistency.
  */
 export declare const DEFAULT_SCOPE_ASSESSMENT_SETTINGS: ScopeAssessmentSettings;
 /**

package/dist/src/lib/settings.js

@@ -31,16 +31,41 @@ export const DEFAULT_AGENT_SETTINGS = {
     parallel: false,
     model: "haiku",
 };
+/**
+ * Default trivial thresholds for scope assessment
+ *
+ * Issues that fall below ALL of these thresholds are considered trivial
+ * and scope assessment is skipped.
+ */
+export const DEFAULT_TRIVIAL_THRESHOLDS = {
+    /** Issues with 3 or fewer AC items are potentially trivial */
+    maxACItems: 3,
+    /** Issues touching only 1 directory are potentially trivial */
+    maxDirectories: 1,
+};
 /**
  * Default scope assessment settings
+ *
+ * These defaults match the values in DEFAULT_SCOPE_CONFIG from
+ * src/lib/scope/types.ts to ensure consistency.
  */
 export const DEFAULT_SCOPE_ASSESSMENT_SETTINGS = {
+    /** Enable scope assessment by default */
     enabled: true,
+    /** Skip assessment for trivial issues by default */
     skipIfSimple: true,
+    /** Trivial issue thresholds - skip if below all */
+    trivialThresholds: DEFAULT_TRIVIAL_THRESHOLDS,
+    /** Thresholds for scope metrics */
     thresholds: {
+        /** 2 features = yellow warning, 3+ = red (split recommended) */
         featureCount: { yellow: 2, red: 3 },
+        /** 6-8 AC items = yellow, 9+ = red */
         acItems: { yellow: 6, red: 9 },
+        /** 8-12 files estimated = yellow, 13+ = red */
         fileEstimate: { yellow: 8, red: 13 },
+        /** 3-4 directories = yellow, 5+ = red */
+        directorySpread: { yellow: 3, red: 5 },
     },
 };
 /**
@@ -59,6 +84,7 @@ export const DEFAULT_SETTINGS = {
         smartTests: true,
         rotation: DEFAULT_ROTATION_SETTINGS,
         mcp: true, // Enable MCP servers by default in headless mode
+        retry: true, // Enable automatic retry with MCP fallback by default
     },
     agents: DEFAULT_AGENT_SETTINGS,
     scopeAssessment: DEFAULT_SCOPE_ASSESSMENT_SETTINGS,
@@ -89,6 +115,10 @@ export async function getSettings() {
             scopeAssessment: {
                 ...DEFAULT_SCOPE_ASSESSMENT_SETTINGS,
                 ...parsed.scopeAssessment,
+                trivialThresholds: {
+                    ...DEFAULT_SCOPE_ASSESSMENT_SETTINGS.trivialThresholds,
+                    ...parsed.scopeAssessment?.trivialThresholds,
+                },
                 thresholds: {
                     ...DEFAULT_SCOPE_ASSESSMENT_SETTINGS.thresholds,
                     ...parsed.scopeAssessment?.thresholds,

package/dist/src/lib/test-tautology-detector.d.ts

@@ -0,0 +1,122 @@
+/**
+ * Test Tautology Detector
+ *
+ * Detects tautological tests — tests that pass but don't call any production code.
+ * These tests provide zero regression protection as they only assert on local values.
+ *
+ * @example
+ * ```typescript
+ * import { detectTautologicalTests, formatTautologyResults } from './test-tautology-detector';
+ *
+ * const results = detectTautologicalTests([
+ *   { path: 'src/lib/foo.test.ts', content: fileContent },
+ * ]);
+ * console.log(formatTautologyResults(results));
+ * ```
+ */
+/**
+ * Represents an imported function from a source module
+ */
+export interface ImportedFunction {
+    /** Function name */
+    name: string;
+    /** Module path the function was imported from */
+    modulePath: string;
+}
+/**
+ * Represents a test block (it() or test())
+ */
+export interface TestBlock {
+    /** Test description */
+    description: string;
+    /** Line number where the test starts */
+    lineNumber: number;
+    /** Whether this test is tautological (no production function calls) */
+    isTautological: boolean;
+    /** Style of test block: 'it' or 'test' */
+    style: "it" | "test";
+}
+/**
+ * Result of analyzing a single test file
+ */
+export interface TautologyFileResult {
+    /** Path to the test file */
+    filePath: string;
+    /** Total number of test blocks found */
+    totalTests: number;
+    /** Number of tautological test blocks */
+    tautologicalCount: number;
+    /** Percentage of tests that are tautological */
+    tautologicalPercentage: number;
+    /** Individual test blocks with their analysis */
+    testBlocks: TestBlock[];
+    /** Imported functions from source modules */
+    importedFunctions: ImportedFunction[];
+    /** Whether the file could be parsed successfully */
+    parseSuccess: boolean;
+    /** Error message if parsing failed */
+    parseError?: string;
+}
+/**
+ * Overall tautology detection results
+ */
+export interface TautologyResults {
+    /** Results for each analyzed file */
+    fileResults: TautologyFileResult[];
+    /** Summary statistics */
+    summary: {
+        totalFiles: number;
+        totalTests: number;
+        totalTautological: number;
+        overallPercentage: number;
+        /** Whether >50% of tests are tautological (blocking threshold) */
+        exceedsBlockingThreshold: boolean;
+    };
+}
+/**
+ * Check if an import path is from a source module (not a test library or mock)
+ */
+export declare function isSourceModule(modulePath: string): boolean;
+/**
+ * Extract imports from a test file
+ *
+ * Handles:
+ * - Named imports: `import { foo, bar } from './module'`
+ * - Default imports: `import foo from './module'`
+ * - Namespace imports: `import * as foo from './module'` (extracts the namespace name)
+ */
+export declare function extractImports(content: string): ImportedFunction[];
+/**
+ * Extract test blocks (it() and test()) from content
+ *
+ * Returns the description, line number, body content, and style of each test block.
+ */
+export declare function extractTestBlocks(content: string): Array<{
+    description: string;
+    lineNumber: number;
+    body: string;
+    style: "it" | "test";
+}>;
+/**
+ * Check if a test block contains calls to any of the imported production functions
+ */
+export declare function testBlockCallsProductionCode(body: string, importedFunctions: ImportedFunction[]): boolean;
+/**
+ * Analyze a single test file for tautological tests
+ */
+export declare function analyzeTestFile(content: string, filePath: string): TautologyFileResult;
+/**
+ * Detect tautological tests across multiple files
+ */
+export declare function detectTautologicalTests(files: Array<{
+    path: string;
+    content: string;
+}>): TautologyResults;
+/**
+ * Format tautology results as markdown for QA output
+ */
+export declare function formatTautologyResults(results: TautologyResults): string;
+/**
+ * Determine verdict impact based on tautology results
+ */
+export declare function getTautologyVerdictImpact(results: TautologyResults): "none" | "warning" | "blocking";