sequant 2.9.0 → 2.10.0

package/dist/src/lib/stacks.js

@@ -1,8 +1,9 @@
 /**
  * Stack detection and configuration
  */
-import { existsSync } from "fs";
+import { closeSync, existsSync, openSync, readFileSync, readSync } from "fs";
 import { readdir } from "fs/promises";
+import { join } from "path";
 import { fileExists, readFile } from "./fs.js";
 /**
  * Directories to skip during multi-stack detection
@@ -30,6 +31,7 @@ export const PM_CONFIG = {
         exec: "npx",
         install: "npm install",
         installSilent: "npm install --silent",
+        ciInstall: "npm ci",
         addPkg: "npm install",
         removePkg: "npm uninstall",
         updatePkg: "npm update",
@@ -39,34 +41,62 @@ export const PM_CONFIG = {
         exec: "bunx",
         install: "bun install",
         installSilent: "bun install --silent",
+        ciInstall: "bun install --frozen-lockfile",
         addPkg: "bun add",
         removePkg: "bun remove",
         updatePkg: "bun update",
     },
+    // Yarn 1 (classic) and Yarn 2+ (berry) are different CLIs sharing one
+    // lockfile name, so no single table can be right for both. This entry is the
+    // BERRY baseline; `resolvePackageManagerConfig(pm, root)` swaps in the classic
+    // spelling for the fields that differ. Read yarn commands through that
+    // resolver, never off this table, at any site that knows which project
+    // directory it is acting on (#871).
+    //
+    // Fields with no major-specific difference — `run`, `install`, `addPkg`,
+    // `removePkg` — are shared, so the resolver leaves them alone.
     yarn: {
         run: "yarn",
+        // Berry-only: `dlx` does not exist in Yarn 1. Resolver → `npx` for classic.
         exec: "yarn dlx",
         install: "yarn install",
+        // Left at the classic spelling deliberately. Berry's `yarn install` takes no
+        // `--silent`, but this field has NO consumer anywhere in the codebase, and
+        // guessing berry's quiet spelling without a yarn binary to check against
+        // would trade a dead-config wart for a real one — the same call
+        // new-feature.sh's `pm_quiet_flag` already made for pnpm/bun. Known
+        // remaining hybrid, and the one field the resolver does not fix.
         installSilent: "yarn install --silent",
+        // Berry-only: Yarn 1 rejects `--immutable` and wants `--frozen-lockfile`.
+        // Resolver → YARN_CLASSIC_CI_INSTALL for classic.
+        ciInstall: "yarn install --immutable",
         addPkg: "yarn add",
         removePkg: "yarn remove",
-        updatePkg: "yarn upgrade",
+        // Berry renamed `yarn upgrade` to `yarn up`. This was the classic spelling
+        // until #871's follow-up, which made the whole entry berry-consistent —
+        // meaning the upgrade hint in version-check.ts was wrong for berry users.
+        // Resolver → `yarn upgrade` for classic.
+        updatePkg: "yarn up",
     },
     pnpm: {
         run: "pnpm run",
         exec: "pnpm dlx",
         install: "pnpm install",
         installSilent: "pnpm install --silent",
+        ciInstall: "pnpm install --frozen-lockfile",
         addPkg: "pnpm add",
         removePkg: "pnpm remove",
         updatePkg: "pnpm update",
     },
-    // Python package managers
+    // Python package managers. None of these has a distinct "frozen lockfile"
+    // install mode the way npm/pnpm/yarn/bun do (poetry install already honors
+    // poetry.lock), so ciInstall mirrors installSilent rather than inventing a flag.
     pip: {
         run: "python -m",
         exec: "python -m",
         install: "pip install",
         installSilent: "pip install -q",
+        ciInstall: "pip install -q",
         addPkg: "pip install",
         removePkg: "pip uninstall",
         updatePkg: "pip install --upgrade",
@@ -76,6 +106,7 @@ export const PM_CONFIG = {
         exec: "poetry run",
         install: "poetry install",
         installSilent: "poetry install -q",
+        ciInstall: "poetry install -q",
         addPkg: "poetry add",
         removePkg: "poetry remove",
         updatePkg: "poetry update",
@@ -85,6 +116,7 @@ export const PM_CONFIG = {
         exec: "uvx",
         install: "uv pip install",
         installSilent: "uv pip install -q",
+        ciInstall: "uv pip install -q",
         addPkg: "uv pip install",
         removePkg: "uv pip uninstall",
         updatePkg: "uv pip install --upgrade",
@@ -143,21 +175,228 @@ export async function detectPackageManager() {
 /**
  * Synchronous version of detectPackageManager for use in startup code.
  * Only checks JS lockfiles (not Python) since sequant is a Node.js tool.
+ *
+ * @param root Directory to look for lockfiles in. Defaults to the process cwd,
+ *        which is what startup code wants; callers that operate on a specific
+ *        repository (e.g. merge-check) must pass that repo's root instead.
  */
