sequant 1.5.2 → 1.5.4

package/dist/bin/cli.js

@@ -89,6 +89,7 @@ program
     .option("--smart-tests", "Enable smart test detection (default)")
     .option("--no-smart-tests", "Disable smart test detection")
     .option("--testgen", "Run testgen phase after spec")
+    .option("--quiet", "Suppress version warnings and non-essential output")
     .action(runCommand);
 program
     .command("logs")

package/dist/src/commands/doctor.js

@@ -5,9 +5,39 @@ import chalk from "chalk";
 import { fileExists, isExecutable } from "../lib/fs.js";
 import { getManifest } from "../lib/manifest.js";
 import { commandExists, isGhAuthenticated, isNativeWindows, isWSL, checkOptionalMcpServers, OPTIONAL_MCP_SERVERS, } from "../lib/system.js";
+import { checkVersionThorough, getVersionWarning, } from "../lib/version-check.js";
 export async function doctorCommand() {
     console.log(chalk.blue("\n🔍 Running health checks...\n"));
     const checks = [];
+    // Check 0: Version freshness
+    const versionResult = await checkVersionThorough();
+    if (versionResult.latestVersion) {
+        if (versionResult.isOutdated) {
+            checks.push({
+                name: "Version",
+                status: "warn",
+                message: `Outdated: ${versionResult.currentVersion} → ${versionResult.latestVersion} available`,
+            });
+            // Show remediation steps
+            console.log(chalk.yellow(`  ⚠️  ${getVersionWarning(versionResult.currentVersion, versionResult.latestVersion)}`));
+            console.log("");
+        }
+        else {
+            checks.push({
+                name: "Version",
+                status: "pass",
+                message: `Up to date (${versionResult.currentVersion})`,
+            });
+        }
+    }
+    else {
+        // Could not fetch version - skip this check silently (graceful degradation)
+        checks.push({
+            name: "Version",
+            status: "pass",
+            message: `${versionResult.currentVersion} (could not verify latest)`,
+        });
+    }
     // Check 1: Manifest exists
     const manifest = await getManifest();
     if (manifest) {

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

@@ -56,6 +56,8 @@ interface RunOptions {
     worktreeIsolation?: boolean;
     /** Reuse existing worktrees instead of creating new ones */
     reuseWorktrees?: boolean;
+    /** Suppress version warnings and non-essential output */
+    quiet?: boolean;
 }
 /**
  * Main run command

package/dist/src/commands/run.js

@@ -15,6 +15,7 @@ import { PM_CONFIG } from "../lib/stacks.js";
 import { LogWriter, createPhaseLogFromTiming, } from "../lib/workflow/log-writer.js";
 import { DEFAULT_PHASES, DEFAULT_CONFIG, } from "../lib/workflow/types.js";
 import { ShutdownManager } from "../lib/shutdown.js";
+import { checkVersionCached, getVersionWarning } from "../lib/version-check.js";
 /**
  * Slugify a title for branch naming
  */
@@ -726,6 +727,19 @@ function parseBatches(batchArgs) {
  */
 export async function runCommand(issues, options) {
     console.log(chalk.blue("\n🌐 Sequant Workflow Execution\n"));
+    // Version freshness check (cached, non-blocking, respects --quiet)
+    if (!options.quiet) {
+        try {
+            const versionResult = await checkVersionCached();
+            if (versionResult.isOutdated && versionResult.latestVersion) {
+                console.log(chalk.yellow(`  ⚠️  ${getVersionWarning(versionResult.currentVersion, versionResult.latestVersion)}`));
+                console.log("");
+            }
+        }
+        catch {
+            // Silent failure - version check is non-critical
+        }
+    }
     // Check if initialized
     const manifest = await getManifest();
     if (!manifest) {

package/dist/src/commands/status.js

@@ -2,13 +2,13 @@
  * sequant status - Show version and configuration
  */
 import chalk from "chalk";
-import { getManifest } from "../lib/manifest.js";
+import { getManifest, getPackageVersion } from "../lib/manifest.js";
 import { fileExists } from "../lib/fs.js";
 import { readdir } from "fs/promises";
 export async function statusCommand() {
     console.log(chalk.bold("\n📊 Sequant Status\n"));
     // Package version
-    console.log(chalk.gray("Package version: 0.1.0"));
+    console.log(chalk.gray(`Package version: ${getPackageVersion()}`));
     // Check initialization
     const manifest = await getManifest();
     if (!manifest) {

package/dist/src/commands/update.js

@@ -5,7 +5,7 @@ import chalk from "chalk";
 import { diffLines } from "diff";
 import inquirer from "inquirer";
 import { spawnSync } from "child_process";
-import { getManifest, updateManifest } from "../lib/manifest.js";
+import { getManifest, updateManifest, getPackageVersion, } from "../lib/manifest.js";
 import { getTemplateContent, listTemplateFiles, processTemplate, } from "../lib/templates.js";
 import { getConfig, saveConfig } from "../lib/config.js";
 import { getStackConfig, PM_CONFIG, getPackageManagerCommands, } from "../lib/stacks.js";
@@ -18,8 +18,19 @@ export async function updateCommand(options) {
         console.log(chalk.red("❌ Sequant is not initialized. Run `sequant init` first."));
         return;
     }
+    const packageVersion = getPackageVersion();
     console.log(chalk.gray(`Current version: ${manifest.version}`));
-    console.log(chalk.gray(`Stack: ${manifest.stack}\n`));
+    console.log(chalk.gray(`Stack: ${manifest.stack}`));
+    console.log(chalk.gray(`CLI version: ${packageVersion}\n`));
+    // Warn if running an older CLI version than what's installed
+    const [mMajor, mMinor, mPatch] = manifest.version.split(".").map(Number);
+    const [pMajor, pMinor, pPatch] = packageVersion.split(".").map(Number);
+    const manifestNum = mMajor * 10000 + mMinor * 100 + mPatch;
+    const packageNum = pMajor * 10000 + pMinor * 100 + pPatch;
+    if (packageNum < manifestNum) {
+        console.log(chalk.yellow(`⚠️  Warning: You're running an older CLI version (${packageVersion}) than installed (${manifest.version}).`));
+        console.log(chalk.yellow(`   Run with: npx sequant@latest update\n`));
+    }
     // Get config with tokens (or migrate legacy installs)
     let config = await getConfig();
     let tokens;

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

@@ -2,6 +2,7 @@
  * Manifest management for tracking installed version
  */
 import type { PackageManager } from "./stacks.js";
+export declare function getPackageVersion(): string;
 export interface Manifest {
     version: string;
     stack: string;

package/dist/src/lib/manifest.js

@@ -29,6 +29,26 @@ function findPackageJson() {
 }
 const pkg = JSON.parse(findPackageJson());
 const PACKAGE_VERSION = pkg.version;
+export function getPackageVersion() {
+    return PACKAGE_VERSION;
+}
+/**
+ * Compare two semver versions.
+ * Returns: 1 if a > b, -1 if a < b, 0 if equal
+ */
+function compareVersions(a, b) {
+    const partsA = a.split(".").map(Number);
+    const partsB = b.split(".").map(Number);
+    for (let i = 0; i < 3; i++) {
+        const numA = partsA[i] || 0;
+        const numB = partsB[i] || 0;
+        if (numA > numB)
+            return 1;
+        if (numA < numB)
+            return -1;
+    }
+    return 0;
+}
 export async function getManifest() {
     if (!(await fileExists(MANIFEST_PATH))) {
         return null;
@@ -56,7 +76,11 @@ export async function updateManifest() {
     if (!manifest) {
         return;
     }
-    manifest.version = PACKAGE_VERSION;
+    // Only update version if package version is >= manifest version
+    // This prevents older cached CLI versions from downgrading the manifest
+    if (compareVersions(PACKAGE_VERSION, manifest.version) >= 0) {
+        manifest.version = PACKAGE_VERSION;
+    }
     manifest.updatedAt = new Date().toISOString();
     await writeFile(MANIFEST_PATH, JSON.stringify(manifest, null, 2));
 }

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

@@ -0,0 +1,67 @@
+/**
+ * Version freshness checks for sequant
+ *
+ * Provides utilities to check if the current version is up to date
+ * with the latest version on npm.
+ */
+export interface VersionCache {
+    latestVersion: string;
+    checkedAt: string;
+}
+export interface VersionCheckResult {
+    currentVersion: string;
+    latestVersion: string | null;
+    isOutdated: boolean;
+    error?: string;
+}
+/**
+ * Get the global cache directory path
+ */
+export declare function getCacheDir(): string;
+/**
+ * Get the version cache file path
+ */
+export declare function getCachePath(): string;
+/**
+ * Get the current version from package.json
+ */
+export declare function getCurrentVersion(): string;
+/**
+ * Read the version cache
+ */
+export declare function readCache(): VersionCache | null;
+/**
+ * Write to the version cache
+ */
+export declare function writeCache(latestVersion: string): void;
+/**
+ * Check if the cache is still fresh (within 24 hours)
+ */
+export declare function isCacheFresh(cache: VersionCache): boolean;
+/**
+ * Fetch the latest version from npm registry with timeout
+ */
+export declare function fetchLatestVersion(): Promise<string | null>;
+/**
+ * Compare two semantic versions
+ * Returns: -1 if a < b, 0 if a == b, 1 if a > b
+ */
+export declare function compareVersions(a: string, b: string): number;
+/**
+ * Check if the current version is outdated
+ */
+export declare function isOutdated(currentVersion: string, latestVersion: string): boolean;
+/**
+ * Get the version warning message
+ */
+export declare function getVersionWarning(currentVersion: string, latestVersion: string): string;
+/**
+ * Check version freshness (thorough - for doctor command)
+ * Always fetches from npm registry
+ */
+export declare function checkVersionThorough(): Promise<VersionCheckResult>;
+/**
+ * Check version freshness (cached - for run command)
+ * Uses cache if available and fresh, otherwise fetches (non-blocking)
+ */
+export declare function checkVersionCached(): Promise<VersionCheckResult>;

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

@@ -0,0 +1,215 @@
+/**
+ * Version freshness checks for sequant
+ *
+ * Provides utilities to check if the current version is up to date
+ * with the latest version on npm.
+ */
+import fs from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const PACKAGE_NAME = "sequant";
+const NPM_REGISTRY_URL = `https://registry.npmjs.org/${PACKAGE_NAME}/latest`;
+const VERSION_CHECK_TIMEOUT = 3000; // 3 seconds
+const CACHE_EXPIRY_MS = 24 * 60 * 60 * 1000; // 24 hours
+/**
+ * Get the global cache directory path
+ */
+export function getCacheDir() {
+    const home = process.env.HOME || process.env.USERPROFILE || "";
+    return path.join(home, ".cache", "sequant");
+}
+/**
+ * Get the version cache file path
+ */
+export function getCachePath() {
+    return path.join(getCacheDir(), "version-check.json");
+}
+/**
+ * Get the current version from package.json
+ */
+export function getCurrentVersion() {
+    try {
+        // Navigate from dist/lib to package.json
+        const packagePath = path.resolve(__dirname, "..", "..", "package.json");
+        const content = fs.readFileSync(packagePath, "utf8");
+        const pkg = JSON.parse(content);
+        return pkg.version || "0.0.0";
+    }
+    catch {
+        return "0.0.0";
+    }
+}
+/**
+ * Read the version cache
+ */
+export function readCache() {
+    try {
+        const cachePath = getCachePath();
+        if (!fs.existsSync(cachePath)) {
+            return null;
+        }
+        const content = fs.readFileSync(cachePath, "utf8");
+        return JSON.parse(content);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Write to the version cache
+ */
+export function writeCache(latestVersion) {
+    try {
+        const cacheDir = getCacheDir();
+        if (!fs.existsSync(cacheDir)) {
+            fs.mkdirSync(cacheDir, { recursive: true });
+        }
+        const cache = {
+            latestVersion,
+            checkedAt: new Date().toISOString(),
+        };
+        fs.writeFileSync(getCachePath(), JSON.stringify(cache, null, 2));
+    }
+    catch {
+        // Silent failure - caching is optional
+    }
+}
+/**
+ * Check if the cache is still fresh (within 24 hours)
+ */
+export function isCacheFresh(cache) {
+    try {
+        const checkedAt = new Date(cache.checkedAt).getTime();
+        const now = Date.now();
+        return now - checkedAt < CACHE_EXPIRY_MS;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Fetch the latest version from npm registry with timeout
+ */
+export async function fetchLatestVersion() {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), VERSION_CHECK_TIMEOUT);
+    try {
+        const response = await fetch(NPM_REGISTRY_URL, {
+            signal: controller.signal,
+            headers: {
+                Accept: "application/json",
+            },
+        });
+        clearTimeout(timeoutId);
+        if (!response.ok) {
+            return null;
+        }
+        const data = (await response.json());
+        return data.version || null;
+    }
+    catch {
+        clearTimeout(timeoutId);
+        return null;
+    }
+}
+/**
+ * Compare two semantic versions
+ * Returns: -1 if a < b, 0 if a == b, 1 if a > b
+ */
+export function compareVersions(a, b) {
+    const parseVersion = (v) => {
+        return v
+            .replace(/^v/, "")
+            .split(".")
+            .map((n) => parseInt(n, 10) || 0);
+    };
+    const aParts = parseVersion(a);
+    const bParts = parseVersion(b);
+    for (let i = 0; i < Math.max(aParts.length, bParts.length); i++) {
+        const aVal = aParts[i] || 0;
+        const bVal = bParts[i] || 0;
+        if (aVal < bVal)
+            return -1;
+        if (aVal > bVal)
+            return 1;
+    }
+    return 0;
+}
+/**
+ * Check if the current version is outdated
+ */
+export function isOutdated(currentVersion, latestVersion) {
+    return compareVersions(currentVersion, latestVersion) < 0;
+}
+/**
+ * Get the version warning message
+ */
+export function getVersionWarning(currentVersion, latestVersion) {
+    return `sequant ${latestVersion} is available (you have ${currentVersion})
+   Run: npx sequant@latest or npm update sequant`;
+}
+/**
+ * Check version freshness (thorough - for doctor command)
+ * Always fetches from npm registry
+ */
+export async function checkVersionThorough() {
+    const currentVersion = getCurrentVersion();
+    const latestVersion = await fetchLatestVersion();
+    if (!latestVersion) {
+        return {
+            currentVersion,
+            latestVersion: null,
+            isOutdated: false,
+            error: "Could not fetch latest version",
+        };
+    }
+    // Update cache with fresh data
+    writeCache(latestVersion);
+    return {
+        currentVersion,
+        latestVersion,
+        isOutdated: isOutdated(currentVersion, latestVersion),
+    };
+}
+/**
+ * Check version freshness (cached - for run command)
+ * Uses cache if available and fresh, otherwise fetches (non-blocking)
+ */
+export async function checkVersionCached() {
+    const currentVersion = getCurrentVersion();
+    // Check cache first
+    const cache = readCache();
+    if (cache && isCacheFresh(cache)) {
+        return {
+            currentVersion,
+            latestVersion: cache.latestVersion,
+            isOutdated: isOutdated(currentVersion, cache.latestVersion),
+        };
+    }
+    // Fetch new version (with timeout)
+    const latestVersion = await fetchLatestVersion();
+    if (!latestVersion) {
+        // Use stale cache if available, otherwise silent failure
+        if (cache) {
+            return {
+                currentVersion,
+                latestVersion: cache.latestVersion,
+                isOutdated: isOutdated(currentVersion, cache.latestVersion),
+            };
+        }
+        return {
+            currentVersion,
+            latestVersion: null,
+            isOutdated: false,
+        };
+    }
+    // Update cache
+    writeCache(latestVersion);
+    return {
+        currentVersion,
+        latestVersion,
+        isOutdated: isOutdated(currentVersion, latestVersion),
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sequant",
-  "version": "1.5.2",
+  "version": "1.5.4",
   "description": "Quantize your development workflow - Sequential AI phases with quality gates",
   "type": "module",
   "bin": {

package/templates/skills/qa/SKILL.md

@@ -114,22 +114,17 @@ If no feature worktree exists (work was done directly on main):
 
 4. **Run quality checks** on the current branch instead of comparing to a worktree.
 
-### Parallel Quality Checks (Multi-Agent)
+### Quality Checks (Multi-Agent) — REQUIRED
 
-Before detailed manual review, run quality checks in parallel using specialized agents.
+**You MUST spawn sub-agents for quality checks.** Do NOT run these checks inline with bash commands. Sub-agents provide parallel execution, better context isolation, and consistent reporting.
 
-**Spawn agents in a SINGLE message:**
+**Spawn ALL THREE agents in a SINGLE message:**
 
-```
-Task(subagent_type="quality-checker", model="haiku",
-     prompt="Run type safety and deleted tests checks. Report: type issues count, deleted tests, verdict.")
+1. `Task(subagent_type="quality-checker", model="haiku", prompt="Run type safety and deleted tests checks on the current branch vs main. Report: type issues count, deleted tests, verdict.")`
 
-Task(subagent_type="quality-checker", model="haiku",
-     prompt="Run scope and size checks. Report: files count, diff size, size assessment.")
+2. `Task(subagent_type="quality-checker", model="haiku", prompt="Run scope and size checks on the current branch vs main. Report: files count, diff size, size assessment.")`
 
-Task(subagent_type="quality-checker", model="haiku",
-     prompt="Run security scan on changed files. Report: critical/warning/info counts, verdict.")
-```
+3. `Task(subagent_type="quality-checker", model="haiku", prompt="Run security scan on changed files in current branch vs main. Report: critical/warning/info counts, verdict.")`
 
 **Add RLS check if admin files modified:**
 ```bash
@@ -191,9 +186,9 @@ Provide an overall verdict:
 
 See [quality-gates.md](references/quality-gates.md) for detailed verdict criteria.
 
-## Automated Quality Checks
+## Automated Quality Checks (Reference)
 
-Run these before detailed review (or use parallel agents above):
+**Note:** These commands are what the sub-agents execute internally. You do NOT run these directly — the sub-agents spawned above handle this. This section is reference documentation only.
 
 ```bash
 # Type safety

package/templates/skills/spec/SKILL.md

@@ -45,22 +45,17 @@ When called like `/spec <freeform description>`:
 
 **Planning Phase:** No worktree needed. Planning happens in the main repository directory. The worktree will be created during the execution phase (`/exec`).
 
-### Parallel Context Gathering
+### Parallel Context Gathering — REQUIRED
 
-Before planning, gather context using parallel agents:
+**You MUST spawn sub-agents for context gathering.** Do NOT explore the codebase inline with Glob/Grep commands. Sub-agents provide parallel execution, better context isolation, and consistent reporting.
 
-```
-Task(subagent_type="pattern-scout", model="haiku",
-     prompt="Find similar features. Check components/admin/, lib/queries/, docs/patterns/. Report: file paths, patterns, recommendations.")
+**Spawn ALL THREE agents in a SINGLE message:**
 
-Task(subagent_type="Explore", model="haiku",
-     prompt="Explore [CODEBASE AREA]. Find: main components, data flow, key files. Report structure.")
+1. `Task(subagent_type="pattern-scout", model="haiku", prompt="Find similar features for [FEATURE]. Check components/admin/, lib/queries/, docs/patterns/. Report: file paths, patterns, recommendations.")`
 
-Task(subagent_type="schema-inspector", model="haiku",
-     prompt="Inspect database for [FEATURE]. Check: table schema, RLS policies, existing queries. Report findings.")
-```
+2. `Task(subagent_type="Explore", model="haiku", prompt="Explore [CODEBASE AREA] for [FEATURE]. Find: main components, data flow, key files. Report structure.")`
 
-**Important:** Spawn all agents in a SINGLE message for parallel execution.
+3. `Task(subagent_type="schema-inspector", model="haiku", prompt="Inspect database for [FEATURE]. Check: table schema, RLS policies, existing queries. Report findings.")`
 
 ### In-Flight Work Analysis (Conflict Detection)