sequant 2.6.1 → 2.7.0

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.
  */
-export async function areSkillsOutdated() {
+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.
+ */
+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
@@ -47,7 +181,7 @@ async function updateSkillsVersion() {
     await writeFile(SKILLS_VERSION_PATH, getPackageVersion());
 }
 export async function syncCommand(options = {}) {
-    const { force = false, quiet = false } = options;
+    const { force = false, quiet = false, dryRun = false } = options;
     if (!quiet) {
         console.log(chalk.blue("\nSyncing templates...\n"));
         console.log(chalk.yellow("Note: For seamless auto-updates, install sequant as a Claude Code plugin:\n" +
@@ -68,16 +202,90 @@ 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;
+    }
+    // Preview path: report exactly what the apply would write, then stop without
+    // mutating (#722). This branch is only reached when `force` is set or the
+    // version marker mismatches — i.e. the path that runs `copyTemplates(force:
+    // true)` and rewrites the whole tree. (A matching-version, non-force dry-run
+    // already returned at the report-only short-circuit above, which never
+    // mutates.) `copyTemplates` does NOT protect in-place customizations the way
+    // `update` does — the force copy overwrites them — so the preview counts
+    // `local-override` files alongside `new`/`modified`. Reporting only
+    // new+modified would under-report the write-set, the exact divergence #722
+    // is about.
+    if (dryRun) {
+        const changes = await computeTemplateChanges(manifest.stack, tokens);
+        const newFiles = changes.filter((c) => c.status === "new");
+        const modifiedFiles = changes.filter((c) => c.status === "modified");
+        const localOverrides = changes.filter((c) => c.status === "local-override");
+        const toWrite = [...newFiles, ...modifiedFiles, ...localOverrides];
+        if (!quiet) {
+            console.log(chalk.bold("Summary (dry-run):"));
+            console.log(chalk.green(`  New files: ${newFiles.length}`));
+            console.log(chalk.yellow(`  Modified: ${modifiedFiles.length}`));
+            console.log(chalk.blue(`  Local overrides (overwritten by sync): ${localOverrides.length}`));
+            if (modifiedFiles.length > 0) {
+                console.log(chalk.bold("\nModified files:"));
+                for (const file of modifiedFiles) {
+                    console.log(chalk.yellow(`  ${file.path}`));
+                }
+            }
+            if (newFiles.length > 0) {
+                console.log(chalk.bold("\nNew files:"));
+                for (const file of newFiles) {
+                    console.log(chalk.green(`  ${file.path}`));
+                }
+            }
+            if (localOverrides.length > 0) {
+                console.log(chalk.bold("\nLocal overrides (will be overwritten by sync):"));
+                for (const file of localOverrides) {
+                    console.log(chalk.blue(`  ${file.path}`));
+                }
+            }
+            if (toWrite.length === 0) {
+                console.log(chalk.green("\n✔ Skills are already up to date!"));
+            }
+            else {
+                console.log(chalk.gray("\n(dry-run mode - no changes made)"));
+            }
+        }
+        // Non-zero exit when work is pending so the documented preview surface can
+        // gate CI/automation (the #709 intent): a dry-run reporting nothing must
+        // mean nothing to do. The matching-version short-circuit signals drift the
+        // same way.
+        if (toWrite.length > 0) {
+            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 +326,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 {};

package/dist/src/commands/update.js

@@ -2,14 +2,36 @@
  * sequant update - Update templates from the package
  */
 import chalk from "chalk";
-import { diffLines } from "diff";
 import inquirer from "inquirer";
 import { spawnSync } from "child_process";
 import { getManifest, updateManifest, getPackageVersion, } from "../lib/manifest.js";
-import { getTemplateContent, listTemplateFiles, processTemplate, } from "../lib/templates.js";
+import { computeTemplateChanges } from "../lib/templates.js";
 import { getConfig, saveConfig } from "../lib/config.js";
 import { getStackConfig, PM_CONFIG, getPackageManagerCommands, } from "../lib/stacks.js";
-import { readFile, writeFile, fileExists } from "../lib/fs.js";
+import { writeFile } from "../lib/fs.js";
+import { isStdinTTY, isCI, getNonInteractiveReason } from "../lib/tty.js";
+/**
+ * True when `update` must not prompt: stdin is not a terminal (piped input) or
+ * we are running in a recognized CI environment. CI is checked explicitly
+ * because some runners allocate a pseudo-TTY — `isStdinTTY()` alone would let
+ * the prompt render and then hang an unattended job forever.
+ */
+function isNonInteractive() {
+    return !isStdinTTY() || isCI();
+}
+/**
+ * Print an actionable message and set a non-zero exit code when a prompt is
+ * required but the shell is non-interactive (piped/CI). Prevents inquirer from
+ * throwing a raw ExitPromptError stack trace. Callers should `return`
+ * immediately after.
+ */
+function refuseNonInteractive() {
+    const reason = getNonInteractiveReason() ?? "stdin is not a terminal";
+    console.error(chalk.red(`\n❌ non-interactive shell (${reason}): \`update\` needs to prompt to continue.`));
+    console.error(chalk.yellow("   Re-run with `--yes` (or `-y`) to apply updates without prompting,"));
+    console.error(chalk.yellow("   or use `--dry-run` to preview changes without applying."));
+    process.exitCode = 1;
+}
 export async function updateCommand(options) {
     console.log(chalk.blue("\nChecking for updates...\n"));
     console.log(chalk.yellow("Note: For seamless auto-updates, install sequant as a Claude Code plugin:\n" +
@@ -58,10 +80,19 @@ export async function updateCommand(options) {
         // Get package manager run command
         const pm = manifest.packageManager || "npm";
         const pmConfig = getPackageManagerCommands(pm);
-        if (options.force) {
+        if (options.force || options.yes) {
             tokens = { DEV_URL: defaultDevUrl, PM_RUN: pmConfig.run };
             console.log(chalk.blue(`Using default dev URL: ${defaultDevUrl}`));
         }
+        else if (options.dryRun) {
+            // Dry-run is read-only: preview with defaults, never prompt or persist.
+            tokens = { DEV_URL: defaultDevUrl, PM_RUN: pmConfig.run };
+            console.log(chalk.blue(`Using default dev URL for preview: ${defaultDevUrl}`));
+        }
+        else if (isNonInteractive()) {
+            refuseNonInteractive();
+            return;
+        }
         else {
             const { inputDevUrl } = await inquirer.prompt([
                 {
@@ -73,57 +104,22 @@ export async function updateCommand(options) {
             ]);
             tokens = { DEV_URL: inputDevUrl, PM_RUN: pmConfig.run };
         }
-        // Save the new config
+        // Persist the new config — but not on a dry-run preview, which must leave
+        // the project untouched.
         config = {
             tokens,
             stack: manifest.stack,
             initialized: manifest.installedAt,
         };
-        await saveConfig(config);
-        console.log(chalk.green("✔ Configuration saved\n"));
-    }
-    // Get list of template files
-    const templateFiles = await listTemplateFiles();
-    const changes = [];
-    for (const templatePath of templateFiles) {
-        const localPath = templatePath.replace("templates/", ".claude/");
-        // Skip if in .local directory (user customizations)
-        if (localPath.includes(".local/")) {
-            continue;
-        }
-        const templateContent = await getTemplateContent(templatePath);
-        const exists = await fileExists(localPath);
-        if (!exists) {
-            changes.push({ path: localPath, status: "new" });
-        }
-        else {
-            const localContent = await readFile(localPath);
-            if (localContent === templateContent) {
-                changes.push({ path: localPath, status: "unchanged" });
-            }
-            else {
-                // Check if there's a local override
-                const localOverridePath = localPath.replace(".claude/", ".claude/.local/");
-                const hasLocalOverride = await fileExists(localOverridePath);
-                if (hasLocalOverride) {
-                    changes.push({ path: localPath, status: "local-override" });
-                }
-                else {
-                    const diff = diffLines(localContent, templateContent)
-                        .map((part) => {
-                        const prefix = part.added ? "+" : part.removed ? "-" : " ";
-                        return part.value
-                            .split("\n")
-                            .filter((l) => l)
-                            .map((l) => `${prefix} ${l}`)
-                            .join("\n");
-                    })
-                        .join("\n");
-                    changes.push({ path: localPath, status: "modified", diff });
-                }
-            }
+        if (!options.dryRun) {
+            await saveConfig(config);
+            console.log(chalk.green("✔ Configuration saved\n"));
         }
     }
+    // Compute changes using the shared, variable-aware comparison.
+    // Templates are rendered (PROJECT_NAME, STACK_NOTES, etc.) before diffing,
+    // and in-place-customizable files (constitution) are protected as overrides.
+    const changes = await computeTemplateChanges(manifest.stack, tokens);
     // Show summary
     const newFiles = changes.filter((c) => c.status === "new");
     const modifiedFiles = changes.filter((c) => c.status === "modified");
@@ -134,8 +130,17 @@ export async function updateCommand(options) {
     console.log(chalk.yellow(`  Modified: ${modifiedFiles.length}`));
     console.log(chalk.gray(`  ✓ Unchanged: ${unchangedFiles.length}`));
     console.log(chalk.blue(`  Local overrides: ${localOverrides.length}`));
-    if (newFiles.length === 0 && modifiedFiles.length === 0) {
-        console.log(chalk.green("\n✔ Everything is up to date!"));
+    // Local overrides are protected by default — only --force overwrites them.
+    const applySet = options.force
+        ? [...newFiles, ...modifiedFiles, ...localOverrides]
+        : [...newFiles, ...modifiedFiles];
+    if (applySet.length === 0) {
+        if (localOverrides.length > 0) {
+            console.log(chalk.blue(`\n✔ No updates to apply. ${localOverrides.length} local override(s) protected (use --force to overwrite).`));
+        }
+        else {
+            console.log(chalk.green("\n✔ Everything is up to date!"));
+        }
         return;
     }
     // Show changes
@@ -154,12 +159,30 @@ export async function updateCommand(options) {
             console.log(chalk.green(`  ${file.path}`));
         }
     }
+    if (options.force && localOverrides.length > 0) {
+        console.log(chalk.bold("\nLocal overrides (forced overwrite):"));
+        for (const file of localOverrides) {
+            console.log(chalk.blue(`  ${file.path}`));
+        }
+    }
     if (options.dryRun) {
         console.log(chalk.gray("\n(dry-run mode - no changes made)"));
+        // Non-zero exit when work is pending so a CI/automation job can gate on the
+        // preview, matching `sync --dry-run` (#724 / #709 intent): a dry-run that
+        // reports nothing must mean nothing to do. The no-op case short-circuits at
+        // the "Everything is up to date!" return above, so it correctly stays 0.
+        if (applySet.length > 0) {
+            process.exitCode = 1;
+        }
         return;
     }
-    // Confirm update
-    if (!options.force) {
+    // Confirm update. --yes and --force both auto-confirm; otherwise we need a
+    // prompt, which is impossible without a TTY — bail cleanly instead of crashing.
+    if (!options.force && !options.yes) {
+        if (isNonInteractive()) {
+            refuseNonInteractive();
+            return;
+        }
         const { proceed } = await inquirer.prompt([
             {
                 type: "confirm",
@@ -173,30 +196,19 @@ export async function updateCommand(options) {
             return;
         }
     }
-    // Apply updates
+    // Apply updates — content was already rendered with the shared variable set
+    // during change detection, so just write it.
     console.log(chalk.blue("\nApplying updates..."));
     let updated = 0;
-    // Build complete variables for template processing
-    const stackConfig = getStackConfig(manifest.stack);
-    const variables = {
-        ...stackConfig.variables,
-        ...tokens,
-        PROJECT_NAME: process.cwd().split("/").pop() || "project",
-        STACK: manifest.stack,
-    };
-    for (const file of [...newFiles, ...modifiedFiles]) {
-        const templatePath = file.path.replace(".claude/", "templates/");
-        let content = await getTemplateContent(templatePath);
-        // Process templates with tokens to replace {{DEV_URL}} etc.
-        content = processTemplate(content, variables);
-        await writeFile(file.path, content);
+    for (const file of applySet) {
+        await writeFile(file.path, file.rendered);
         updated++;
     }
     // Update manifest
     await updateManifest();
     console.log(chalk.green(`\n✔ Updated ${updated} files`));
     // Check if package.json was updated and run install
-    const packageJsonUpdated = [...newFiles, ...modifiedFiles].some((f) => f.path === "package.json" || f.path.endsWith("/package.json"));
+    const packageJsonUpdated = applySet.some((f) => f.path === "package.json" || f.path.endsWith("/package.json"));
     if (packageJsonUpdated) {
         // Use detected package manager or default to npm
         const pm = manifest.packageManager || "npm";

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

@@ -14,6 +14,56 @@ export declare function listTemplateFiles(): Promise<string[]>;
  * Get content of a template file
  */
 export declare function getTemplateContent(templatePath: string): Promise<string>;
+/**
+ * Files that are meant to be edited in place per project (e.g. the
+ * constitution). When one of these diverges from the rendered template
+ * without a parallel `.claude/.local/` file, it is treated as a protected
+ * local override rather than a stale "modified" file — so the default
+ * (non-`--force`) update/sync path never silently overwrites it.
+ */
+export declare const CUSTOMIZABLE_FILES: string[];
+/**
+ * Whether a local path is a customizable file edited in place per project.
+ */
+export declare function isCustomizableFile(localPath: string): boolean;
+/**
+ * Build the full set of template variables used when rendering templates.
+ *
+ * This is the single source of truth shared by `copyTemplates` (write time)
+ * and `computeTemplateChanges` (diff time) so the two can never drift — a
+ * mismatch here is what caused `constitution.md` to read as "modified" on
+ * every project (the diff used a different/incomplete variable set than the
+ * write). See #708.
+ */
+export declare function buildTemplateVariables(stack: string, tokens?: Record<string, string>, options?: {
+    additionalStacks?: string[];
+}): Promise<Record<string, string>>;
+/**
+ * A single template file's status relative to the installed copy.
+ */
+export interface TemplateChange {
+    /** Installed path under `.claude/` */
+    path: string;
+    /** Source template path under `templates/` */
+    templatePath: string;
+    status: "new" | "modified" | "unchanged" | "local-override";
+    /** Template content rendered with the project's variables */
+    rendered: string;
+    /** Unified-ish diff (installed → rendered), only set for `modified` */
+    diff?: string;
+}
+/**
+ * Compare bundled template content against what's installed under `.claude/`.
+ *
+ * Templates are rendered with the project's variables *before* comparison, so
+ * an unmodified file (e.g. a constitution with `{{PROJECT_NAME}}` expanded)
+ * reads as `unchanged` rather than `modified`. A file that diverges in place is
+ * `local-override` (skip-by-default) when it has a parallel `.claude/.local/`
+ * file or is in the customizable allow-list; otherwise it is `modified`.
+ */
+export declare function computeTemplateChanges(stack: string, tokens?: Record<string, string>, options?: {
+    additionalStacks?: string[];
+}): Promise<TemplateChange[]>;
 /**
  * Result of symlink creation attempt
  */