sequant 1.13.4 → 1.14.0

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "sequant",
   "description": "Structured workflow system for Claude Code - GitHub issue resolution with spec, exec, test, and QA phases",
-  "version": "1.13.4",
+  "version": "1.14.0",
   "author": {
     "name": "admarble",
     "email": "github@admarble.com"

package/README.md

@@ -9,11 +9,12 @@ Solve GitHub issues with structured phases and quality gates — from issue to m
 
 ## Quick Start
 
-### Install via npm (Recommended)
+### Install
 
 ```bash
 # In your project directory
 npm install sequant
+npx sequant init     # Install skills to your project
 npx sequant doctor   # Verify setup
 ```
 
@@ -22,18 +23,6 @@ To update:
 npm update sequant
 ```
 
-### Alternative: Install as Claude Code Plugin
-
-> **Note:** Plugin updates via `/plugin update` may not work reliably. Use `npm update sequant` to get latest skills.
-
-```bash
-# Add the Sequant marketplace
-/plugin marketplace add admarble/sequant
-
-# Install the plugin
-/plugin install sequant
-```
-
 ### Start Using
 
 Then in Claude Code:
@@ -238,7 +227,6 @@ See [Customization Guide](docs/guides/customization.md) for all options.
 - [Run Command](docs/reference/run-command.md)
 - [Git Workflows](docs/guides/git-workflows.md)
 - [Customization](docs/guides/customization.md)
-- [Plugin Updates & Versioning](docs/internal/plugin-updates.md)
 - [Troubleshooting](docs/troubleshooting.md)
 
 Stack guides: [Next.js](docs/stacks/nextjs.md) · [Rust](docs/stacks/rust.md) · [Python](docs/stacks/python.md) · [Go](docs/stacks/go.md)
@@ -249,7 +237,6 @@ Stack guides: [Next.js](docs/stacks/nextjs.md) · [Rust](docs/stacks/rust.md) ·
 
 ### Reporting Issues
 
-- **Plugin issues:** [Plugin Feedback template](https://github.com/admarble/sequant/issues/new?template=plugin-feedback.yml)
 - **Bug reports:** [Bug template](https://github.com/admarble/sequant/issues/new?template=bug.yml)
 - **Feature requests:** [Feature template](https://github.com/admarble/sequant/issues/new?template=feature.yml)
 - **Questions:** [GitHub Discussions](https://github.com/admarble/sequant/discussions)

package/dist/src/commands/run.js

@@ -605,6 +605,8 @@ async function executePhase(issueNumber, phase, config, sessionId, worktreePath,
     // Determine working directory and environment
     const shouldUseWorktree = worktreePath && ISOLATED_PHASES.includes(phase);
     const cwd = shouldUseWorktree ? worktreePath : process.cwd();
+    // Track stderr for error diagnostics (declared outside try for catch access)
+    let capturedStderr = "";
     try {
         // Check if shutdown is in progress
         if (shutdownManager?.shuttingDown) {
@@ -667,6 +669,15 @@ async function executePhase(issueNumber, phase, config, sessionId, worktreePath,
                 env,
                 // Pass MCP servers for headless mode (AC-2)
                 ...(mcpServers ? { mcpServers } : {}),
+                // Capture stderr for debugging (helps diagnose early exit failures)
+                stderr: (data) => {
+                    capturedStderr += data;
+                    if (config.verbose) {
+                        spinner?.pause();
+                        process.stderr.write(chalk.red(data));
+                        spinner?.resume();
+                    }
+                },
             },
         });
         // Stream and process messages
@@ -791,11 +802,15 @@ async function executePhase(issueNumber, phase, config, sessionId, worktreePath,
                 error: `Timeout after ${config.phaseTimeout}s`,
             };
         }
+        // Include stderr in error message if available (helps diagnose early exit failures)
+        const stderrSuffix = capturedStderr
+            ? `\nStderr: ${capturedStderr.slice(0, 500)}`
+            : "";
         return {
             phase,
             success: false,
             durationSeconds,
-            error,
+            error: error + stderrSuffix,
         };
     }
 }

package/dist/src/lib/cli-ui.d.ts

@@ -51,7 +51,7 @@ export declare const colors: {
     failed: import("chalk").ChalkInstance | ((s: string) => string);
 };
 /**
- * Get the ASCII logo with optional gradient
+ * Get the ASCII logo with brand color
  */
 export declare function logo(): string;
 /**

package/dist/src/lib/cli-ui.js

@@ -9,7 +9,6 @@ import ora from "ora";
 import boxen from "boxen";
 // cli-table3 uses CommonJS `export =` syntax, default import works with esModuleInterop
 import Table from "cli-table3";
-import gradient from "gradient-string";
 import { isCI, isStdoutTTY } from "./tty.js";
 /**
  * Global UI configuration state
@@ -109,27 +108,26 @@ function isLegacyWindows() {
 // ============================================================================
 /**
  * Static ASCII logo for SEQUANT branding
- * Pre-generated to avoid ~1MB figlet font bundle
+ * Clean, legible design inspired by the sequant logo
+ * Q has distinctive tail like the brand logo
  */
-const ASCII_LOGO = `
-   _____ _____ _____ _   _ _____ _   _ _____
-  /  ___/  ___|  _  | | | |  _  | \\ | |_   _|
-  \\ \`--.\\ \`--.| | | | | | | | | |  \\| | | |
-   \`--. \\\`--. \\ \\_/ / | | \\_| |_| . \` | | |
-  /\\__/ /\\__/ /\\___/\\ |_| |\\___/\\_|\\_/ \\_/
-  \\____/\\____/       \\___/
-`.trimStart();
+const ASCII_LOGO = ` ██████  ███████   ██████   ██    ██   █████   ███    ██  ████████
+██       ██       ██    ██  ██    ██  ██   ██  ████   ██     ██
+ █████   █████    ██    ██  ██    ██  ███████  ██ ██  ██     ██
+     ██  ██       ██ ▄▄ ██  ██    ██  ██   ██  ██  ██ ██     ██
+██████   ███████   ██████    ██████   ██   ██  ██   ████     ██
+                      ▀▀
+`;
 /**
- * Get the ASCII logo with optional gradient
+ * Get the ASCII logo with brand color
  */
 export function logo() {
     if (config.jsonMode || config.minimal)
         return "";
     if (config.noColor || !config.isTTY)
         return ASCII_LOGO;
-    // Apply gradient for color terminals
-    const sequantGradient = gradient(["#00D4FF", "#7B68EE", "#FF6B9D"]);
-    return sequantGradient(ASCII_LOGO);
+    // Apply brand orange color
+    return chalk.hex("#FF8012")(ASCII_LOGO);
 }
 /**
  * Get the banner (logo + tagline)

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

@@ -0,0 +1,91 @@
+/**
+ * Scope Analyzer
+ *
+ * Detects bundled features and analyzes issue scope using heuristics:
+ * - AC clustering by functional area
+ * - Title verb detection (multiple verbs = multiple features)
+ * - Directory spread analysis
+ *
+ * @example
+ * ```typescript
+ * import { detectFeatures, analyzeScope } from './analyzer';
+ *
+ * const criteria = parseAcceptanceCriteria(issueBody);
+ * const detection = detectFeatures(criteria, issueTitle);
+ * console.log(`Feature count: ${detection.featureCount}`);
+ * ```
+ */
+import type { AcceptanceCriterion } from "../workflow/state-schema.js";
+import type { ACCluster, FeatureDetection, NonGoals, ScopeAssessmentConfig } from "./types.js";
+/**
+ * Cluster AC items by functional area based on keywords
+ *
+ * @param criteria - Parsed acceptance criteria
+ * @returns Array of AC clusters
+ */
+export declare function clusterACByKeyword(criteria: AcceptanceCriterion[]): ACCluster[];
+/**
+ * Detect action verbs in issue title
+ *
+ * @param title - Issue title
+ * @returns Array of detected verbs
+ */
+export declare function detectTitleVerbs(title: string): string[];
+/**
+ * Estimate directory spread from AC descriptions
+ *
+ * Looks for patterns that suggest different areas of the codebase:
+ * - File path mentions (src/, lib/, components/)
+ * - Module references
+ * - Component type mentions
+ *
+ * @param criteria - Parsed acceptance criteria
+ * @returns Estimated number of distinct directories
+ */
+export declare function estimateDirectorySpread(criteria: AcceptanceCriterion[]): {
+    spread: number;
+    directories: string[];
+};
+/**
+ * Calculate feature count based on multiple signals
+ *
+ * Algorithm:
+ * 1. Count distinct AC clusters (if >1, suggests multiple features)
+ * 2. Count action verbs in title (multiple verbs = multiple features)
+ * 3. Consider directory spread (wide spread suggests complexity)
+ *
+ * @param clusters - AC clusters from keyword analysis
+ * @param titleVerbs - Detected verbs from title
+ * @param directorySpread - Number of directories touched
+ * @returns Estimated feature count
+ */
+export declare function calculateFeatureCount(clusters: ACCluster[], titleVerbs: string[], directorySpread: number): number;
+/**
+ * Detect features in issue based on AC items and title
+ *
+ * @param criteria - Parsed acceptance criteria
+ * @param title - Issue title
+ * @returns Feature detection result
+ */
+export declare function detectFeatures(criteria: AcceptanceCriterion[], title: string): FeatureDetection;
+/**
+ * Parse non-goals section from issue body
+ *
+ * Looks for a "Non-Goals" or "Out of Scope" section with checkbox items.
+ *
+ * @param issueBody - Full issue body markdown
+ * @returns Non-goals extraction result
+ */
+export declare function parseNonGoals(issueBody: string): NonGoals;
+/**
+ * Check if an issue should skip scope assessment (trivial issue)
+ *
+ * @param acCount - Number of acceptance criteria
+ * @param directorySpread - Estimated directory spread
+ * @param config - Scope assessment configuration
+ * @returns Whether to skip assessment
+ */
+export declare function shouldSkipAssessment(acCount: number, directorySpread: number, config?: ScopeAssessmentConfig): {
+    skip: boolean;
+    reason?: string;
+};

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

@@ -0,0 +1,310 @@
+/**
+ * Scope Analyzer
+ *
+ * Detects bundled features and analyzes issue scope using heuristics:
+ * - AC clustering by functional area
+ * - Title verb detection (multiple verbs = multiple features)
+ * - Directory spread analysis
+ *
+ * @example
+ * ```typescript
+ * import { detectFeatures, analyzeScope } from './analyzer';
+ *
+ * const criteria = parseAcceptanceCriteria(issueBody);
+ * const detection = detectFeatures(criteria, issueTitle);
+ * console.log(`Feature count: ${detection.featureCount}`);
+ * ```
+ */
+import { DEFAULT_SCOPE_CONFIG } from "./types.js";
+/**
+ * Keywords for clustering AC items by functional area
+ */
+const CLUSTER_KEYWORDS = {
+    auth: [
+        "auth",
+        "login",
+        "logout",
+        "session",
+        "password",
+        "token",
+        "jwt",
+        "oauth",
+        "sso",
+    ],
+    ui: [
+        "display",
+        "show",
+        "render",
+        "button",
+        "form",
+        "modal",
+        "page",
+        "component",
+        "ui",
+        "dashboard",
+    ],
+    api: [
+        "api",
+        "endpoint",
+        "route",
+        "request",
+        "response",
+        "http",
+        "rest",
+        "graphql",
+    ],
+    data: [
+        "database",
+        "db",
+        "query",
+        "store",
+        "save",
+        "persist",
+        "cache",
+        "storage",
+    ],
+    perf: [
+        "performance",
+        "optimize",
+        "speed",
+        "fast",
+        "slow",
+        "latency",
+        "throughput",
+    ],
+    config: ["config", "setting", "option", "preference", "environment", "env"],
+    test: ["test", "spec", "coverage", "mock", "stub", "fixture"],
+    docs: ["document", "readme", "guide", "tutorial", "example"],
+    error: ["error", "exception", "fail", "handle", "catch", "throw"],
+    validation: ["valid", "invalid", "check", "verify", "sanitize"],
+};
+/**
+ * Action verbs that indicate distinct features when multiple are present
+ */
+const ACTION_VERBS = [
+    "add",
+    "create",
+    "implement",
+    "build",
+    "fix",
+    "update",
+    "refactor",
+    "remove",
+    "delete",
+    "improve",
+    "optimize",
+    "migrate",
+    "convert",
+    "integrate",
+    "enable",
+    "disable",
+];
+/**
+ * Cluster AC items by functional area based on keywords
+ *
+ * @param criteria - Parsed acceptance criteria
+ * @returns Array of AC clusters
+ */
+export function clusterACByKeyword(criteria) {
+    const clusters = new Map();
+    const unclassified = [];
+    for (const ac of criteria) {
+        const descLower = ac.description.toLowerCase();
+        let matched = false;
+        for (const [keyword, patterns] of Object.entries(CLUSTER_KEYWORDS)) {
+            if (patterns.some((p) => descLower.includes(p))) {
+                const existing = clusters.get(keyword) ?? [];
+                existing.push(ac.id);
+                clusters.set(keyword, existing);
+                matched = true;
+                break; // Only assign to first matching cluster
+            }
+        }
+        if (!matched) {
+            unclassified.push(ac.id);
+        }
+    }
+    // Add unclassified as a separate cluster if not empty
+    if (unclassified.length > 0) {
+        clusters.set("other", unclassified);
+    }
+    // Convert to array format
+    return Array.from(clusters.entries()).map(([keyword, acIds]) => ({
+        keyword,
+        acIds,
+        count: acIds.length,
+    }));
+}
+/**
+ * Detect action verbs in issue title
+ *
+ * @param title - Issue title
+ * @returns Array of detected verbs
+ */
+export function detectTitleVerbs(title) {
+    const titleLower = title.toLowerCase();
+    const detected = [];
+    for (const verb of ACTION_VERBS) {
+        // Match word boundaries to avoid partial matches
+        const regex = new RegExp(`\\b${verb}\\b`, "i");
+        if (regex.test(titleLower)) {
+            detected.push(verb);
+        }
+    }
+    return detected;
+}
+/**
+ * Estimate directory spread from AC descriptions
+ *
+ * Looks for patterns that suggest different areas of the codebase:
+ * - File path mentions (src/, lib/, components/)
+ * - Module references
+ * - Component type mentions
+ *
+ * @param criteria - Parsed acceptance criteria
+ * @returns Estimated number of distinct directories
+ */
+export function estimateDirectorySpread(criteria) {
+    const directories = new Set();
+    // Common directory patterns
+    const dirPatterns = [
+        /\b(src|lib|utils|helpers)\b/i,
+        /\b(components|pages|views|layouts)\b/i,
+        /\b(api|routes|handlers|controllers)\b/i,
+        /\b(models|schemas|types|interfaces)\b/i,
+        /\b(tests?|__tests__|specs?)\b/i,
+        /\b(scripts|bin|cli)\b/i,
+        /\b(config|settings)\b/i,
+        /\b(docs|documentation)\b/i,
+        /\b(styles|css|scss)\b/i,
+        /\b(hooks|contexts?|providers?)\b/i,
+        /\b(services|queries|mutations)\b/i,
+        /\b(middleware|plugins?)\b/i,
+    ];
+    for (const ac of criteria) {
+        const desc = ac.description;
+        for (const pattern of dirPatterns) {
+            const match = desc.match(pattern);
+            if (match) {
+                directories.add(match[1].toLowerCase());
+            }
+        }
+    }
+    return {
+        spread: directories.size,
+        directories: Array.from(directories),
+    };
+}
+/**
+ * Calculate feature count based on multiple signals
+ *
+ * Algorithm:
+ * 1. Count distinct AC clusters (if >1, suggests multiple features)
+ * 2. Count action verbs in title (multiple verbs = multiple features)
+ * 3. Consider directory spread (wide spread suggests complexity)
+ *
+ * @param clusters - AC clusters from keyword analysis
+ * @param titleVerbs - Detected verbs from title
+ * @param directorySpread - Number of directories touched
+ * @returns Estimated feature count
+ */
+export function calculateFeatureCount(clusters, titleVerbs, directorySpread) {
+    // Base: number of distinct clusters with >1 AC items
+    const significantClusters = clusters.filter((c) => c.count >= 2).length;
+    // Additional signal: multiple verbs in title
+    const verbSignal = Math.max(0, titleVerbs.length - 1);
+    // Directory spread signal (normalized)
+    const dirSignal = directorySpread >= 4 ? 1 : 0;
+    // Combine signals with weights
+    // Clusters are primary signal, title and directories are secondary
+    const rawCount = significantClusters + verbSignal * 0.5 + dirSignal * 0.5;
+    // Minimum is 1 feature, round to nearest integer
+    return Math.max(1, Math.round(rawCount));
+}
+/**
+ * Detect features in issue based on AC items and title
+ *
+ * @param criteria - Parsed acceptance criteria
+ * @param title - Issue title
+ * @returns Feature detection result
+ */
+export function detectFeatures(criteria, title) {
+    const clusters = clusterACByKeyword(criteria);
+    const titleVerbs = detectTitleVerbs(title);
+    const { spread, directories } = estimateDirectorySpread(criteria);
+    const featureCount = calculateFeatureCount(clusters, titleVerbs, spread);
+    return {
+        featureCount,
+        clusters,
+        multipleVerbs: titleVerbs.length > 1,
+        titleVerbs,
+        directorySpread: spread,
+        directories,
+    };
+}
+/**
+ * Parse non-goals section from issue body
+ *
+ * Looks for a "Non-Goals" or "Out of Scope" section with checkbox items.
+ *
+ * @param issueBody - Full issue body markdown
+ * @returns Non-goals extraction result
+ */
+export function parseNonGoals(issueBody) {
+    const items = [];
+    // Find Non-Goals section (case-insensitive)
+    const sectionPattern = /##\s*(?:Non[- ]?Goals|Out\s+of\s+Scope|Scope\s+Boundaries)\s*\n([\s\S]*?)(?=\n##|\n---|$)/i;
+    const sectionMatch = issueBody.match(sectionPattern);
+    if (!sectionMatch) {
+        return {
+            items: [],
+            found: false,
+            warning: "Non-Goals section not found. Consider adding scope boundaries.",
+        };
+    }
+    const sectionContent = sectionMatch[1];
+    // Extract checkbox items or list items
+    const itemPattern = /^[-*]\s*(?:\[[ x]\]\s*)?(.+)$/gim;
+    let match;
+    while ((match = itemPattern.exec(sectionContent)) !== null) {
+        const item = match[1].trim();
+        if (item && !item.startsWith("#")) {
+            items.push(item);
+        }
+    }
+    if (items.length === 0) {
+        return {
+            items: [],
+            found: true,
+            warning: "Non-Goals section is empty. Add explicit scope boundaries.",
+        };
+    }
+    return {
+        items,
+        found: true,
+    };
+}
+/**
+ * Check if an issue should skip scope assessment (trivial issue)
+ *
+ * @param acCount - Number of acceptance criteria
+ * @param directorySpread - Estimated directory spread
+ * @param config - Scope assessment configuration
+ * @returns Whether to skip assessment
+ */
+export function shouldSkipAssessment(acCount, directorySpread, config = DEFAULT_SCOPE_CONFIG) {
+    if (!config.enabled) {
+        return { skip: true, reason: "Scope assessment disabled in config" };
+    }
+    if (!config.skipIfSimple) {
+        return { skip: false };
+    }
+    const { maxACItems, maxDirectories } = config.trivialThresholds;
+    if (acCount <= maxACItems && directorySpread <= maxDirectories) {
+        return {
+            skip: true,
+            reason: `Trivial issue (${acCount} AC items, ${directorySpread} directories)`,
+        };
+    }
+    return { skip: false };
+}

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

@@ -0,0 +1,52 @@
+/**
+ * Scope Assessment Formatter
+ *
+ * Formats scope assessment results as markdown for /spec output
+ * and GitHub issue comments.
+ *
+ * @example
+ * ```typescript
+ * import { formatScopeAssessment } from './formatter';
+ *
+ * const assessment = performScopeAssessment(criteria, issueBody, title);
+ * console.log(formatScopeAssessment(assessment));
+ * ```
+ */
+import type { ScopeAssessment, NonGoals } from "./types.js";
+/**
+ * Format non-goals section for output
+ *
+ * @param nonGoals - Non-goals parsing result
+ * @returns Formatted markdown string
+ */
+export declare function formatNonGoals(nonGoals: NonGoals): string;
+/**
+ * Format scope metrics table
+ *
+ * @param assessment - Complete scope assessment
+ * @returns Formatted markdown table
+ */
+export declare function formatMetricsTable(assessment: ScopeAssessment): string;
+/**
+ * Format scope verdict section
+ *
+ * @param assessment - Complete scope assessment
+ * @returns Formatted markdown string
+ */
+export declare function formatVerdict(assessment: ScopeAssessment): string;
+/**
+ * Format complete scope assessment section
+ *
+ * @param assessment - Complete scope assessment
+ * @returns Formatted markdown string
+ */
+export declare function formatScopeAssessment(assessment: ScopeAssessment): string;
+/**
+ * Format condensed scope assessment for issue comments
+ *
+ * A shorter version suitable for GitHub issue comments.
+ *
+ * @param assessment - Complete scope assessment
+ * @returns Condensed markdown string
+ */
+export declare function formatCondensedAssessment(assessment: ScopeAssessment): string;