-export function detectPackageManagerSync() {
+export function detectPackageManagerSync(root = process.cwd()) {
     for (const { file, pm } of LOCKFILE_PRIORITY) {
-        if (existsSync(file)) {
+        if (existsSync(join(root, file))) {
             return pm;
         }
     }
     return "npm";
 }
+/**
+ * Resolve the package manager for a directory, preferring a declared value and
+ * falling back to live lockfile detection.
+ *
+ * The declared value is a *snapshot* — the worktree manifest records whatever
+ * `sequant init` saw, so it is absent on manifest-less or pre-init trees. The
+ * old spelling at those call sites was `(declared as keyof typeof PM_CONFIG)
+ * || "npm"`, which assumed npm whenever the snapshot was missing while the
+ * shell provisioning path (`templates/scripts/new-feature.sh`, PM-aware since
+ * #847) detected live from the lockfile. On a pnpm/yarn/bun project without a
+ * manifest the two paths therefore disagreed about the project's package
+ * manager — the dual-producer drift class of #833. Detecting here makes the
+ * TypeScript path agree with the shell path by construction (#870).
+ *
+ * The own-property membership test also retires that unchecked cast: a
+ * declared value outside `PackageManager` (a hand-edited manifest, a future
+ * `"npm@10"` spelling) used to index `PM_CONFIG` to `undefined` and throw on
+ * the next property access. Such a value now routes to detection instead.
+ * Python managers (`pip`/`poetry`/`uv`) are `PM_CONFIG` keys, so a declared
+ * Python manager still wins over the JS-only detector.
+ *
+ * The test is `hasOwnProperty`, deliberately not `in`: `in` walks the
+ * prototype chain, so `"toString"`, `"constructor"`, and `"__proto__"` would
+ * all pass it and be returned as if they named a package manager. Indexing
+ * `PM_CONFIG` with one yields an inherited function (or `Object.prototype`)
+ * whose `ciInstall` is `undefined`, crashing the caller on `.split(" ")` —
+ * reintroducing the exact failure this guard exists to prevent.
+ *
+ * @param declared Package manager recorded in the manifest, if any
+ * @param root Directory whose lockfiles decide the fallback
+ */
+export function resolvePackageManager(declared, root) {
+    if (declared && Object.prototype.hasOwnProperty.call(PM_CONFIG, declared)) {
+        return declared;
+    }
+    return detectPackageManagerSync(root);
+}
 /**
  * Get package manager command configuration
  */
 export function getPackageManagerCommands(pm) {
     return PM_CONFIG[pm];
 }
+/**
+ * Frozen install understood by Yarn 1 (classic).
+ *
+ * Yarn 2+ (berry) renamed this flag to `--immutable`, which is what
+ * `PM_CONFIG.yarn.ciInstall` carries. Both yarn spellings therefore exist, and
+ * both must appear in `new-feature.sh`'s `pm_ci_install()` table — the drift
+ * guard in `__tests__/new-feature-frozen-install.integration.test.ts` asserts
+ * exactly that, which is why this is a named export rather than a literal
+ * buried in `resolvePackageManagerConfig` (#871).
+ */
+export const YARN_CLASSIC_CI_INSTALL = "yarn install --frozen-lockfile";
+/**
+ * Yarn 1 (classic) spellings for every `PM_CONFIG.yarn` field whose berry value
+ * is wrong on classic. Applied by {@link resolvePackageManagerConfig}.
+ *
+ * `exec` is `npx` rather than a `yarn` subcommand because Yarn 1 has no
+ * `dlx` equivalent at all — npm ships with node, so `npx` is the run-a-binary
+ * -without-installing story a Yarn 1 project actually has.
+ *
+ * `installSilent` is deliberately absent — see the note on `PM_CONFIG.yarn`.
+ */
+const YARN_CLASSIC_OVERRIDES = {
+    ciInstall: YARN_CLASSIC_CI_INSTALL,
+    exec: "npx",
+    updatePkg: "yarn upgrade",
+};
+/**
+ * Bytes of `yarn.lock` scanned for its version header.
+ *
+ * Matches the `head -c` byte count in `new-feature.sh`'s `detect_yarn_major`.
+ * Keeping the scanned region identical is what makes the two implementations
+ * agree by construction rather than by inspection: a whole-file `grep` in the
+ * shell against a prefix-only read in TypeScript would silently diverge on a
+ * lockfile that happens to mention the header string further down.
+ */
+const YARN_LOCK_HEADER_BYTES = 1024;
+/**
+ * Read the `packageManager` pin's yarn major from `package.json`, if declared.
+ *
+ * Deliberately a regex rather than `JSON.parse`: the shell path cannot parse
+ * JSON without adding a `jq` dependency, so both paths match on text. A
+ * non-numeric pin (`yarn@stable`, `yarn@berry`) does not match and falls
+ * through to the next signal.
+ *
+ * Matching on text does NOT make the two paths agree for free — `\s*` here
+ * spans newlines and `.match` returns the first hit, neither of which a
+ * line-oriented `sed`/`grep` gives you. `detect_yarn_major` in
+ * `new-feature.sh` collapses newlines and takes the first match specifically
+ * to line up with this; see its comment for the two inputs that diverged
+ * before it did.
+ *
+ * @returns the declared major, or null when nothing is declared
+ */
+function readDeclaredYarnMajor(root) {
+    let raw;
+    try {
+        raw = readFileSync(join(root, "package.json"), "utf8");
+    }
+    catch {
+        return null;
+    }
+    const match = raw.match(/"packageManager"\s*:\s*"yarn@v?(\d+)/);
+    if (!match) {
+        return null;
+    }
+    // Every major above 1 is berry and shares berry's CLI surface, so the return
+    // type is the *behavioral* split (classic vs. berry), not the literal major.
+    return match[1] === "1" ? 1 : 2;
+}
+/** Read the first {@link YARN_LOCK_HEADER_BYTES} of `yarn.lock` ("" if absent). */
+function readYarnLockHeader(root) {
+    let fd;
+    try {
+        fd = openSync(join(root, "yarn.lock"), "r");
+    }
+    catch {
+        return "";
+    }
+    try {
+        const buffer = Buffer.alloc(YARN_LOCK_HEADER_BYTES);
+        const bytesRead = readSync(fd, buffer, 0, YARN_LOCK_HEADER_BYTES, 0);
+        return buffer.toString("utf8", 0, bytesRead);
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+/**
+ * Detect whether a directory is a Yarn 1 (classic) or Yarn 2+ (berry) project.
+ *
+ * Yarn 1 and berry both use `yarn.lock`, so `detectPackageManagerSync` cannot
+ * tell them apart — it answers "yarn", and this answers "which yarn". They are
+ * separate axes on purpose: adding a `yarn1` member to `PackageManager` would
+ * leak a synthetic name into settings (`pmRun`), doctor output, and templates
+ * for what is, today, a one-flag difference.
+ *
+ * Signals, in order of authority. The ordering follows a single rule: **flag
+ * acceptance is decided by the yarn binary that runs, not by the lockfile it
+ * reads.** So a Corepack pin outranks the lockfile header — a yarn-1 lockfile
+ * under `packageManager: "yarn@4"` still gets berry's `--immutable`, because
+ * yarn 4 is what will execute and yarn 4 rejects `--frozen-lockfile`.
+ *
+ *   1. `packageManager: "yarn@<major>"` in `package.json` — Corepack pins the
+ *      binary.
+ *   2. `.yarnrc.yml` — a berry-only config file; yarn 1 reads `.yarnrc`.
+ *   3. `yarn.lock` header — yarn 1 writes `# yarn lockfile v1`; berry writes
+ *      `__metadata:` instead.
+ *   4. Nothing recognizable → berry, the pre-#871 assumption. Staying with it
+ *      keeps a contentless or unreadable `yarn.lock` behaving exactly as it did
+ *      before this function existed.
+ *
+ * Mirrored by `detect_yarn_major` in `templates/scripts/new-feature.sh` (#871).
+ *
+ * @internal Exported for testing — production code should go through
+ * {@link resolvePackageManagerConfig}, whose whole job is to apply this answer.
+ * The export exists so the cross-path agreement test can run this and the shell
+ * mirror against the same fixtures, which is the gate keeping the two in step.
+ *
+ * @param root Directory to inspect. Defaults to the process cwd.
+ * @returns 1 for Yarn 1 (classic), 2 for Yarn 2+ (berry)
+ */
+export function detectYarnMajor(root = process.cwd()) {
+    const declared = readDeclaredYarnMajor(root);
+    if (declared !== null) {
+        return declared;
+    }
+    if (existsSync(join(root, ".yarnrc.yml"))) {
+        return 2;
+    }
+    if (readYarnLockHeader(root).includes("yarn lockfile v1")) {
+        return 1;
+    }
+    return 2;
+}
+/**
+ * Package manager commands for `pm`, with directory-dependent commands resolved
+ * against `root`.
+ *
+ * A drop-in replacement for `PM_CONFIG[pm]` at every call site that knows which
+ * project directory it is acting on. `PM_CONFIG.yarn` is the berry baseline, so
+ * for a Yarn 1 project this substitutes every field whose berry spelling is
+ * wrong on classic — `ciInstall`, `exec`, and `updatePkg` (see
+ * {@link YARN_CLASSIC_OVERRIDES}). Every other package manager, and every
+ * major-agnostic yarn field, is returned untouched.
+ *
+ * Returning the whole config rather than one resolved string is what makes that
+ * cheap: call sites that thread a `PackageManagerConfig` onward — merge-check's
+ * combined-branch test reads `ciInstall` for three commands and two user-facing
+ * messages — stay correct with a single-line change, and each newly discovered
+ * classic/berry split is one entry in the overrides table rather than a new
+ * call-site edit.
+ *
+ * Resolve against the tree you are about to act on, not against wherever the
+ * process started: `root` decides the answer, and in merge-check the combined
+ * (post-merge) state can disagree with the pre-merge one.
+ *
+ * @param pm Package manager identity, e.g. from `detectPackageManagerSync`
+ * @param root Directory whose files decide the directory-dependent commands
+ */
+export function resolvePackageManagerConfig(pm, root) {
+    const config = PM_CONFIG[pm];
+    if (pm !== "yarn" || detectYarnMajor(root) !== 1) {
+        return config;
+    }
+    return { ...config, ...YARN_CLASSIC_OVERRIDES };
+}
 export const STACKS = {
     nextjs: {
         name: "nextjs",

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

@@ -1,7 +1,47 @@
 /**
  * Template management - copy and process templates
  */
+/**
+ * How well a candidate path matches "the templates root of *this* package".
+ *
+ * `package-root` outranks `exists` because the two offsets are not mutually
+ * exclusive: from a source tree at `<repo>/src/lib`, the *compiled* offset
+ * resolves to `<repo>/../templates` — a directory one level **above** the repo.
+ * A bare existence probe would happily bind to an unrelated `templates/` that
+ * happens to sit beside the checkout. Requiring the candidate's parent to be
+ * the sequant package root removes that ambiguity without walking the tree.
+ */
+export type TemplatesCandidateRank = "package-root" | "exists" | "missing";
+/**
+ * Resolve the templates root relative to a module directory, given a ranking
+ * function.
+ *
+ * Split out from `getTemplatesDir` purely so both layouts are testable: a test
+ * cannot relocate `import.meta.url`, so without injection the "works from both
+ * layouts" assertion could only ever exercise whichever layout the test runner
+ * happens to use.
+ *
+ * Resolution order: the first `package-root` candidate, else the first that
+ * merely `exists` (keeps any layout that works today working, even one whose
+ * package root is not where we expect), else the **compiled** offset — so the
+ * caller's error message names the canonical expected location rather than a
+ * source-tree guess.
+ */
+export declare function resolveTemplatesDirFrom(baseDir: string, rank: (candidate: string) => TemplatesCandidateRank): string;
 export declare function getTemplatesDir(): string;
+/**
+ * Resolve the templates root and fail loudly when it does not exist.
+ *
+ * A missing templates *root* means the install is broken: every `copyDir` call
+ * below would hit `copyDir`'s per-directory ENOENT skip, no-op, and let the
+ * caller print a success message over an empty tree (#822). That skip is
+ * deliberate for individual subdirectories — a stack may legitimately ship
+ * without `memory/` — but it must not absorb the whole source tree.
+ *
+ * Throws rather than printing so the lib layer stays free of presentation;
+ * commands catch and render.
+ */
+export declare function assertTemplatesDirExists(): Promise<string>;
 /**
  * Process template variables in content
  */
@@ -52,6 +92,25 @@ export interface TemplateChange {
     /** Unified-ish diff (installed → rendered), only set for `modified` */
     diff?: string;
 }
+/**
+ * Map a bundled template path to the location `copyTemplates` installs it to,
+ * or `null` for templates the copy/diff cycle does not manage.
+ *
+ * This mirrors the routing in `copyTemplates` (write time) so
+ * `computeTemplateChanges` (diff time) can never report drift on a file init
+ * deliberately places elsewhere — `.claude/mcp.json`, `.claude/relay/*`, and
+ * `.claude/scripts/*` read as phantom "new" files on every fresh install when
+ * the diff assumed a flat `.claude/<relpath>` layout. #708 gives the same
+ * guarantee for the template *variables*; this covers the *destinations*.
+ *
+ * - `templates/mcp.json` → `null`: the project `.mcp.json` is generated and
+ *   version-pinned by `mcp-config.ts` (`syncSequantMcpPin`), never copied.
+ * - `templates/relay/` → `null`: not installed by `copyTemplates`.
+ * - `templates/scripts/` → `scripts/dev/`: symlinked on POSIX, copied on
+ *   Windows / `--no-symlinks`.
+ * - everything else → `.claude/<relpath>`.
+ */
+export declare function templateDestination(templatePath: string): string | null;
 /**
  * Compare bundled template content against what's installed under `.claude/`.
  *
@@ -83,6 +142,15 @@ export interface CopyTemplatesOptions {
     noSymlinks?: boolean;
     /** Force replacement of existing files/symlinks */
     force?: boolean;
+    /**
+     * Opt in to overwriting in-place customizations (files in `CUSTOMIZABLE_FILES`,
+     * e.g. the constitution) that already exist and differ from the rendered
+     * template. Deliberately separate from `force`: `force` refreshes the managed
+     * skills/agents/hooks trees, but that always-on tree overwrite must NOT imply
+     * consent to clobber user-owned files. Only an explicit user `--force` sets
+     * this. A missing or identical customizable file is written regardless (#814).
+     */
+    overwriteCustomizable?: boolean;
     /** Additional stacks to include in constitution notes (for multi-stack projects) */
     additionalStacks?: string[];
 }
@@ -102,4 +170,10 @@ export declare function symlinkDir(srcDir: string, destDir: string, options?: {
 export declare function copyTemplates(stack: string, tokens?: Record<string, string>, options?: CopyTemplatesOptions): Promise<{
     scriptsSymlinked: boolean;
     symlinkResults?: SymlinkResult[];
+    /**
+     * Customizable files that already existed, differed from the rendered
+     * template, and were left untouched because `overwriteCustomizable` was not
+     * set. Normalized to forward slashes so callers can report them verbatim.
+     */
+    preservedCustomizable: string[];
 }>;

package/dist/src/lib/templates.js

@@ -1,7 +1,8 @@
 /**
  * Template management - copy and process templates
  */
-import { readdir, chmod } from "fs/promises";
+import { readdir, chmod, stat } from "fs/promises";
+import { existsSync, readFileSync } from "fs";
 import { join, dirname, relative, isAbsolute } from "path";
 import { fileURLToPath } from "url";
 import { diffLines } from "diff";
@@ -11,18 +12,122 @@ const SKILLS_VERSION_PATH = ".claude/skills/.sequant-version";
 import { getStackConfig, getStackNotes, getMultiStackNotes } from "./stacks.js";
 import { isNativeWindows } from "./system.js";
 import { getProjectName } from "./project-name.js";
+/**
+ * Offsets from this module's directory to the bundled `templates/` root, in
+ * probe order. This module lives at `src/lib/templates.ts`, so it sits three
+ * levels below the package root once compiled (`dist/src/lib/templates.js`) but
+ * only two when executed straight from source under `tsx` (`src/lib/`).
+ *
+ * The compiled offset is listed first so consumers — who always run the compiled
+ * binary — keep byte-identical behavior. See #822.
+ */
+const TEMPLATES_DIR_OFFSETS = [
+    ["..", "..", "..", "templates"], // compiled: dist/src/lib → <pkg>/templates
+    ["..", "..", "templates"], // source (tsx): src/lib → <repo>/templates
+];
+/**
+ * Resolve the templates root relative to a module directory, given a ranking
+ * function.
+ *
+ * Split out from `getTemplatesDir` purely so both layouts are testable: a test
+ * cannot relocate `import.meta.url`, so without injection the "works from both
+ * layouts" assertion could only ever exercise whichever layout the test runner
+ * happens to use.
+ *
+ * Resolution order: the first `package-root` candidate, else the first that
+ * merely `exists` (keeps any layout that works today working, even one whose
+ * package root is not where we expect), else the **compiled** offset — so the
+ * caller's error message names the canonical expected location rather than a
+ * source-tree guess.
+ */
+export function resolveTemplatesDirFrom(baseDir, rank) {
+    const candidates = TEMPLATES_DIR_OFFSETS.map((offset) => join(baseDir, ...offset));
+    const ranked = candidates.map((candidate) => ({
+        candidate,
+        rank: rank(candidate),
+    }));
+    return (ranked.find((c) => c.rank === "package-root")?.candidate ??
+        ranked.find((c) => c.rank === "exists")?.candidate ??
+        candidates[0]);
+}
+/**
+ * Rank a candidate by checking whether it exists and whether its parent is the
+ * sequant package root. Anchoring on `package.json` mirrors how every other
+ * root resolver in this codebase locates the package (`version.ts`,
+ * `manifest.ts`, `bin/preflight.ts`).
+ */
+function rankTemplatesCandidate(candidate) {
+    if (!existsSync(candidate)) {
+        return "missing";
+    }
+    try {
+        const pkg = JSON.parse(readFileSync(join(candidate, "..", "package.json"), "utf-8"));
+        if (pkg.name === "sequant") {
+            return "package-root";
+        }
+    }
+    catch {
+        // No readable/parseable package.json beside it — still a usable directory,
+        // just not a positively identified package root.
+    }
+    return "exists";
+}
+/**
+ * Memoized bundled-templates path. Resolution is now stat-backed rather than a
+ * pure string join, and `getTemplateContent` calls it once per template file
+ * during a drift scan — ~2ms per scan uncached, on a pre-flight path #708
+ * deliberately keeps in the 2-5ms range. The install layout cannot change
+ * within a process, so caching it is safe. Only the *bundled* resolution is
+ * cached; the env override is re-read every call, so tests that set and unset
+ * `SEQUANT_TEMPLATES_DIR` are unaffected.
+ */
+let cachedBundledTemplatesDir;
 // Get the package templates directory
 export function getTemplatesDir() {
     // Allow overriding the templates source (used by tests; also lets the dir be
-    // relocated without relying on the compiled-output layout below).
+    // relocated without relying on the compiled-output layout below). Returned
+    // verbatim — the override is authoritative and is never probed, so a bad
+    // value surfaces at `assertTemplatesDirExists` rather than silently falling
+    // back to the bundled tree.
     if (process.env.SEQUANT_TEMPLATES_DIR) {
         return process.env.SEQUANT_TEMPLATES_DIR;
     }
-    const __dirname = dirname(fileURLToPath(import.meta.url));
-    // Compiled structure: dist/src/lib/templates.js
-    // So we need ../../../templates to reach project root templates/
-    const devPath = join(__dirname, "..", "..", "..", "templates");
-    return devPath;
+    if (cachedBundledTemplatesDir === undefined) {
+        const __dirname = dirname(fileURLToPath(import.meta.url));
+        cachedBundledTemplatesDir = resolveTemplatesDirFrom(__dirname, rankTemplatesCandidate);
+    }
+    return cachedBundledTemplatesDir;
+}
+/**
+ * Resolve the templates root and fail loudly when it does not exist.
+ *
+ * A missing templates *root* means the install is broken: every `copyDir` call
+ * below would hit `copyDir`'s per-directory ENOENT skip, no-op, and let the
+ * caller print a success message over an empty tree (#822). That skip is
+ * deliberate for individual subdirectories — a stack may legitimately ship
+ * without `memory/` — but it must not absorb the whole source tree.
+ *
+ * Throws rather than printing so the lib layer stays free of presentation;
+ * commands catch and render.
+ */
+export async function assertTemplatesDirExists() {
+    const templatesDir = getTemplatesDir();
+    // A *directory* check, not a bare existence check: a stray file at that path
+    // would pass `access()` and then fail deeper in `readdir` with the same silent
+    // ENOTDIR-shaped confusion this guard exists to prevent.
+    let isDirectory;
+    try {
+        isDirectory = (await stat(templatesDir)).isDirectory();
+    }
+    catch {
+        isDirectory = false;
+    }
+    if (isDirectory) {
+        return templatesDir;
+    }
+    throw new Error(`Bundled templates directory not found: ${templatesDir}\n` +
+        "This usually means the Sequant install is incomplete or was run from an unexpected layout.\n" +
+        "Reinstall sequant, or set SEQUANT_TEMPLATES_DIR to the templates/ directory.");
 }
 /**
  * Process template variables in content
@@ -112,6 +217,35 @@ export async function buildTemplateVariables(stack, tokens, options = {}) {
         STACK_NOTES: stackNotes,
     };
 }
+/**
+ * Map a bundled template path to the location `copyTemplates` installs it to,
+ * or `null` for templates the copy/diff cycle does not manage.
+ *
+ * This mirrors the routing in `copyTemplates` (write time) so
+ * `computeTemplateChanges` (diff time) can never report drift on a file init
+ * deliberately places elsewhere — `.claude/mcp.json`, `.claude/relay/*`, and
+ * `.claude/scripts/*` read as phantom "new" files on every fresh install when
+ * the diff assumed a flat `.claude/<relpath>` layout. #708 gives the same
+ * guarantee for the template *variables*; this covers the *destinations*.
+ *
+ * - `templates/mcp.json` → `null`: the project `.mcp.json` is generated and
+ *   version-pinned by `mcp-config.ts` (`syncSequantMcpPin`), never copied.
+ * - `templates/relay/` → `null`: not installed by `copyTemplates`.
+ * - `templates/scripts/` → `scripts/dev/`: symlinked on POSIX, copied on
+ *   Windows / `--no-symlinks`.
+ * - everything else → `.claude/<relpath>`.
+ */
+export function templateDestination(templatePath) {
+    const normalized = templatePath.replace(/\\/g, "/");
+    if (normalized === "templates/mcp.json")
+        return null;
+    if (normalized.startsWith("templates/relay/"))
+        return null;
+    if (normalized.startsWith("templates/scripts/")) {
+        return normalized.replace("templates/scripts/", "scripts/dev/");
+    }
+    return normalized.replace("templates/", ".claude/");
+}
 /**
  * Compare bundled template content against what's installed under `.claude/`.
  *
@@ -126,12 +260,13 @@ export async function computeTemplateChanges(stack, tokens, options = {}) {
     const templateFiles = await listTemplateFiles();
     const changes = [];
     for (const templatePath of templateFiles) {
-        // Normalize separators first: listTemplateFiles builds paths with the OS
-        // separator (backslashes on Windows), but the prefix swap and the .local/
-        // and customizable-file checks below all assume forward slashes (#708).
-        const localPath = templatePath
-            .replace(/\\/g, "/")
-            .replace("templates/", ".claude/");
+        // templateDestination normalizes separators (listTemplateFiles builds
+        // paths with the OS separator, backslashes on Windows — #708) and applies
+        // the same routing copyTemplates uses at write time.
+        const localPath = templateDestination(templatePath);
+        if (localPath === null) {
+            continue;
+        }
         // Skip .local files (user customizations are never overwritten)
         if (localPath.includes(".local/")) {
             continue;
@@ -165,8 +300,11 @@ export async function computeTemplateChanges(stack, tokens, options = {}) {
         // auto-skipped above because it lives under `.local/`. The directive sits at
         // the top, not end-of-file, so it fires reliably even in 3000-line skills.
         // See docs/guides/customization.md.
-        const localOverridePath = localPath.replace(".claude/", ".claude/.local/");
-        const hasLocalOverride = await fileExists(localOverridePath);
+        // Only `.claude/` files have `.local/` twins; for `scripts/dev/` paths the
+        // replace would be a no-op and the file would shadow itself as its own
+        // "override".
+        const hasLocalOverride = localPath.startsWith(".claude/") &&
+            (await fileExists(localPath.replace(".claude/", ".claude/.local/")));
         if (hasLocalOverride || isCustomizableFile(localPath)) {
             changes.push({
                 path: localPath,
@@ -293,6 +431,9 @@ export async function copyTemplates(stack, tokens, options = {}) {
     const templatesDir = getTemplatesDir();
     // Single source of truth for template variables (shared with the diff path)
     const variables = await buildTemplateVariables(stack, tokens, options);
+    // Customizable files skipped on the write path (see copyDir), surfaced to the
+    // caller so it can report them without a second diff pass (#814).
+    const preservedCustomizable = [];
     async function copyDir(srcDir, destDir) {
         try {
             const entries = await readdir(srcDir, { withFileTypes: true });
@@ -307,6 +448,20 @@ export async function copyTemplates(stack, tokens, options = {}) {
                     // Read, process, and write
                     let content = await readFile(srcPath);
                     content = processTemplate(content, variables);
+                    // Protect in-place customizations on the write path. A file in
+                    // CUSTOMIZABLE_FILES that already exists and differs from the
+                    // rendered template is preserved unless the caller explicitly opted
+                    // in via `overwriteCustomizable`. A missing file (fresh install) or
+                    // an identical one falls through and is written as usual (#814).
+                    if (!options.overwriteCustomizable &&
+                        isCustomizableFile(destPath) &&
+                        (await fileExists(destPath))) {
+                        const existing = await readFile(destPath);
+                        if (existing !== content) {
+                            preservedCustomizable.push(destPath.replace(/\\/g, "/"));
+                            continue;
+                        }
+                    }
                     await writeFile(destPath, content);
                     // Make shell scripts executable
                     if (entry.name.endsWith(".sh")) {
@@ -352,5 +507,5 @@ export async function copyTemplates(stack, tokens, options = {}) {
     }
     // Write skills version marker for sync detection
     await writeFile(SKILLS_VERSION_PATH, getPackageVersion());
-    return { scriptsSymlinked, symlinkResults };
+    return { scriptsSymlinked, symlinkResults, preservedCustomizable };
 }