sequant 2.9.0 → 2.11.0

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

@@ -37,6 +37,7 @@ export interface PackageManagerConfig {
     exec: string;
     install: string;
     installSilent: string;
+    ciInstall: string;
     addPkg: string;
     removePkg: string;
     updatePkg: string;
@@ -56,12 +57,120 @@ export declare function detectPackageManager(): Promise<PackageManager | null>;
 /**
  * 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 declare function detectPackageManagerSync(root?: string): PackageManager;
+/**
+ * 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 declare function detectPackageManagerSync(): PackageManager;
+export declare function resolvePackageManager(declared: string | undefined, root: string): PackageManager;
 /**
  * Get package manager command configuration
  */
 export declare function getPackageManagerCommands(pm: PackageManager): PackageManagerConfig;
+/**
+ * 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 declare const YARN_CLASSIC_CI_INSTALL = "yarn install --frozen-lockfile";
+/**
+ * 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 declare function detectYarnMajor(root?: string): 1 | 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 declare function resolvePackageManagerConfig(pm: PackageManager, root: string): PackageManagerConfig;
 export interface StackConfig {
     name: string;
     displayName: string;

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[];
 }>;