sequant 2.6.0 → 2.6.2

package/.claude-plugin/marketplace.json

@@ -8,7 +8,7 @@
     {
       "name": "sequant",
       "description": "AI coding agent orchestrator for Claude Code — resolve GitHub issues end-to-end with isolated git worktrees, quality gates, and an MCP server. Includes 17 skills, workflow MCP tools, and pre/post-tool hooks.",
-      "version": "2.6.0",
+      "version": "2.6.2",
       "author": {
         "name": "sequant-io",
         "email": "hello@sequant.io"

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "sequant",
   "description": "AI coding agent orchestrator for Claude Code — resolve GitHub issues end-to-end with isolated git worktrees and quality gates, through spec → exec → qa phases.",
-  "version": "2.6.0",
+  "version": "2.6.2",
   "author": {
     "name": "sequant-io",
     "email": "hello@sequant.io"

package/README.md

@@ -16,6 +16,11 @@ AI coding agents write code well, but leave you to run the workflow around it
 
 See the [CHANGELOG](CHANGELOG.md) for release notes, or the [migration guide](CHANGELOG.md#migration-from-v1x) if upgrading from v1.x.
 
+### What's new in 2.6
+
+- **Boxed Ink TUI is the default for `sequant run`** — on a TTY, `run` now renders the boxed dashboard by default (matching `sequant ready`). Opt out with `--no-tui` (line renderer) or `-s`/`--quiet` (heartbeat-only); non-TTY output auto-degrades.
+- **Flag change:** `--quiet` moved from `-q` to **`-s`** (silent). `-q` is now an alias for `-Q, --quality-loop`, so `sequant run … -q` enables the quality loop as intended. (`--experimental-tui` is kept as a hidden no-op alias.)
+
 ### What's new in 2.5
 
 - **`sequant ready <issue>`** — a post-resolve A+ QA gate that drives a resolved issue through a full-weight `qa → loop → qa` pass and **stops at the human merge gate — it never merges**.

package/dist/bin/cli.js

@@ -44,7 +44,7 @@ import { logsCommand } from "../src/commands/logs.js";
 import { statsCommand } from "../src/commands/stats.js";
 import { dashboardCommand } from "../src/commands/dashboard.js";
 import { stateInitCommand, stateRebuildCommand, stateCleanCommand, } from "../src/commands/state.js";
-import { syncCommand, areSkillsOutdated } from "../src/commands/sync.js";
+import { syncCommand, areSkillsOutdated, checkAndWarnSkillsOutdated, } from "../src/commands/sync.js";
 import { mergeCommand } from "../src/commands/merge.js";
 import { readyCommand, } from "../src/commands/ready.js";
 import { conventionsCommand } from "../src/commands/conventions.js";
@@ -128,6 +128,7 @@ program
     .description("Update templates from the Sequant package")
     .option("-d, --dry-run", "Show what would be updated without making changes")
     .option("-f, --force", "Overwrite local modifications")
+    .option("-y, --yes", "Apply updates without prompting (for CI/non-interactive shells)")
     .action(updateCommand);
 program
     .command("sync")
@@ -399,14 +400,36 @@ locksCmd
 // Projects that manage skills manually (no marker) are not affected.
 program.hook("preAction", async (thisCommand) => {
     const cmd = thisCommand.name();
-    if (cmd === "init" || cmd === "sync")
+    // `update` is excluded alongside `init`/`sync`: it is itself the command that
+    // resolves drift, so the warn-only "run sync/update" pre-flight would be a
+    // circular nag right before it does exactly that.
+    if (cmd === "init" || cmd === "sync" || cmd === "update")
         return;
     const manifest = await getManifest();
     if (!manifest)
         return;
-    const { outdated, currentVersion } = await areSkillsOutdated();
-    if (outdated && currentVersion !== null) {
+    // `cache: true` opts the per-command pre-flight into the stat-only drift
+    // fingerprint cache: the full template scan runs only when something that
+    // affects drift changed, keeping latency off the hot path (AC-5).
+    const status = await areSkillsOutdated({ cache: true });
+    const { outdated, currentVersion, contentDrift } = status;
+    // No version marker → the project manages skills manually; stay silent and
+    // do nothing (unchanged behavior — see the header comment above the hook).
+    if (currentVersion === null)
+        return;
+    if (outdated) {
+        // Version-marker mismatch → stale install: auto-sync (copy) as before.
         await syncCommand({ quiet: true });
+        return;
+    }
+    // Version-current but bundled content drifted in place (#708/#713). AC-3
+    // decision: auto-sync (copy) stays gated on version bumps ONLY — we do NOT
+    // copy here, because that would clobber in-place customizations (#711).
+    // Content-only drift is surfaced as a non-destructive, warn-only signal,
+    // leaving the fix to the user (`sequant sync`/`update`). The helper never
+    // touches process.exitCode, so the command still exits normally.
+    if (contentDrift > 0) {
+        await checkAndWarnSkillsOutdated(status);
     }
 });
 // Parse and execute

package/dist/marketplace/external_plugins/sequant/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "sequant",
   "description": "AI coding agent orchestrator for Claude Code — resolve GitHub issues end-to-end with isolated git worktrees and quality gates, through spec → exec → qa phases.",
-  "version": "2.6.0",
+  "version": "2.6.2",
   "author": {
     "name": "sequant-io",
     "email": "hello@sequant.io"

package/dist/marketplace/external_plugins/sequant/skills/assess/SKILL.md

@@ -13,6 +13,9 @@ allowed-tools:
   - Bash(gh *)
 ---
 
+<!-- sequant:local-override -->
+> **Local overrides (read this first).** Before following any instruction below, check whether `.claude/.local/skills/assess/overrides.md` exists. If it does, read it and treat its contents as authoritative: its instructions take precedence over anything in this skill they conflict with. This is the supported way to tailor `/assess` without forking it — `overrides.md` lives under `.claude/.local/`, which `sequant update` and `sync` never overwrite.
+
 # Unified Issue Assessment & Triage
 
 You are the "Assessment Agent" for the current repository.

package/dist/marketplace/external_plugins/sequant/skills/clean/SKILL.md

@@ -27,6 +27,9 @@ allowed-tools:
   - Grep
 ---
 
+<!-- sequant:local-override -->
+> **Local overrides (read this first).** Before following any instruction below, check whether `.claude/.local/skills/clean/overrides.md` exists. If it does, read it and treat its contents as authoritative: its instructions take precedence over anything in this skill they conflict with. This is the supported way to tailor `/clean` without forking it — `overrides.md` lives under `.claude/.local/`, which `sequant update` and `sync` never overwrite.
+
 # Repository Cleanup Command
 
 Comprehensive, safe repository cleanup that archives stale files, removes artifacts, and commits changes.

package/dist/marketplace/external_plugins/sequant/skills/docs/SKILL.md

@@ -18,6 +18,9 @@ allowed-tools:
   - Bash(gh pr diff:*)
 ---
 
+<!-- sequant:local-override -->
+> **Local overrides (read this first).** Before following any instruction below, check whether `.claude/.local/skills/docs/overrides.md` exists. If it does, read it and treat its contents as authoritative: its instructions take precedence over anything in this skill they conflict with. This is the supported way to tailor `/docs` without forking it — `overrides.md` lives under `.claude/.local/`, which `sequant update` and `sync` never overwrite.
+
 # Documentation Generator
 
 You are the Phase 4 "Documentation Agent" for the current repository.

package/dist/marketplace/external_plugins/sequant/skills/exec/SKILL.md

@@ -43,6 +43,9 @@ allowed-tools:
   - TodoWrite
 ---
 
+<!-- sequant:local-override -->
+> **Local overrides (read this first).** Before following any instruction below, check whether `.claude/.local/skills/exec/overrides.md` exists. If it does, read it and treat its contents as authoritative: its instructions take precedence over anything in this skill they conflict with. This is the supported way to tailor `/exec` without forking it — `overrides.md` lives under `.claude/.local/`, which `sequant update` and `sync` never overwrite.
+
 # Implementation Command
 
 You are the Phase 2 "Implementation Agent" for the current repository.

package/dist/marketplace/external_plugins/sequant/skills/fullsolve/SKILL.md

@@ -39,6 +39,9 @@ allowed-tools:
   - Bash(./scripts/list-worktrees.sh:*)
 ---
 
+<!-- sequant:local-override -->
+> **Local overrides (read this first).** Before following any instruction below, check whether `.claude/.local/skills/fullsolve/overrides.md` exists. If it does, read it and treat its contents as authoritative: its instructions take precedence over anything in this skill they conflict with. This is the supported way to tailor `/fullsolve` without forking it — `overrides.md` lives under `.claude/.local/`, which `sequant update` and `sync` never overwrite.
+
 # Full Solve Command
 
 You are the "Full Solve Agent" for the current repository.

package/dist/marketplace/external_plugins/sequant/skills/improve/SKILL.md

@@ -16,6 +16,9 @@ allowed-tools:
   - AskUserQuestion
 ---
 
+<!-- sequant:local-override -->
+> **Local overrides (read this first).** Before following any instruction below, check whether `.claude/.local/skills/improve/overrides.md` exists. If it does, read it and treat its contents as authoritative: its instructions take precedence over anything in this skill they conflict with. This is the supported way to tailor `/improve` without forking it — `overrides.md` lives under `.claude/.local/`, which `sequant update` and `sync` never overwrite.
+
 # Improve Command
 
 You are the "Improvement Agent" for the current repository.
@@ -665,4 +668,4 @@ Error: Path `src/nonexistent/` not found.
 - [ ] **Recommendations** - Tips for running quick wins vs larger refactors
 
 **DO NOT proceed to issue creation without user selection.**
-**DO NOT respond until all items are verified.**
+**DO NOT respond until all items are verified.**

package/dist/marketplace/external_plugins/sequant/skills/loop/SKILL.md

@@ -25,6 +25,9 @@ allowed-tools:
   - Bash(git status:*)
 ---
 
+<!-- sequant:local-override -->
+> **Local overrides (read this first).** Before following any instruction below, check whether `.claude/.local/skills/loop/overrides.md` exists. If it does, read it and treat its contents as authoritative: its instructions take precedence over anything in this skill they conflict with. This is the supported way to tailor `/loop` without forking it — `overrides.md` lives under `.claude/.local/`, which `sequant update` and `sync` never overwrite.
+
 # Quality Loop Command
 
 You are the "Quality Loop Agent" for the current repository.

package/dist/marketplace/external_plugins/sequant/skills/merger/SKILL.md

@@ -16,6 +16,9 @@ allowed-tools:
   - Glob
 ---
 
+<!-- sequant:local-override -->
+> **Local overrides (read this first).** Before following any instruction below, check whether `.claude/.local/skills/merger/overrides.md` exists. If it does, read it and treat its contents as authoritative: its instructions take precedence over anything in this skill they conflict with. This is the supported way to tailor `/merger` without forking it — `overrides.md` lives under `.claude/.local/`, which `sequant update` and `sync` never overwrite.
+
 # Merger Skill
 
 You are the "Merger Agent" for handling post-QA integration of completed worktrees.

package/dist/marketplace/external_plugins/sequant/skills/qa/SKILL.md

@@ -24,6 +24,9 @@ allowed-tools:
   - AgentOutputTool
 ---
 
+<!-- sequant:local-override -->
+> **Local overrides (read this first).** Before following any instruction below, check whether `.claude/.local/skills/qa/overrides.md` exists. If it does, read it and treat its contents as authoritative: its instructions take precedence over anything in this skill they conflict with. This is the supported way to tailor `/qa` without forking it — `overrides.md` lives under `.claude/.local/`, which `sequant update` and `sync` never overwrite.
+
 # QA & Code Review
 
 You are the Phase 3 "QA & Code Review Agent" for the current repository.

package/dist/marketplace/external_plugins/sequant/skills/reflect/SKILL.md

@@ -12,6 +12,9 @@ allowed-tools:
   - Grep
 ---
 
+<!-- sequant:local-override -->
+> **Local overrides (read this first).** Before following any instruction below, check whether `.claude/.local/skills/reflect/overrides.md` exists. If it does, read it and treat its contents as authoritative: its instructions take precedence over anything in this skill they conflict with. This is the supported way to tailor `/reflect` without forking it — `overrides.md` lives under `.claude/.local/`, which `sequant update` and `sync` never overwrite.
+
 # Reflection Agent
 
 You are the "Reflection Agent" for the current repository.

package/dist/marketplace/external_plugins/sequant/skills/security-review/SKILL.md

@@ -17,6 +17,9 @@ allowed-tools:
   - Bash(gh issue comment:*)
 ---
 
+<!-- sequant:local-override -->
+> **Local overrides (read this first).** Before following any instruction below, check whether `.claude/.local/skills/security-review/overrides.md` exists. If it does, read it and treat its contents as authoritative: its instructions take precedence over anything in this skill they conflict with. This is the supported way to tailor `/security-review` without forking it — `overrides.md` lives under `.claude/.local/`, which `sequant update` and `sync` never overwrite.
+
 # Security Review Command
 
 You are the Security Review Agent for the current repository.

package/dist/marketplace/external_plugins/sequant/skills/setup/SKILL.md

@@ -30,6 +30,9 @@ allowed-tools:
   - Bash(curl:*)
 ---
 
+<!-- sequant:local-override -->
+> **Local overrides (read this first).** Before following any instruction below, check whether `.claude/.local/skills/setup/overrides.md` exists. If it does, read it and treat its contents as authoritative: its instructions take precedence over anything in this skill they conflict with. This is the supported way to tailor `/setup` without forking it — `overrides.md` lives under `.claude/.local/`, which `sequant update` and `sync` never overwrite.
+
 # Sequant Setup
 
 Initialize Sequant workflow system in your current project.

package/dist/marketplace/external_plugins/sequant/skills/solve/SKILL.md

@@ -13,6 +13,9 @@ allowed-tools:
   - Bash(gh *)
 ---
 
+<!-- sequant:local-override -->
+> **Local overrides (read this first).** Before following any instruction below, check whether `.claude/.local/skills/solve/overrides.md` exists. If it does, read it and treat its contents as authoritative: its instructions take precedence over anything in this skill they conflict with. This is the supported way to tailor `/solve` without forking it — `overrides.md` lives under `.claude/.local/`, which `sequant update` and `sync` never overwrite.
+
 # /solve — Deprecated Alias for /assess
 
 **This command has been merged into `/assess`.** Use `/assess` instead.

package/dist/marketplace/external_plugins/sequant/skills/spec/SKILL.md

@@ -17,6 +17,9 @@ allowed-tools:
   - AgentOutputTool
 ---
 
+<!-- sequant:local-override -->
+> **Local overrides (read this first).** Before following any instruction below, check whether `.claude/.local/skills/spec/overrides.md` exists. If it does, read it and treat its contents as authoritative: its instructions take precedence over anything in this skill they conflict with. This is the supported way to tailor `/spec` without forking it — `overrides.md` lives under `.claude/.local/`, which `sequant update` and `sync` never overwrite.
+
 # Planning Agent
 
 Phase 1 "Planning Agent." Understands the issue and AC, reviews or synthesizes a plan, identifies gaps and risks, and drafts a GitHub issue comment.

package/dist/marketplace/external_plugins/sequant/skills/test/SKILL.md

@@ -19,6 +19,9 @@ allowed-tools:
   - Bash(npx tsx:*)
 ---
 
+<!-- sequant:local-override -->
+> **Local overrides (read this first).** Before following any instruction below, check whether `.claude/.local/skills/test/overrides.md` exists. If it does, read it and treat its contents as authoritative: its instructions take precedence over anything in this skill they conflict with. This is the supported way to tailor `/test` without forking it — `overrides.md` lives under `.claude/.local/`, which `sequant update` and `sync` never overwrite.
+
 # Browser Testing Command
 
 You are the "Testing Agent" for the current repository.

package/dist/marketplace/external_plugins/sequant/skills/testgen/SKILL.md

@@ -20,6 +20,9 @@ allowed-tools:
   - Agent(sequant-testgen)
 ---
 
+<!-- sequant:local-override -->
+> **Local overrides (read this first).** Before following any instruction below, check whether `.claude/.local/skills/testgen/overrides.md` exists. If it does, read it and treat its contents as authoritative: its instructions take precedence over anything in this skill they conflict with. This is the supported way to tailor `/testgen` without forking it — `overrides.md` lives under `.claude/.local/`, which `sequant update` and `sync` never overwrite.
+
 # Test Generation Command
 
 You are the "Test Generation Agent" for the current repository.

package/dist/marketplace/external_plugins/sequant/skills/verify/SKILL.md

@@ -15,6 +15,9 @@ allowed-tools:
   - Bash(gh issue comment:*)
 ---
 
+<!-- sequant:local-override -->
+> **Local overrides (read this first).** Before following any instruction below, check whether `.claude/.local/skills/verify/overrides.md` exists. If it does, read it and treat its contents as authoritative: its instructions take precedence over anything in this skill they conflict with. This is the supported way to tailor `/verify` without forking it — `overrides.md` lives under `.claude/.local/`, which `sequant update` and `sync` never overwrite.
+
 # Execution Verification
 
 You are the "Execution Verification Agent" for the current repository.

package/dist/src/commands/ready.js

@@ -130,7 +130,7 @@ export async function readyCommand(issueArg, options) {
         const branch = listWorktrees().find((w) => w.issue === issueNumber)?.branch ?? "";
         adapter = new ReadySnapshotAdapter({ issueNumber, title, branch });
         onProgress = adapter.onProgress;
-        const { renderTui } = await import("../ui/tui/index.js");
+        const { renderTui } = await (await import("../ui/tui/load.js")).loadTui();
         tuiHandle = renderTui(adapter);
     }
     else if (!options.json) {

package/dist/src/commands/run.js

@@ -92,7 +92,7 @@ export async function runCommand(issues, options) {
         maxLoopIterations: resolved.config.maxIterations,
     });
     if (tuiEnabled) {
-        const { renderTui } = await import("../ui/tui/index.js");
+        const { renderTui } = await (await import("../ui/tui/load.js")).loadTui();
         let tuiHandle = null;
         // Unmount the TUI before ShutdownManager writes its shutdown banner so
         // the two don't race on stdout / leave the terminal in alt-screen buffer.

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

@@ -13,16 +13,54 @@ interface SyncOptions {
  */
 export declare function getSkillsVersion(): Promise<string | null>;
 /**
- * Check if skills are outdated compared to package version
+ * Skills status relative to the bundled package, as seen by the pre-flight path.
  */
-export declare function areSkillsOutdated(): Promise<{
+export interface SkillsOutdatedStatus {
+    /** Version-marker mismatch (`.sequant-version` ≠ package). Cheap fast-path. */
     outdated: boolean;
     currentVersion: string | null;
     packageVersion: string;
-}>;
+    /**
+     * Count of bundled files that are `new` or `modified` in place at a *matching*
+     * version (the #708 blind spot the version marker can't see). Only computed
+     * when versions match; `0` otherwise (a mismatch already means stale). Excludes
+     * `local-override`/`unchanged` so customized files (e.g. constitution, #711)
+     * don't register as drift.
+     */
+    contentDrift: number;
+}
+/**
+ * Check if skills are outdated compared to package version.
+ *
+ * The version marker is only a cheap hint: a tree at the matching version can
+ * still have drifted bundled content in place (the #708 root cause). So when the
+ * marker matches we run the same content diff `sync` uses (`computeTemplateChanges`,
+ * the single source of truth from #708/#710) and surface a `contentDrift` count.
+ * On a version *mismatch* we skip the diff entirely — the install is already stale
+ * and the copy path handles it — keeping the per-command pre-flight cheap (AC-5).
+ *
+ * `options.cache` opts into a stat-only fingerprint cache for the content scan,
+ * so the hot pre-flight path (which runs before most commands, including batched
+ * `/assess` dashboard calls) pays the full ~15ms scan only when something that
+ * affects drift actually changed. Off by default so diagnostic callers (`doctor`)
+ * always see fresh truth.
+ */
+export declare function areSkillsOutdated(options?: {
+    cache?: boolean;
+}): Promise<SkillsOutdatedStatus>;
 export declare function syncCommand(options?: SyncOptions): Promise<void>;
 /**
- * Check and warn if skills are outdated (for use by other commands)
+ * Check and warn if skills are outdated (for use by other commands).
+ *
+ * Warns on either signal: a version-marker mismatch, or in-place content drift at
+ * a matching version (#708/#713). The content-drift path is warn-only by design —
+ * it never mutates files and never sets `process.exitCode` (this is a pre-flight,
+ * not the command itself), so customized installs (#711) are left intact.
+ *
+ * Callers that have already computed the status (e.g. the `preAction` hook) can
+ * pass it in to avoid a second template scan on the hot path (AC-5).
+ *
+ * @returns `true` if a warning was emitted, `false` if up to date.
  */
-export declare function checkAndWarnSkillsOutdated(): Promise<boolean>;
+export declare function checkAndWarnSkillsOutdated(status?: SkillsOutdatedStatus): Promise<boolean>;
 export {};

package/dist/src/commands/sync.js

@@ -5,14 +5,23 @@
  * Designed for plugin users who need to update after upgrading sequant.
  */
 import chalk from "chalk";
+import { join } from "path";
+import { createHash } from "crypto";
 import { getManifest, updateManifest, getPackageVersion, } from "../lib/manifest.js";
-import { copyTemplates } from "../lib/templates.js";
+import { copyTemplates, computeTemplateChanges, listTemplateFiles, getTemplatesDir, } from "../lib/templates.js";
 import { getConfig } from "../lib/config.js";
-import { writeFile, readFile, fileExists } from "../lib/fs.js";
+import { writeFile, readFile, fileExists, getFileStats } from "../lib/fs.js";
 import { generateAgentsMd, writeAgentsMd, AGENTS_MD_PATH, } from "../lib/agents-md.js";
 import { getProjectName } from "../lib/project-name.js";
 import { getStackConfig } from "../lib/stacks.js";
 const SKILLS_VERSION_PATH = ".claude/skills/.sequant-version";
+// Where the cheap drift-fingerprint cache lives (gitignored via `**/.sequant/`).
+const DRIFT_CACHE_PATH = ".claude/.sequant/.skills-drift-cache.json";
+// Mirrors config.ts / manifest.ts (those constants are module-private). These
+// install paths are stable; we stat them only to invalidate the drift cache
+// when the project's config tokens or manifest stack change.
+const CONFIG_FILE_PATH = ".claude/.sequant/config.json";
+const MANIFEST_FILE_PATH = ".sequant-manifest.json";
 /**
  * Get the version of skills currently installed
  */
@@ -29,16 +38,141 @@ export async function getSkillsVersion() {
     }
 }
 /**
- * Check if skills are outdated compared to package version
+ * Cheap stat-only fingerprint of every input that can change the content-drift
+ * result: package version plus the mtime (or absence) of each bundled template,
+ * its installed counterpart, any `.claude/.local/` override, and the config and
+ * manifest. A full read+render+diff scan is ~15ms per command; this fingerprint
+ * is ~2-5ms, so the per-command pre-flight can skip the scan when nothing that
+ * affects drift has changed (AC-5). A per-file hash (not a max-mtime) is used so
+ * editing an *older* file — whose new mtime may still trail another file's —
+ * still changes the fingerprint and forces a rescan (no missed warnings).
+ *
+ * Returns `null` if it cannot be computed; the caller then scans uncached.
+ */
+async function computeDriftFingerprint(packageVersion) {
+    try {
+        const templateFiles = await listTemplateFiles();
+        const templatesDir = getTemplatesDir();
+        const lines = [`v=${packageVersion}`];
+        const addPath = async (fsPath, key) => {
+            try {
+                const stats = await getFileStats(fsPath);
+                lines.push(`${key}:${Math.round(stats.mtimeMs)}`);
+            }
+            catch {
+                // Missing file is itself signal: a `.local` override or installed file
+                // appearing/disappearing flips this line and invalidates the cache.
+                lines.push(`${key}:absent`);
+            }
+        };
+        for (const templatePath of templateFiles) {
+            const normalized = templatePath.replace(/\\/g, "/");
+            const localPath = normalized.replace("templates/", ".claude/");
+            if (localPath.includes(".local/"))
+                continue;
+            const templateFsPath = join(templatesDir, normalized.replace("templates/", ""));
+            const overridePath = localPath.replace(".claude/", ".claude/.local/");
+            await addPath(templateFsPath, `t:${normalized}`);
+            await addPath(localPath, `l:${localPath}`);
+            await addPath(overridePath, `o:${overridePath}`);
+        }
+        await addPath(CONFIG_FILE_PATH, "config");
+        await addPath(MANIFEST_FILE_PATH, "manifest");
+        lines.sort();
+        return createHash("sha1").update(lines.join("\n")).digest("hex");
+    }
+    catch {
+        return null;
+    }
+}
+async function readDriftCache() {
+    try {
+        if (!(await fileExists(DRIFT_CACHE_PATH)))
+            return null;
+        const parsed = JSON.parse(await readFile(DRIFT_CACHE_PATH));
+        if (typeof parsed?.fingerprint === "string" &&
+            typeof parsed?.contentDrift === "number") {
+            return parsed;
+        }
+        return null;
+    }
+    catch {
+        // Corrupt/unreadable cache → treat as a miss; the scan path rebuilds it.
+        return null;
+    }
+}
+async function writeDriftCache(cache) {
+    try {
+        await writeFile(DRIFT_CACHE_PATH, JSON.stringify(cache));
+    }
+    catch {
+        // The cache is a pure optimization — never fail a command over a write miss
+        // (e.g. the `.claude/.sequant/` dir not existing yet).
+    }
+}
+/**
+ * Run the content-drift scan (the source-of-truth `computeTemplateChanges` diff),
+ * returning the count of `new`+`modified` files. When `useCache` is true (the
+ * per-command pre-flight), a stat-only fingerprint short-circuits the scan if no
+ * drift-affecting input changed since the last run. Callers that need fresh
+ * truth (`doctor`, and `sync` itself) leave caching off — the default.
  */
-export async function areSkillsOutdated() {
+async function computeContentDrift(packageVersion, useCache) {
+    let fingerprint = null;
+    if (useCache) {
+        fingerprint = await computeDriftFingerprint(packageVersion);
+        if (fingerprint) {
+            const cached = await readDriftCache();
+            if (cached && cached.fingerprint === fingerprint) {
+                return cached.contentDrift;
+            }
+        }
+    }
+    try {
+        const manifest = await getManifest();
+        if (!manifest)
+            return 0;
+        const config = await getConfig();
+        const tokens = config?.tokens || {};
+        const changes = await computeTemplateChanges(manifest.stack, tokens);
+        const contentDrift = changes.filter((c) => c.status === "new" || c.status === "modified").length;
+        if (useCache && fingerprint) {
+            await writeDriftCache({ fingerprint, contentDrift });
+        }
+        return contentDrift;
+    }
+    catch {
+        // The pre-flight must never break the actual command. If the content diff
+        // fails (missing templates, read error), treat it as "no detectable drift"
+        // and let the command proceed.
+        return 0;
+    }
+}
+/**
+ * Check if skills are outdated compared to package version.
+ *
+ * The version marker is only a cheap hint: a tree at the matching version can
+ * still have drifted bundled content in place (the #708 root cause). So when the
+ * marker matches we run the same content diff `sync` uses (`computeTemplateChanges`,
+ * the single source of truth from #708/#710) and surface a `contentDrift` count.
+ * On a version *mismatch* we skip the diff entirely — the install is already stale
+ * and the copy path handles it — keeping the per-command pre-flight cheap (AC-5).
+ *
+ * `options.cache` opts into a stat-only fingerprint cache for the content scan,
+ * so the hot pre-flight path (which runs before most commands, including batched
+ * `/assess` dashboard calls) pays the full ~15ms scan only when something that
+ * affects drift actually changed. Off by default so diagnostic callers (`doctor`)
+ * always see fresh truth.
+ */
+export async function areSkillsOutdated(options = {}) {
     const currentVersion = await getSkillsVersion();
     const packageVersion = getPackageVersion();
-    return {
-        outdated: currentVersion !== packageVersion,
-        currentVersion,
-        packageVersion,
-    };
+    const outdated = currentVersion !== packageVersion;
+    let contentDrift = 0;
+    if (!outdated) {
+        contentDrift = await computeContentDrift(packageVersion, options.cache === true);
+    }
+    return { outdated, currentVersion, packageVersion, contentDrift };
 }
 /**
  * Update the skills version marker
@@ -68,16 +202,35 @@ export async function syncCommand(options = {}) {
         console.log(chalk.gray(`Package version: ${packageVersion}`));
         console.log(chalk.gray(`Stack: ${manifest.stack}\n`));
     }
-    // Check if sync is needed
+    // Get config tokens for template processing
+    const config = await getConfig();
+    const tokens = config?.tokens || {};
+    // The version marker is only a fast-path hint — verify actual content before
+    // claiming "up to date". On a version match we still diff bundled templates
+    // against installed content (rendered with the same variables) so we never
+    // declare success while real drift sits in place (#708).
     if (!force && skillsVersion === packageVersion) {
+        const changes = await computeTemplateChanges(manifest.stack, tokens);
+        const drifted = changes.filter((c) => c.status === "new" || c.status === "modified");
+        if (drifted.length === 0) {
+            // Truthful no-op: content is actually identical.
+            if (!quiet) {
+                console.log(chalk.green("✔ Skills are already up to date!"));
+            }
+            return;
+        }
+        // Version current but content differs — report, don't mutate (report-only
+        // keeps the fast path from silently overwriting in-place customizations).
         if (!quiet) {
-            console.log(chalk.green("✔ Skills are already up to date!"));
+            console.log(chalk.yellow(`!  Version current, but ${drifted.length} file(s) differ — run \`update\` or \`sync --force\``));
         }
+        // Signal drift with a non-zero exit code even under --quiet. The exit code
+        // is the machine signal the (suppressible) message is not, so the
+        // non-interactive / CI path we recommend can't treat a drifted tree as
+        // success — the original failure mode in #708.
+        process.exitCode = 1;
         return;
     }
-    // Get config tokens for template processing
-    const config = await getConfig();
-    const tokens = config?.tokens || {};
     // Copy templates with force to overwrite existing files
     const copyOptions = {
         force: true, // Always overwrite when syncing
@@ -118,14 +271,32 @@ export async function syncCommand(options = {}) {
     }
 }
 /**
- * Check and warn if skills are outdated (for use by other commands)
+ * Check and warn if skills are outdated (for use by other commands).
+ *
+ * Warns on either signal: a version-marker mismatch, or in-place content drift at
+ * a matching version (#708/#713). The content-drift path is warn-only by design —
+ * it never mutates files and never sets `process.exitCode` (this is a pre-flight,
+ * not the command itself), so customized installs (#711) are left intact.
+ *
+ * Callers that have already computed the status (e.g. the `preAction` hook) can
+ * pass it in to avoid a second template scan on the hot path (AC-5).
+ *
+ * @returns `true` if a warning was emitted, `false` if up to date.
  */
-export async function checkAndWarnSkillsOutdated() {
-    const { outdated, currentVersion, packageVersion } = await areSkillsOutdated();
+export async function checkAndWarnSkillsOutdated(status) {
+    const { outdated, currentVersion, packageVersion, contentDrift } = status ?? (await areSkillsOutdated());
     if (outdated) {
         console.log(chalk.yellow(`\n!  Skills are outdated (${currentVersion || "unknown"} → ${packageVersion})`));
         console.log(chalk.yellow("   Run: npx sequant sync\n"));
         return true;
     }
+    if (contentDrift > 0) {
+        // Mirror syncCommand's own drift remediation: a bare `sync` at a matching
+        // version is report-only (it won't copy), so point at the commands that
+        // actually resolve in-place drift — `sync --force` or `update`.
+        console.log(chalk.yellow(`\n!  Version current, but ${contentDrift} file(s) differ from bundled content`));
+        console.log(chalk.yellow("   Run: npx sequant sync --force (or npx sequant update)\n"));
+        return true;
+    }
     return false;
 }

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

@@ -4,6 +4,7 @@
 interface UpdateOptions {
     dryRun?: boolean;
     force?: boolean;
+    yes?: boolean;
 }
 export declare function updateCommand(options: UpdateOptions): Promise<void>;
 export {};