sequant 2.1.2 → 2.2.0

package/.claude-plugin/marketplace.json

@@ -8,7 +8,7 @@
     {
       "name": "sequant",
       "description": "Structured workflow system for Claude Code - GitHub issue resolution with spec, exec, test, and QA phases. Includes 17 skills, MCP server with workflow tools, and pre/post-tool hooks.",
-      "version": "2.1.0",
+      "version": "2.2.0",
       "author": {
         "name": "sequant-io",
         "email": "hello@sequant.io"

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": "2.1.2",
+  "version": "2.2.0",
   "author": {
     "name": "sequant-io",
     "email": "hello@sequant.io"

package/dist/bin/cli.js

@@ -86,6 +86,7 @@ program
     .option("--no-symlinks", "Use copies instead of symlinks for scripts/dev/ files")
     .option("--no-agents-md", "Skip AGENTS.md generation")
     .option("--mcp", "Add Sequant MCP server to detected clients (use with --yes)")
+    .option("--upgrade-skills", "Upgrade skill files from installed package templates (with diff preview)")
     .action(initCommand);
 program
     .command("update")

package/dist/src/commands/init.d.ts

@@ -10,6 +10,7 @@ interface InitOptions {
     noSymlinks?: boolean;
     agentsMd?: boolean;
     mcp?: boolean;
+    upgradeSkills?: boolean;
 }
 export declare function initCommand(options: InitOptions): Promise<void>;
 export {};

package/dist/src/commands/init.js

@@ -2,7 +2,10 @@
  * sequant init - Initialize Sequant in a project
  */
 import chalk from "chalk";
+import { diffLines } from "diff";
 import inquirer from "inquirer";
+import { join, dirname } from "path";
+import { readdir } from "fs/promises";
 import { ui, colors } from "../lib/cli-ui.js";
 import { detectStack, detectAllStacks, getStackConfig, detectPackageManager, getPackageManagerCommands, STACKS, } from "../lib/stacks.js";
 import { copyTemplates } from "../lib/templates.js";
@@ -70,6 +73,11 @@ function logDefault(label, value) {
     console.log(chalk.blue(`${label}: ${value} (default)`));
 }
 export async function initCommand(options) {
+    // Handle --upgrade-skills: update skill files from installed package templates
+    if (options.upgradeSkills) {
+        await upgradeSkills();
+        return;
+    }
     // Show banner
     console.log(ui.banner());
     console.log(colors.success("\nInitializing Sequant...\n"));
@@ -503,3 +511,113 @@ export async function initCommand(options) {
     }
     console.log(chalk.gray("\nDocumentation: https://github.com/sequant-io/sequant#readme\n"));
 }
+/**
+ * Upgrade installed skill files from the sequant package's templates.
+ * Shows a diff preview for each changed file and asks for confirmation.
+ */
+async function upgradeSkills() {
+    console.log(chalk.bold("\nUpgrading skills from package templates...\n"));
+    const installedDir = ".claude/skills";
+    if (!(await fileExists(installedDir))) {
+        console.log(chalk.red("No skills directory found. Run `sequant init` first."));
+        return;
+    }
+    // Resolve the package's templates/skills directory
+    const { getTemplatesDir } = await import("../lib/templates.js");
+    const templateSkillsDir = join(getTemplatesDir(), "skills");
+    // Collect all files from both directories
+    const changes = [];
+    const newFiles = [];
+    async function compareDir(templateDir, installedBaseDir, relativePrefix) {
+        let entries;
+        try {
+            entries = await readdir(templateDir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            const relPath = join(relativePrefix, entry.name);
+            const templatePath = join(templateDir, entry.name);
+            const installedPath = join(installedBaseDir, relPath);
+            if (entry.isDirectory()) {
+                await compareDir(templatePath, installedBaseDir, relPath);
+            }
+            else {
+                const templateContent = await readFile(templatePath);
+                const exists = await fileExists(installedPath);
+                if (!exists) {
+                    newFiles.push({ path: relPath, content: templateContent });
+                }
+                else {
+                    const installedContent = await readFile(installedPath);
+                    if (installedContent !== templateContent) {
+                        changes.push({
+                            path: relPath,
+                            installed: installedContent,
+                            template: templateContent,
+                        });
+                    }
+                }
+            }
+        }
+    }
+    await compareDir(templateSkillsDir, installedDir, "");
+    if (changes.length === 0 && newFiles.length === 0) {
+        console.log(chalk.green("All skills are up to date."));
+        return;
+    }
+    // Show summary
+    console.log(chalk.bold("Changes found:"));
+    if (changes.length > 0) {
+        console.log(chalk.yellow(`  Modified: ${changes.length} file(s)`));
+    }
+    if (newFiles.length > 0) {
+        console.log(chalk.green(`  New: ${newFiles.length} file(s)`));
+    }
+    console.log();
+    // Show diffs for modified files
+    for (const change of changes) {
+        console.log(chalk.yellow(`--- ${change.path} ---`));
+        const diff = diffLines(change.installed, change.template);
+        for (const part of diff) {
+            if (part.added) {
+                process.stdout.write(chalk.green(part.value));
+            }
+            else if (part.removed) {
+                process.stdout.write(chalk.red(part.value));
+            }
+            // Skip unchanged lines in diff output
+        }
+        console.log();
+    }
+    // Show new files
+    for (const file of newFiles) {
+        console.log(chalk.green(`+++ ${file.path} (new)`));
+    }
+    // Ask for confirmation
+    const isInteractive = shouldUseInteractiveMode();
+    if (isInteractive) {
+        const { proceed } = await inquirer.prompt([
+            {
+                type: "confirm",
+                name: "proceed",
+                message: `Apply ${changes.length + newFiles.length} skill update(s)?`,
+                default: true,
+            },
+        ]);
+        if (!proceed) {
+            console.log(chalk.gray("Aborted."));
+            return;
+        }
+    }
+    // Apply changes
+    for (const change of changes) {
+        await writeFile(join(installedDir, change.path), change.template);
+    }
+    for (const file of newFiles) {
+        await ensureDir(dirname(join(installedDir, file.path)));
+        await writeFile(join(installedDir, file.path), file.content);
+    }
+    console.log(chalk.green(`\nUpgraded ${changes.length + newFiles.length} skill file(s).`));
+}

package/dist/src/commands/run-display.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Display helpers for `sequant run` — pre-run config block + post-run summary.
+ *
+ * Kept separate from run.ts so the adapter stays thin (see AC-2 of #503).
+ */
+import type { ResolvedRun, RunResult } from "../lib/workflow/run-orchestrator.js";
+/**
+ * Print pre-run config block.
+ *
+ * Columnar alignment via 15-char label padding. Conditional rows only
+ * appear when non-default, matching the pre-#503 format.
+ */
+export declare function displayConfig(r: ResolvedRun): void;
+/**
+ * Print post-run summary: per-issue status, log path, reflection, tips.
+ */
+export declare function displaySummary(result: RunResult): void;

package/dist/src/commands/run-display.js

@@ -0,0 +1,116 @@
+/**
+ * Display helpers for `sequant run` — pre-run config block + post-run summary.
+ *
+ * Kept separate from run.ts so the adapter stays thin (see AC-2 of #503).
+ */
+import chalk from "chalk";
+import { ui, colors } from "../lib/cli-ui.js";
+import { formatDuration } from "../lib/workflow/phase-executor.js";
+import { analyzeRun, formatReflection } from "../lib/workflow/run-reflect.js";
+/**
+ * Print pre-run config block.
+ *
+ * Columnar alignment via 15-char label padding. Conditional rows only
+ * appear when non-default, matching the pre-#503 format.
+ */
+export function displayConfig(r) {
+    const pad = (label) => label.padEnd(15);
+    const row = (label, value) => console.log(chalk.gray(`  ${pad(label)}${value}`));
+    row("Stack", r.stack);
+    if (r.autoDetectPhases) {
+        row("Phases", "auto-detect from labels");
+    }
+    else {
+        row("Phases", r.config.phases.join(" \u2192 "));
+    }
+    row("Mode", r.config.sequential
+        ? "sequential (stop-on-failure)"
+        : `parallel (concurrency: ${r.config.concurrency})`);
+    if (r.config.qualityLoop) {
+        row("Quality loop", `enabled (max ${r.config.maxIterations} iterations)`);
+    }
+    if (r.mergedOptions.testgen)
+        row("Testgen", "enabled");
+    if (r.config.noSmartTests)
+        row("Smart tests", "disabled");
+    if (r.config.dryRun) {
+        console.log(chalk.yellow(`  !  DRY RUN - no actual execution`));
+    }
+    if (r.logEnabled)
+        row("Logging", "JSON");
+    if (r.stateEnabled)
+        row("State", "enabled");
+    if (r.mergedOptions.force) {
+        console.log(chalk.yellow(`  ${pad("Force")}enabled (bypass state guard)`));
+    }
+    if (r.issueNumbers.length > 0) {
+        row("Issues", r.issueNumbers.map((n) => `#${n}`).join(", "));
+    }
+    if (r.worktreeIsolationEnabled) {
+        console.log(chalk.gray(`  Worktree isolation: enabled`));
+    }
+    if (r.baseBranch) {
+        console.log(chalk.gray(`  Base branch: ${r.baseBranch}`));
+    }
+    if (r.mergedOptions.chain) {
+        console.log(chalk.gray(`  Chain mode: enabled (each issue branches from previous)`));
+    }
+    if (r.mergedOptions.qaGate) {
+        console.log(chalk.gray(`  QA gate: enabled (chain waits for QA pass)`));
+    }
+}
+/**
+ * Print post-run summary: per-issue status, log path, reflection, tips.
+ */
+export function displaySummary(result) {
+    const { results, logPath, config, mergedOptions } = result;
+    if (results.length === 0)
+        return;
+    const passed = results.filter((r) => r.success).length;
+    const failed = results.filter((r) => !r.success).length;
+    console.log("\n" + ui.divider());
+    console.log(colors.info("  Summary"));
+    console.log(ui.divider());
+    console.log(`\n  ${colors.success(`${passed} passed`)} ${colors.muted("·")} ${colors.error(`${failed} failed`)}`);
+    for (const r of results) {
+        const status = r.success
+            ? ui.statusIcon("success")
+            : ui.statusIcon("error");
+        const duration = r.durationSeconds
+            ? colors.muted(` (${formatDuration(r.durationSeconds)})`)
+            : "";
+        const phases = r.phaseResults
+            .map((p) => (p.success ? colors.success(p.phase) : colors.error(p.phase)))
+            .join(" → ");
+        const loopInfo = r.loopTriggered ? colors.warning(" [loop]") : "";
+        const prInfo = r.prUrl ? colors.muted(` → PR #${r.prNumber}`) : "";
+        console.log(`  ${status} #${r.issueNumber}: ${phases}${loopInfo}${prInfo}${duration}`);
+    }
+    console.log("");
+    if (logPath) {
+        console.log(colors.muted(`  Log: ${logPath}`));
+        console.log("");
+    }
+    if (mergedOptions.reflect && results.length > 0) {
+        const reflection = analyzeRun({
+            results,
+            issueInfoMap: result.issueInfoMap,
+            runLog: result.logWriter?.getRunLog() ?? null,
+            config: { phases: config.phases, qualityLoop: config.qualityLoop },
+        });
+        const reflectionOutput = formatReflection(reflection);
+        if (reflectionOutput) {
+            console.log(reflectionOutput);
+            console.log("");
+        }
+    }
+    if (results.length > 1 && passed > 0 && !config.dryRun) {
+        console.log(colors.muted("  Tip: Verify batch integration before merging:"));
+        console.log(colors.muted("     sequant merge --check"));
+        console.log("");
+    }
+    if (config.dryRun) {
+        console.log(colors.warning("  ℹ️  This was a dry run. Use without --dry-run to execute."));
+        console.log("");
+    }
+}

package/dist/src/commands/run.js

@@ -5,10 +5,9 @@ import { formatElapsedTime } from "../lib/phase-spinner.js";
 import { getSettings } from "../lib/settings.js";
 import { checkVersionCached, getVersionWarning } from "../lib/version-check.js";
 import { ui, colors } from "../lib/cli-ui.js";
-import { formatDuration } from "../lib/workflow/phase-executor.js";
 import { parseBatches } from "../lib/workflow/batch-executor.js";
 import { RunOrchestrator } from "../lib/workflow/run-orchestrator.js";
-import { analyzeRun, formatReflection } from "../lib/workflow/run-reflect.js";
+import { displayConfig, displaySummary } from "./run-display.js";
 // Re-export public API for backwards compatibility
 export * from "./run-compat.js";
 /** Parse CLI args → validate → delegate to RunOrchestrator.run() → display summary. */
@@ -51,7 +50,16 @@ export async function runCommand(issues, options) {
         batches = parseBatches(options.batch);
         console.log(chalk.gray(`  Batch mode: ${batches.map((b) => `[${b.join(", ")}]`).join(" → ")}`));
     }
-    console.log(chalk.gray(`  ${"Stack".padEnd(15)}${manifest.stack}`));
+    const init = {
+        options,
+        settings,
+        manifest: {
+            stack: manifest.stack,
+            packageManager: manifest.packageManager ?? "npm",
+        },
+    };
+    const resolved = RunOrchestrator.resolveConfig(init, issues, batches);
+    displayConfig(resolved);
     const onProgress = !options.quiet
         ? (issue, phase, event, extra) => {
             if (event === "start")
@@ -66,68 +74,8 @@ export async function runCommand(issues, options) {
                 console.log(`  ${colors.error("✖")} #${issue}  ${phase}`);
         }
         : undefined;
-    const result = await RunOrchestrator.run({
-        options,
-        settings,
-        manifest: {
-            stack: manifest.stack,
-            packageManager: manifest.packageManager ?? "npm",
-        },
-        onProgress,
-    }, issues, batches);
+    const result = await RunOrchestrator.run({ ...init, onProgress }, issues, batches);
     displaySummary(result);
     if (result.exitCode !== 0)
         process.exit(result.exitCode);
 }
-function displaySummary(result) {
-    const { results, logPath, config, mergedOptions } = result;
-    if (results.length === 0)
-        return;
-    const passed = results.filter((r) => r.success).length;
-    const failed = results.filter((r) => !r.success).length;
-    console.log("\n" + ui.divider());
-    console.log(colors.info("  Summary"));
-    console.log(ui.divider());
-    console.log(`\n  ${colors.success(`${passed} passed`)} ${colors.muted("·")} ${colors.error(`${failed} failed`)}`);
-    for (const r of results) {
-        const status = r.success
-            ? ui.statusIcon("success")
-            : ui.statusIcon("error");
-        const duration = r.durationSeconds
-            ? colors.muted(` (${formatDuration(r.durationSeconds)})`)
-            : "";
-        const phases = r.phaseResults
-            .map((p) => (p.success ? colors.success(p.phase) : colors.error(p.phase)))
-            .join(" → ");
-        const loopInfo = r.loopTriggered ? colors.warning(" [loop]") : "";
-        const prInfo = r.prUrl ? colors.muted(` → PR #${r.prNumber}`) : "";
-        console.log(`  ${status} #${r.issueNumber}: ${phases}${loopInfo}${prInfo}${duration}`);
-    }
-    console.log("");
-    if (logPath) {
-        console.log(colors.muted(`  Log: ${logPath}`));
-        console.log("");
-    }
-    if (mergedOptions.reflect && results.length > 0) {
-        const reflection = analyzeRun({
-            results,
-            issueInfoMap: result.issueInfoMap,
-            runLog: result.logWriter?.getRunLog() ?? null,
-            config: { phases: config.phases, qualityLoop: config.qualityLoop },
-        });
-        const reflectionOutput = formatReflection(reflection);
-        if (reflectionOutput) {
-            console.log(reflectionOutput);
-            console.log("");
-        }
-    }
-    if (results.length > 1 && passed > 0 && !config.dryRun) {
-        console.log(colors.muted("  Tip: Verify batch integration before merging:"));
-        console.log(colors.muted("     sequant merge --check"));
-        console.log("");
-    }
-    if (config.dryRun) {
-        console.log(colors.warning("  ℹ️  This was a dry run. Use without --dry-run to execute."));
-        console.log("");
-    }
-}

package/dist/src/commands/status.js

@@ -10,6 +10,7 @@ import { StateManager } from "../lib/workflow/state-manager.js";
 import { rebuildStateFromLogs, cleanupStaleEntries, } from "../lib/workflow/state-utils.js";
 import { reconcileState, getNextActionHint, formatRelativeTime, } from "../lib/workflow/reconcile.js";
 import { getSettingsWithWarnings } from "../lib/settings.js";
+import { getSkillVersions } from "../lib/skill-version.js";
 /**
  * Run reconciliation and display warnings.
  * Returns the reconcile result for use in display.
@@ -263,13 +264,26 @@ export async function statusCommand(options = {}) {
             console.log(chalk.yellow(`    ${w.message}`));
         }
     }
-    // Count skills
+    // Count skills and check versions
     const skillsDir = ".claude/skills";
     if (await fileExists(skillsDir)) {
         try {
             const skills = await readdir(skillsDir);
             const skillCount = skills.filter((s) => !s.startsWith(".")).length;
             console.log(chalk.gray(`Skills: ${skillCount}`));
+            // Show skill version info
+            const { getTemplatesDir } = await import("../lib/templates.js");
+            const { join } = await import("path");
+            const templateSkillsDir = join(getTemplatesDir(), "skills");
+            const skillVersions = await getSkillVersions(templateSkillsDir);
+            const outdated = skillVersions.filter((s) => s.updateAvailable);
+            if (outdated.length > 0) {
+                console.log(chalk.yellow(`\n  Skill updates available (${outdated.length}):`));
+                for (const s of outdated) {
+                    console.log(chalk.yellow(`    ${s.name}: v${s.installedVersion} → v${s.templateVersion}`));
+                }
+                console.log(chalk.gray("    Run `sequant init --upgrade-skills` to update."));
+            }
         }
         catch {
             // Ignore errors

package/dist/src/lib/skill-version.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Skill version utilities — reads version from SKILL.md YAML frontmatter
+ */
+export interface SkillVersionInfo {
+    name: string;
+    installedVersion: string | null;
+    templateVersion: string | null;
+    updateAvailable: boolean;
+}
+/**
+ * Parse YAML frontmatter from a SKILL.md file and extract the version field.
+ * Returns null if no version is found or file doesn't exist.
+ */
+export declare function parseSkillVersion(content: string): string | null;
+/**
+ * Get version info for all installed skills, comparing installed (.claude/skills/)
+ * with template versions (from the sequant package's templates/skills/).
+ */
+export declare function getSkillVersions(templateDir?: string): Promise<SkillVersionInfo[]>;

package/dist/src/lib/skill-version.js

@@ -0,0 +1,68 @@
+/**
+ * Skill version utilities — reads version from SKILL.md YAML frontmatter
+ */
+import { readdir } from "fs/promises";
+import { join } from "path";
+import { parse as parseYaml } from "yaml";
+import { readFile, fileExists } from "./fs.js";
+/**
+ * Parse YAML frontmatter from a SKILL.md file and extract the version field.
+ * Returns null if no version is found or file doesn't exist.
+ */
+export function parseSkillVersion(content) {
+    const match = content.match(/^---\n([\s\S]*?)\n---/);
+    if (!match)
+        return null;
+    try {
+        const frontmatter = parseYaml(match[1]);
+        return frontmatter?.version ?? frontmatter?.metadata?.version ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Read version from a single skill's SKILL.md file.
+ */
+async function readSkillVersion(skillDir) {
+    const skillPath = join(skillDir, "SKILL.md");
+    if (!(await fileExists(skillPath)))
+        return null;
+    const content = await readFile(skillPath);
+    return parseSkillVersion(content);
+}
+/**
+ * Get version info for all installed skills, comparing installed (.claude/skills/)
+ * with template versions (from the sequant package's templates/skills/).
+ */
+export async function getSkillVersions(templateDir) {
+    const installedDir = ".claude/skills";
+    const results = [];
+    if (!(await fileExists(installedDir)))
+        return results;
+    try {
+        const entries = await readdir(installedDir, { withFileTypes: true });
+        for (const entry of entries) {
+            if (!entry.isDirectory() || entry.name.startsWith("."))
+                continue;
+            const installedVersion = await readSkillVersion(join(installedDir, entry.name));
+            let templateVersion = null;
+            if (templateDir) {
+                templateVersion = await readSkillVersion(join(templateDir, entry.name));
+            }
+            const updateAvailable = installedVersion !== null &&
+                templateVersion !== null &&
+                installedVersion !== templateVersion;
+            results.push({
+                name: entry.name,
+                installedVersion,
+                templateVersion,
+                updateAvailable,
+            });
+        }
+    }
+    catch {
+        // Ignore errors reading skills directory
+    }
+    return results.sort((a, b) => a.name.localeCompare(b.name));
+}

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

@@ -1,6 +1,7 @@
 /**
  * Template management - copy and process templates
  */
+export declare function getTemplatesDir(): string;
 /**
  * Process template variables in content
  */

package/dist/src/lib/templates.js

@@ -11,7 +11,7 @@ import { getStackConfig, getStackNotes, getMultiStackNotes } from "./stacks.js";
 import { isNativeWindows } from "./system.js";
 import { getProjectName } from "./project-name.js";
 // Get the package templates directory
-function getTemplatesDir() {
+export function getTemplatesDir() {
     const __dirname = dirname(fileURLToPath(import.meta.url));
     // Compiled structure: dist/src/lib/templates.js
     // So we need ../../../templates to reach project root templates/

package/dist/src/lib/workflow/batch-executor.js

@@ -747,7 +747,7 @@ export async function runIssueWithLogging(ctx) {
     }
     // Create checkpoint commit in chain mode after QA passes
     if (success && chainMode && worktreePath) {
-        createCheckpointCommit(worktreePath, issueNumber, config.verbose);
+        createCheckpointCommit(worktreePath, issueNumber, config.verbose, baseBranch);
     }
     // Rebase onto the base branch before PR creation (unless --no-rebase)
     // This ensures the branch is up-to-date and prevents lockfile drift

package/dist/src/lib/workflow/phase-executor.d.ts

@@ -11,6 +11,7 @@ import { ShutdownManager } from "../shutdown.js";
 import { PhaseSpinner } from "../phase-spinner.js";
 import { Phase, ExecutionConfig, PhaseResult, QaVerdict } from "./types.js";
 import type { QaSummary } from "./run-log-schema.js";
+import type { AgentPhaseResult } from "./drivers/index.js";
 /**
  * Spec-specific retry configuration.
  * Spec failures have a higher failure rate (~8.6%) than other phases due to
@@ -40,6 +41,36 @@ export declare function parseQaSummary(output: string): QaSummary | null;
  * Format duration in human-readable format
  */
 export declare function formatDuration(seconds: number): string;
+/**
+ * Check whether the exec phase produced any changes in the worktree.
+ * Returns true if HEAD has commits unique to it relative to origin/main
+ * OR uncommitted work is present.
+ *
+ * Uses `git rev-list --count origin/main..HEAD` (commits reachable from HEAD
+ * but not origin/main) instead of `git diff origin/main..HEAD`, because the
+ * two-dot diff also fires in reverse when origin/main has advanced past HEAD
+ * — on stale branches that would falsely report "has commits" even when the
+ * exec phase produced nothing, reintroducing the bug #534 is fixing.
+ *
+ * Fails open (returns true) on git errors — a missing origin ref is better
+ * diagnosed as a real zero-diff run than as a false phase failure.
+ *
+ * @internal Exported for testing only.
+ */
+export declare function hasExecChanges(cwd: string): boolean;
+/**
+ * Map a successful AgentPhaseResult to a PhaseResult, applying phase-specific
+ * guards that catch agent sessions which returned success without producing
+ * usable work (#534):
+ *
+ * - `qa`: fails when no parseable verdict is found (empty or malformed output).
+ * - `exec`: fails when no commits and no uncommitted changes exist.
+ *
+ * @internal Exported for testing only.
+ */
+export declare function mapAgentSuccessToPhaseResult(phase: Phase, agentResult: AgentPhaseResult, durationSeconds: number, cwd: string): PhaseResult & {
+    sessionId?: string;
+};
 /**
  * Get the prompt for a phase with the issue number substituted.
  * Selects self-contained prompts for non-Claude agents.