sequant 2.1.1 → 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.1",
+  "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,13 +2,16 @@
  * 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";
 import { createManifest } from "../lib/manifest.js";
 import { saveConfig } from "../lib/config.js";
-import { createDefaultSettings } from "../lib/settings.js";
+import { createDefaultSettings, generateSettingsReference, } from "../lib/settings.js";
 import { detectAndSaveConventions } from "../lib/conventions-detector.js";
 import { fileExists, ensureDir, readFile, writeFile } from "../lib/fs.js";
 import { generateAgentsMd, writeAgentsMd } from "../lib/agents-md.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"));
@@ -348,11 +356,12 @@ export async function initCommand(options) {
         await saveStackConfig(stackConfig);
         console.log(chalk.blue("📋 Saved multi-stack configuration"));
     }
-    // Create default settings
+    // Create default settings + reference doc (AC-4)
     const settingsSpinner = ui.spinner("Creating default settings...");
     settingsSpinner.start();
     await createDefaultSettings();
-    settingsSpinner.succeed("Created default settings");
+    await writeFile(".sequant/settings.reference.md", generateSettingsReference());
+    settingsSpinner.succeed("Created default settings + reference doc");
     // Detect codebase conventions
     const conventionsSpinner = ui.spinner("Detecting codebase conventions...");
     conventionsSpinner.start();
@@ -502,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-compat.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Backward-compatible re-exports from run.ts.
+ *
+ * Consumers that import workflow utilities from "commands/run" continue to work.
+ * New code should import directly from the source modules.
+ */
+export { normalizeCommanderOptions } from "../lib/workflow/config-resolver.js";
+export { parseQaVerdict, formatDuration, executePhaseWithRetry, } from "../lib/workflow/phase-executor.js";
+export { detectDefaultBranch, checkWorktreeFreshness, removeStaleWorktree, listWorktrees, getWorktreeChangedFiles, getWorktreeDiffStats, readCacheMetrics, filterResumedPhases, ensureWorktree, createCheckpointCommit, reinstallIfLockfileChanged, rebaseBeforePR, createPR, } from "../lib/workflow/worktree-manager.js";
+export type { WorktreeInfo, RebaseResult, PRCreationResult, } from "../lib/workflow/worktree-manager.js";
+export { detectPhasesFromLabels, parseRecommendedWorkflow, determinePhasesForIssue, } from "../lib/workflow/phase-mapper.js";
+export { getIssueInfo, sortByDependencies, parseBatches, getEnvConfig, executeBatch, runIssueWithLogging, } from "../lib/workflow/batch-executor.js";
+export type { RunOptions } from "../lib/workflow/types.js";
+export { logNonFatalWarning } from "../lib/workflow/run-orchestrator.js";

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

@@ -0,0 +1,12 @@
+/**
+ * Backward-compatible re-exports from run.ts.
+ *
+ * Consumers that import workflow utilities from "commands/run" continue to work.
+ * New code should import directly from the source modules.
+ */
+export { normalizeCommanderOptions } from "../lib/workflow/config-resolver.js";
+export { parseQaVerdict, formatDuration, executePhaseWithRetry, } from "../lib/workflow/phase-executor.js";
+export { detectDefaultBranch, checkWorktreeFreshness, removeStaleWorktree, listWorktrees, getWorktreeChangedFiles, getWorktreeDiffStats, readCacheMetrics, filterResumedPhases, ensureWorktree, createCheckpointCommit, reinstallIfLockfileChanged, rebaseBeforePR, createPR, } from "../lib/workflow/worktree-manager.js";
+export { detectPhasesFromLabels, parseRecommendedWorkflow, determinePhasesForIssue, } from "../lib/workflow/phase-mapper.js";
+export { getIssueInfo, sortByDependencies, parseBatches, getEnvConfig, executeBatch, runIssueWithLogging, } from "../lib/workflow/batch-executor.js";
+export { logNonFatalWarning } from "../lib/workflow/run-orchestrator.js";

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.d.ts

@@ -1,27 +1,5 @@
-/**
- * sequant run - Execute workflow for GitHub issues
- *
- * Orchestrator module that composes focused workflow modules:
- * - worktree-manager: Worktree lifecycle (ensure, list, cleanup, changed files)
- * - phase-executor: Phase execution with retry and failure handling
- * - phase-mapper: Label-to-phase detection and workflow parsing
- * - batch-executor: Batch execution, dependency sorting, issue logging
- */
-/** @internal Log a non-fatal warning: one-line summary always, detail in verbose. */
-export declare function logNonFatalWarning(message: string, error: unknown, verbose: boolean): void;
-import type { RunOptions } from "../lib/workflow/batch-executor.js";
-export { parseQaVerdict, formatDuration, executePhaseWithRetry, } from "../lib/workflow/phase-executor.js";
-export { detectDefaultBranch, checkWorktreeFreshness, removeStaleWorktree, listWorktrees, getWorktreeChangedFiles, getWorktreeDiffStats, readCacheMetrics, filterResumedPhases, ensureWorktree, createCheckpointCommit, reinstallIfLockfileChanged, rebaseBeforePR, createPR, } from "../lib/workflow/worktree-manager.js";
-export type { WorktreeInfo, RebaseResult, PRCreationResult, } from "../lib/workflow/worktree-manager.js";
-export { detectPhasesFromLabels, parseRecommendedWorkflow, determinePhasesForIssue, } from "../lib/workflow/phase-mapper.js";
-export { getIssueInfo, sortByDependencies, parseBatches, getEnvConfig, executeBatch, runIssueWithLogging, } from "../lib/workflow/batch-executor.js";
-export type { RunOptions } from "../lib/workflow/batch-executor.js";
-/**
- * Normalize Commander.js --no-X flags into typed RunOptions fields.
- * Replaces the `as any` cast (#402 AC-4).
- */
-export declare function normalizeCommanderOptions(options: RunOptions): RunOptions;
-/**
- * Main run command
- */
+/** sequant run — Thin CLI adapter that delegates to RunOrchestrator. */
+import type { RunOptions } from "../lib/workflow/types.js";
+export * from "./run-compat.js";
+/** Parse CLI args → validate → delegate to RunOrchestrator.run() → display summary. */
 export declare function runCommand(issues: string[], options: RunOptions): Promise<void>;