claude-toolkit 0.15.0 → 0.17.0-rc.1

package/CHANGELOG.md

@@ -1,5 +1,35 @@
 # Changelog
 
+## 0.17.0 (unreleased)
+
+Nothing runs at install time any more. The `postinstall` script that regenerated `.claude/` is gone; projects opt in with one line in their own `package.json`, and the new `claude-toolkit refresh` does the work. The package also stops shipping `docs/`, and releases move to npm trusted publishing behind a tarball guard.
+
+**BREAKING:** installing or upgrading claude-toolkit no longer regenerates `.claude/`. After upgrading, run `bunx claude-toolkit` once, then add to your `package.json` scripts:
+
+    "prepare": "claude-toolkit refresh || exit 0"
+
+This line is **required** when `.claude/` is gitignored (the README's recommended setup): without it a fresh clone has no `.claude/` until someone runs `bunx claude-toolkit`. Yarn 2+ never runs `prepare` for your own project — use `"postinstall"` there. npm runs `prepare` only on a plain `npm install` and pnpm skips it on `pnpm add`; after those, run `bunx claude-toolkit refresh`. If you added `claude-toolkit` to Bun's `trustedDependencies` or pnpm's `onlyBuiltDependencies`, remove it.
+
+- feat!: remove the install-time `postinstall` script (`bin/postinstall.mjs`) and the internal `postinstall` command. The package now ships no install scripts and no `child_process` or `process.env` use.
+- feat: `claude-toolkit refresh [dir]` regenerates `.claude/` only when the installed toolkit version differs from `.claude/.toolkit-version`; the up-to-date path never imports the config. It never creates the config and never scaffolds `biome.json`/`tsconfig.json`; a config that fails to load exits 1. Accepts `claude-toolkit.config.ts` or `claude-toolkit.config.js`.
+- feat: every non-quiet `bunx claude-toolkit` run ends with the `prepare` line until `package.json` has a script running `claude-toolkit refresh` — with a named-script variant when `prepare` is already taken, `postinstall` for Yarn 2+ (`.yarnrc.yml`), the npm and pnpm cases where `prepare` does not run, and a leading line when upgrading from 0.16 or earlier. The CLI never edits `package.json`.
+- fix(settings): the protected-branch guard blocked every edit on every branch when two or more `git.protectedBranches` were configured (`[` does not accept `&&`). It is now a `case` statement; branch names are validated against `^[A-Za-z0-9._/][A-Za-z0-9._/-]*$`, and an invalid name fails generation with an error naming it. An empty list now generates no guard instead of blocking every edit.
+- build: stop shipping `docs/` (about 270 KB); the README links the docs on GitHub. `prepare` runs the husky 9 binary instead of `npx husky`. Dropped the dead pre-0.11 `skill-eval.sh` cleanup.
+- ci: publish with npm trusted publishing (OIDC, automatic provenance, no token secret); prerelease versions go to the `next` dist-tag, and the workflow can be re-run by hand on a tag. Before publishing it runs typecheck, lint and tests, strips `prepare`, and runs `check:pack --publish` (no install scripts, no shell or environment access in shipped code, no `docs/`) and `check:smoke` (installs the packed tarball and runs `refresh`). A new CI workflow runs the checks on every push and pull request.
+- build: the post-commit version hook no longer bumps prerelease versions (it turned `0.17.0-rc.0` into `0.17.NaN`); `@types/bun` is pinned to `^1.3.11`.
+- docs: README documents `refresh`, the `prepare` opt-in per package manager, upgrading from 0.16, and the release-candidate flow; the auto-format, auto-test and type-check hooks are marked not yet functional (fixed in 0.18.0). CLAUDE.md drops the postinstall description and corrects the post-commit and `core/hooks` notes.
+- fix(package): `bin` is now `bin/cli.ts` without a leading `./`. npm 11.10 and later silently drop a `./`-prefixed `bin` entry at publish time (`npm pack` keeps it), which would have shipped 0.17.0 without its CLI; `check:pack` now rejects such paths. `repository.url` uses the `git+https` form npm normalizes to.
+
+## 0.16.0 (2026-08-08)
+
+`ct-typescript-conventions` now selects a compiler as well as types: prefer the TypeScript 7 native compiler where a project already ships it, fall back cleanly where it does not, and never upgrade a project unprompted. Availability-aware in the same spirit as `ct-esnext-idioms`.
+
+- feat: prioritise the TypeScript 7 native compiler in `ct-typescript-conventions` — TS7 reached GA on 2026-07-08 as `typescript@7.0.2`, with Microsoft reporting 8x–12x faster full builds. The skill detects the *installed* version (`require('typescript/package.json').version`) rather than the declared semver range, which `overrides`/`resolutions`/catalogs routinely defeat, and names the three detection traps: the binary is `tsc` not `tsgo` (that was the pre-GA `@typescript/native-preview` name), range-sniffing is unreliable, and an API probe gives a false negative because TS7 exposes only `version`/`versionMajorMinor`.
+- feat: document when *not* to switch — TS7.0 ships no stable programmatic API, so `typescript-eslint`, `ts-jest`, `ts-node`, `vue-tsc`, `svelte-check`, `@astrojs/check` and `@angular/compiler-cli` break at install or lint time rather than at `tsc --noEmit`, which means a green type-check proves nothing. The skill prescribes the documented side-by-side alias install instead of a downgrade.
+- feat: add the TS7 `tsconfig.json` deltas — the options TS7 rejects outright (`ignoreDeprecations` no longer silences them), plus the two changed defaults behind most real breakage. Verified empirically against 5.9.3 / 6.0.3 / 7.0.2: both defaults land in 6.0 and carry forward, `types` fails `TS2591` even with `@types/node` installed, `rootDir` only bites when an `outDir` is set, and `types: ["*"]` is `TS2688` on 5.x — so no literal value is safe across majors.
+- feat: skill triggers now fire on typecheck, tsconfig, and compiler work — added the `tsc`, `tsgo`, `tsconfig`, `typecheck` and `compiler` keywords, the `**/tsconfig*.json` path pattern, and intents for running a typecheck or upgrading TypeScript.
+- docs: TSConfig cheat sheet gains a TypeScript 7 delta section; the skill's new remit is reflected in the generated skills index, README, and docs index.
+
 ## 0.15.0 (2026-07-04)
 
 Two new authoring-convention assets — an opt-in `esnext` stack and an always-on `ct-code-style` core skill — plus Biome enforcement of the mechanically-checkable style rules.

package/README.md

@@ -18,12 +18,31 @@ bun add -d claude-toolkit
 bunx claude-toolkit
 ```
 
+Then add one line to your `package.json` so `.claude/` is rebuilt after toolkit upgrades and on fresh clones. It is **required** when `.claude/` is gitignored (the setup recommended below):
+
+```json
+{
+  "scripts": {
+    "prepare": "claude-toolkit refresh || exit 0"
+  }
+}
+```
+
+claude-toolkit itself runs nothing at install time: this is your project's own script, and `|| exit 0` keeps installs working where bun is missing. If `prepare` is already taken, add `"claude-toolkit:refresh": "claude-toolkit refresh || exit 0"` and append `&& bun run claude-toolkit:refresh` (or `npm run`/`pnpm run`/`yarn run`) to your `prepare`. Until one of these is in place, `bunx claude-toolkit` prints the exact line for your project.
+
+When your package manager runs it:
+
+- **bun** runs `prepare` on `bun install`, `bun add` and `bun update`.
+- **npm** runs it only on a plain `npm install`. After `npm install <pkg>` or `npm update`, run `bunx claude-toolkit refresh`.
+- **pnpm** runs it on `pnpm install` and `pnpm update`, not on `pnpm add`. After `pnpm add`, run `bunx claude-toolkit refresh`.
+- **Yarn 2+** never runs `prepare` for your own project. Use `"postinstall": "claude-toolkit refresh || exit 0"` instead; it runs whenever your dependencies change. If you publish the package, don't ship that `postinstall` — run `bunx claude-toolkit refresh` by hand instead.
+
 ## How It Works
 
 1. Run `bunx claude-toolkit` — on the first run it creates a `claude-toolkit.config.ts` at your project root, pre-filled with the stacks it detects
 2. It generates a `.claude/` directory with skills, hooks, commands, and agents — regenerated cleanly each run, so stacks you remove leave no stale skills behind
 3. Claude Code picks up the generated config automatically
-4. `.claude/` regenerates automatically on install whenever the toolkit version changes, so upgrades land without running anything
+4. After a toolkit upgrade, the `prepare` line from Quick Start runs `claude-toolkit refresh`, which rebuilds `.claude/` only when the installed version differs from the one that generated it. Nothing else runs at install time
 
 ```ts
 import { defineConfig } from "claude-toolkit";
@@ -46,13 +65,14 @@ export default defineConfig({
 
 ## CLI Commands
 
-| Command                        | Description                                                             |
-| ------------------------------ | ----------------------------------------------------------------------- |
-| `bunx claude-toolkit`          | Create the config if missing, then (re)generate `.claude/`. Idempotent. |
-| `bunx claude-toolkit --update` | Same, and also add newly-detected stacks to your config                 |
-| `bunx claude-toolkit help`     | Show available commands                                                 |
+| Command                             | Description                                                                                          |
+| ----------------------------------- | ---------------------------------------------------------------------------------------------------- |
+| `bunx claude-toolkit`               | Create the config if missing, then (re)generate `.claude/`. Idempotent.                              |
+| `bunx claude-toolkit --update`      | Same, and also add newly-detected stacks to your config                                              |
+| `bunx claude-toolkit refresh [dir]` | Regenerate `.claude/` only if the toolkit version changed. Never creates the config or other files. |
+| `bunx claude-toolkit help`          | Show available commands                                                                              |
 
-Aliases (back-compat): `init` is a friendly name for the bare command, `update` equals `--update`, and `sync` is deprecated — use the bare command. `.claude/` also regenerates automatically on install when the toolkit version changes.
+Aliases (back-compat): `init` is a friendly name for the bare command, `update` equals `--update`, and `sync` is deprecated — use the bare command. `refresh` is what your `prepare` script runs: with no config it prints one setup line and exits 0, a config that fails to load exits 1, and `--quiet` silences it.
 
 ## Stack Auto-Detection
 
@@ -91,7 +111,7 @@ Generated .claude/ with 4 stack(s) and 4 core skills
 
 Stacks in your config that are no longer detected are reported but left unchanged (remove them manually if intended).
 
-**Automatic regeneration** — when the installed toolkit version changes, `.claude/` is regenerated on install automatically (via a `postinstall` hook), so a toolkit upgrade ships its updated skills without you running anything. This only refreshes the generated `.claude/` — it never creates or edits committed files.
+**Keeping `.claude/` in sync** — `claude-toolkit refresh` compares the installed toolkit version with `.claude/.toolkit-version` and regenerates only when they differ; when they match it returns without loading your config. It never creates the config and never scaffolds `biome.json`/`tsconfig.json`. Run it from your `prepare` script (see Quick Start).
 
 ## Available Stacks
 
@@ -113,15 +133,15 @@ Stacks in your config that are no longer detected are reported but left unchange
 
 - **Skill Evaluation Engine** — Analyzes prompts and suggests relevant skills
 - **Main Branch Protection** — Prevents accidental edits on protected branches
-- **Auto-formatting** — Formats files after edits
-- **Auto-testing** — Runs related tests when test files change
-- **Type checking** — Checks TypeScript types on save
+- **Auto-formatting** — Formats files after edits _(not yet functional — fixed in 0.18.0)_
+- **Auto-testing** — Runs related tests when test files change _(not yet functional — fixed in 0.18.0)_
+- **Type checking** — Checks TypeScript types on save _(not yet functional — fixed in 0.18.0)_
 
 ### Core Skills
 
 - `ct-systematic-debugging` — Four-phase debugging methodology
 - `ct-testing-patterns` — TDD workflow and patterns
-- `ct-typescript-conventions` — TypeScript strict mode best practices
+- `ct-typescript-conventions` — TypeScript strict mode best practices, and preferring the TS7 native compiler where available
 - `ct-verification-before-completion` — Evidence-based completion claims
 - `ct-code-style` — Code structure & style: guard clauses, lookup tables, no magic values
 
@@ -149,6 +169,8 @@ Add `.claude/` to your `.gitignore` (it's generated, not tracked):
 CLAUDE.local.md
 ```
 
+With `.claude/` gitignored, a fresh clone has no `.claude/` until something generates it, so the `prepare` line from Quick Start is **required** in this setup.
+
 Track the config file and CLAUDE.md:
 
 ```
@@ -156,9 +178,17 @@ claude-toolkit.config.ts  # tracked — your project's Claude config
 CLAUDE.md                 # tracked — project-specific documentation
 ```
 
+## Upgrading from 0.16 or earlier
+
+0.17.0 removed the install-time `postinstall` script: installing or upgrading claude-toolkit no longer runs anything. After upgrading:
+
+1. Run `bunx claude-toolkit` once to regenerate `.claude/`.
+2. Add `"prepare": "claude-toolkit refresh || exit 0"` to your `package.json` scripts (the CLI prints the exact line for your project, including the Yarn 2+ and existing-`prepare` variants).
+3. If you added `claude-toolkit` to Bun's `trustedDependencies` or pnpm's `onlyBuiltDependencies` so its install script could run, remove it — there is no install script any more.
+
 ## Documentation
 
-Full reference documentation for all skills, commands, and agents is available in the [`docs/`](docs/README.md) directory.
+Full reference documentation for all skills, commands, and agents lives in the [`docs/` directory on GitHub](https://github.com/william-queant/claude-toolkit/blob/main/docs/README.md). It is not included in the npm package.
 
 ## Versioning
 
@@ -167,7 +197,15 @@ Version bumps are derived from your commit messages (Conventional Commits) by a
 - `feat:` → minor · `fix:` / `perf:` → patch · `feat!:` / `BREAKING CHANGE` → major (capped to minor while pre-1.0)
 - `docs:` / `chore:` / `refactor:` / `style:` / `test:` / `ci:` / `build:` → no version change
 
-To set an exact version deliberately (a re-baseline, or `1.0.0`), edit `package.json` and prepend a `CHANGELOG.md` entry, then commit with `SKIP_POST_COMMIT=1` so the hook doesn't re-bump, and tag `vX.Y.Z`. Publishing to npm happens automatically when a GitHub Release is published (see `.github/workflows/publish.yml`).
+To set an exact version deliberately (a re-baseline, a release candidate, or `1.0.0`), edit `package.json` and the `CHANGELOG.md` entry, then commit with `SKIP_POST_COMMIT=1` so the hook doesn't re-bump. While `package.json` holds a prerelease version (for example `0.17.0-rc.0`), the hook never bumps.
+
+Releases go through a release candidate:
+
+1. Set `X.Y.0-rc.N`, commit with `SKIP_POST_COMMIT=1`, and publish a GitHub **pre-release** for tag `vX.Y.0-rc.N`. `.github/workflows/publish.yml` publishes it to the `next` dist-tag.
+2. Verify the published candidate; fix and cut `rc.N+1` if needed.
+3. Set `X.Y.0`, commit with `SKIP_POST_COMMIT=1`, and publish a normal GitHub Release for `vX.Y.0`. It goes to `latest`.
+
+Publishing uses npm trusted publishing (OIDC): there is no npm token secret, and provenance is automatic. Before publishing, the workflow runs typecheck, lint and tests, strips the dev-only `prepare` script, then runs `bun run check:pack --publish` (no install scripts, no shell or environment access in shipped code, no `docs/`) and `bun run check:smoke` (installs the packed tarball and runs `claude-toolkit refresh`). `.github/workflows/ci.yml` runs typecheck, lint, tests, `check:pack` and `check:smoke` on every push and pull request.
 
 ## Development
 
@@ -175,4 +213,7 @@ To set an exact version deliberately (a re-baseline, or `1.0.0`), edit `package.
 git clone https://github.com/william-queant/claude-toolkit.git
 cd claude-toolkit
 bun install
+bun test               # test suite
+bun run check:pack     # tarball guard
+bun run check:smoke    # pack, install into a temp project, run refresh
 ```

package/bin/cli.ts

@@ -6,24 +6,34 @@
  * One idempotent command does it all:
  *   bunx claude-toolkit            Create the config if missing, then (re)generate .claude/
  *   bunx claude-toolkit --update   Also pull newly-detected stacks into the config
+ *   bunx claude-toolkit refresh    Regenerate .claude/ only if the toolkit version changed
  *
  * Aliases / back-compat:
  *   init     Friendly name for the first run (same as the bare command)
  *   update   Same as `--update`
  *   sync     Deprecated alias of the bare command
  *
- * .claude/ is also regenerated automatically on install when the installed
- * toolkit version changes (see bin/postinstall.mjs).
+ * Nothing runs at install time. Consumers keep .claude/ in sync by adding
+ * "prepare": "claude-toolkit refresh || exit 0" to their own package.json scripts;
+ * the bare command prints that hint until they do.
  */
 
 import { existsSync } from "node:fs";
 import { readFile, writeFile } from "node:fs/promises";
-import { join, resolve } from "node:path";
+import { basename, join, resolve } from "node:path";
 import { detectStacks } from "../src/detect.js";
-import { generate } from "../src/generator.js";
+import { generate, readMarker, readToolkitVersion } from "../src/generator.js";
+import { buildRefreshHint } from "../src/refresh-hint.js";
 import type { ClaudeToolkitConfig } from "../src/types.js";
 
 const CONFIG_FILENAME = "claude-toolkit.config.ts";
+/** Config files `loadConfig` and `refresh` accept, in lookup order. */
+const CONFIG_FILENAMES = [CONFIG_FILENAME, "claude-toolkit.config.js"];
+
+/** Path of the project's config file, or null when there is none. */
+function findConfigPath(projectDir: string): string | null {
+	return CONFIG_FILENAMES.map((name) => join(projectDir, name)).find((p) => existsSync(p)) ?? null;
+}
 
 /** Build a `stacks: [...]` literal for injection into the config file. */
 function buildStacksLiteral(stacks: string[]): string {
@@ -44,16 +54,16 @@ async function updateConfigStacks(configPath: string, stacks: string[]): Promise
 }
 
 async function loadConfig(projectDir: string): Promise<ClaudeToolkitConfig> {
-	const configPath = join(projectDir, CONFIG_FILENAME);
-	if (!existsSync(configPath)) {
-		throw new Error(`Config not found: ${configPath}\nRun "bunx claude-toolkit" first.`);
+	const configPath = findConfigPath(projectDir);
+	if (configPath === null) {
+		throw new Error(`Config not found in ${projectDir}\nRun "bunx claude-toolkit" first.`);
 	}
 	let mod: { default?: ClaudeToolkitConfig };
 	try {
 		mod = await import(configPath);
 	} catch (err) {
 		throw new Error(
-			`Failed to load ${CONFIG_FILENAME}. Make sure claude-toolkit is installed in this project ` +
+			`Failed to load ${basename(configPath)}. Make sure claude-toolkit is installed in this project ` +
 				`(e.g. "bun add -d claude-toolkit"), then run "bunx claude-toolkit" again.\n  ${(err as Error).message}`,
 		);
 	}
@@ -104,11 +114,14 @@ interface RunOptions {
 async function run(projectDir: string, options: RunOptions = {}): Promise<void> {
 	const { update = false, quiet = false } = options;
 	const log = quiet ? (_msg = "") => {} : (msg = "") => console.log(msg);
-	const configPath = join(projectDir, CONFIG_FILENAME);
+	const existingConfig = findConfigPath(projectDir);
+	const configPath = existingConfig ?? join(projectDir, CONFIG_FILENAME);
+	// Read before generate() rewrites it: a pre-0.17 marker means this run is an upgrade.
+	const previousVersion = await readMarker(projectDir);
 
 	let config: ClaudeToolkitConfig;
 
-	if (!existsSync(configPath)) {
+	if (existingConfig === null) {
 		// First run: create the config from what we detect.
 		const detected = detectStacks(projectDir);
 		if (detected.length > 0) {
@@ -175,15 +188,52 @@ async function run(projectDir: string, options: RunOptions = {}): Promise<void>
 
 	await generate(projectDir, config, { quiet });
 	log("Done.");
+	if (!quiet) await printRefreshHint(projectDir, config.packageManager, previousVersion);
 }
 
-/** postinstall: quietly regenerate from an existing config. Never creates one. */
-async function postinstall(projectDir: string): Promise<void> {
-	if (!existsSync(join(projectDir, CONFIG_FILENAME))) return;
+/**
+ * Print the "keep .claude/ in sync" hint unless package.json already runs
+ * `claude-toolkit refresh`. Only prints: package.json is a committed file.
+ */
+async function printRefreshHint(
+	projectDir: string,
+	packageManager: ClaudeToolkitConfig["packageManager"],
+	previousVersion: string | null,
+): Promise<void> {
+	const pkgPath = join(projectDir, "package.json");
+	if (!existsSync(pkgPath)) return;
+	let scripts: Record<string, unknown>;
+	try {
+		scripts = JSON.parse(await readFile(pkgPath, "utf-8")).scripts ?? {};
+	} catch {
+		return; // an unparsable package.json is not worth failing the run over
+	}
+	const lines = buildRefreshHint({
+		scripts,
+		packageManager,
+		yarnBerry: existsSync(join(projectDir, ".yarnrc.yml")),
+		previousVersion,
+	});
+	if (lines.length > 0) console.log(`\n${lines.join("\n")}`);
+}
+
+/**
+ * refresh: regenerate .claude/ when the installed toolkit version differs from the
+ * one recorded in .claude/.toolkit-version. Built for the consumer's own "prepare"
+ * script: it never creates the config, never scaffolds committed files, and the
+ * up-to-date path returns before the config is imported.
+ */
+async function refresh(projectDir: string, quiet: boolean): Promise<void> {
+	const log = quiet ? (_msg = "") => {} : (msg = "") => console.log(msg);
+	if (findConfigPath(projectDir) === null) {
+		log('[claude-toolkit] No config found — run "bunx claude-toolkit" to set up .claude/.');
+		return;
+	}
+	const version = await readToolkitVersion();
+	if ((await readMarker(projectDir)) === version) return;
 	const config = await loadConfig(projectDir);
-	// scaffold:false — never write committed project files (biome.json/tsconfig.json) on install.
 	await generate(projectDir, config, { quiet: true, scaffold: false });
-	console.log("[claude-toolkit] Regenerated .claude/ for the updated toolkit version.");
+	log(`[claude-toolkit] Regenerated .claude/ for toolkit ${version}.`);
 }
 
 const HELP = `
@@ -193,6 +243,10 @@ Usage:
   bunx claude-toolkit [project-dir]            Create config if missing, then regenerate .claude/
   bunx claude-toolkit --update [project-dir]   Also add newly-detected stacks to the config
 
+Commands:
+  refresh [project-dir]   Regenerate .claude/ only if the toolkit version changed.
+                          Never creates the config; meant for a "prepare" script.
+
 Commands (aliases):
   init      First-run friendly name (same as the bare command)
   update    Same as --update
@@ -203,14 +257,16 @@ Flags:
   --update, -u   Add newly-detected stacks to the config before regenerating
   --quiet, -q    Suppress informational output
 
-.claude/ also regenerates automatically on install when the toolkit version changes.
+Nothing runs at install time. To keep .claude/ in sync after upgrades, add to
+your package.json "scripts":
+  "prepare": "claude-toolkit refresh || exit 0"
 `;
 
 // ---- entry ----
 const argv = process.argv.slice(2);
 const flags = new Set(argv.filter((a) => a.startsWith("-")));
 const positional = argv.filter((a) => !a.startsWith("-"));
-const COMMANDS = new Set(["init", "update", "sync", "help", "postinstall"]);
+const COMMANDS = new Set(["init", "update", "sync", "help", "refresh"]);
 const KNOWN_FLAGS = new Set(["--update", "-u", "--quiet", "-q"]);
 
 // Reject unknown flags so a typo'd flag (e.g. --updat) isn't silently ignored.
@@ -248,8 +304,8 @@ try {
 		case "help":
 			console.log(HELP);
 			break;
-		case "postinstall":
-			await postinstall(projectDir);
+		case "refresh":
+			await refresh(projectDir, quiet);
 			break;
 		case "sync":
 			if (!quiet) {

package/core/skills/ct-typescript-conventions/SKILL.md

@@ -1,12 +1,70 @@
 ---
 name: ct-typescript-conventions
-description: Strict TypeScript patterns for type safety, readability, and maintainable codebases. Use when writing or reviewing TypeScript, adding or tightening types, or deciding between type and interface
+description: Strict TypeScript patterns and compiler selection -- prefer the TypeScript 7 native compiler when a project ships it. Use when writing or reviewing TypeScript, running a typecheck, adding or tightening types, or deciding between type and interface
 ---
 
 # TypeScript Conventions
 
 Strict mode enabled. Catch errors at compile time, not runtime.
 
+## Compiler -- prefer TypeScript 7 when the project has it
+
+TypeScript 7 (GA 2026-07-08, `typescript@7.0.2`) is the Go-native compiler; Microsoft reports **8x--12x faster full builds**. In a project that already ships it, use it for every type-check and build. Never install or bump it unprompted.
+
+**Detect the installed version, not the declared range:**
+
+```bash
+node -p "require('typescript/package.json').version"   # major >= 7 -> TS7
+```
+
+Resolve from the directory you are editing -- monorepo workspaces can pin different majors. Three traps:
+
+- The TS7 binary is **`tsc`**. `tsgo` was the pre-GA `@typescript/native-preview` name -- never put it in a script.
+- `package.json` ranges lie: `overrides`, `resolutions`, catalogs, and stale lockfiles all win, and `*` / `latest` / `>=5` resolve to 7.x today.
+- Don't probe the API -- on TS7 `require("typescript")` exposes only `version` and `versionMajorMinor`, so a `ts.createProgram` check gives a false negative.
+
+**Using it** -- same flags as 6.x:
+
+```bash
+tsc --noEmit                  # type-check
+tsc -b                        # build mode / project references
+tsc --checkers 1 --noEmit     # CI: pin the worker count
+```
+
+`--checkers` defaults to 4. Pin it in CI -- Microsoft warns that varying it can surface order-dependent results.
+
+**Stay on 6.x when a tool embeds the compiler.** TS7.0 ships no stable programmatic API (7.1 targets a new one), so `typescript-eslint`, `ts-jest`, `ts-node`, `vue-tsc`, `svelte-check`, `@astrojs/check`, and `@angular/compiler-cli` all break -- at install or lint time, *not* at `tsc --noEmit`. A green type-check proves nothing here. Vite, Bun, `tsx`, Vitest, and Biome are unaffected. Run both rather than downgrading:
+
+```json
+{
+  "devDependencies": {
+    "@typescript/native": "npm:typescript@^7.0.2",
+    "typescript": "npm:@typescript/typescript6@^6.0.2"
+  }
+}
+```
+
+Keep `typescript` pointed at the 6.0 package -- blocked tools import it by peer dependency. Where TS7 is absent, the floor is `typescript@6.0.3`, the bridge release; its readiness gate is a clean build with `"stableTypeOrdering": true` and no `ignoreDeprecations`.
+
+**`tsconfig.json` rules TS7 enforces** -- `ignoreDeprecations` no longer silences any of them:
+
+| Now rejected | Fix |
+|---|---|
+| `baseUrl` | project-root-relative `paths` |
+| `outFile`, `downlevelIteration` | remove |
+| `target: "es5"` | `"es2015"` or later |
+| `module: "amd" \| "umd" \| "system" \| "none" \| "systemjs"` | `"esnext"`, `"preserve"`, or `"nodenext"` |
+| `moduleResolution: "node" \| "node10" \| "classic"` | `"bundler"`, `"node16"`, or `"nodenext"` |
+| `esModuleInterop` / `allowSyntheticDefaultImports` / `alwaysStrict` set to `false` | drop the override |
+| `out`, `charset`, `keyofStringsOnly`, `importsNotUsedAsValues`, `preserveValueImports`, `suppressImplicitAnyIndexErrors`, `suppressExcessPropertyErrors`, `noStrictGenericChecks`, `noImplicitUseStrict` | gone -- `TS5023: Unknown compiler option` |
+
+Two changed defaults cause most real-world breakage. Both arrived in 6.0 and carry forward, so they bite on either major -- verified identical on 6.0.3 and 7.0.2:
+
+- **`types` defaults to `[]`** -- `process`, `Bun` and friends disappear (`TS2591`) *even with `@types/node` installed*. Set `"types": ["node"]` / `["bun"]` explicitly, naming only packages that are actually installed (a missing one is `TS2688`). `"types": ["*"]` restores the old catch-all on 6.x/7.x but is itself `TS2688` on 5.x.
+- **`rootDir` defaults to `./`** -- with sources in `src/` and an `outDir`, emit fails `TS5011`. Set `"rootDir": "./src"`. `--noEmit` does *not* surface this, so type-check CI stays green while the build breaks.
+
+`strict` and `stableTypeOrdering` are on by default; `stableTypeOrdering` cannot be turned off.
+
 ## Rules
 
 - **No `any`** -- Use `unknown` + narrowing, generics, or specific types.

package/package.json

@@ -1,10 +1,10 @@
 {
 	"name": "claude-toolkit",
-	"version": "0.15.0",
+	"version": "0.17.0-rc.1",
 	"description": "Reusable Claude Code configuration toolkit with stack-specific connectors",
 	"type": "module",
 	"bin": {
-		"claude-toolkit": "./bin/cli.ts"
+		"claude-toolkit": "bin/cli.ts"
 	},
 	"exports": {
 		".": {
@@ -18,7 +18,6 @@
 		"core/",
 		"stacks/",
 		"templates/",
-		"docs/",
 		"CHANGELOG.md"
 	],
 	"scripts": {
@@ -26,8 +25,8 @@
 		"lint": "biome check --write",
 		"lint:check": "biome check",
 		"test": "bun test",
-		"postinstall": "bun bin/postinstall.mjs || node bin/postinstall.mjs || exit 0",
-		"prepare": "npx husky"
+		"check:pack": "bun scripts/check-pack.ts",
+		"check:smoke": "bun scripts/check-smoke.ts"
 	},
 	"lint-staged": {
 		"*.{ts,tsx,js,jsx,json,css}": "biome check --write --no-errors-on-unmatched"
@@ -44,11 +43,11 @@
 	"license": "MIT",
 	"repository": {
 		"type": "git",
-		"url": "https://github.com/william-queant/claude-toolkit.git"
+		"url": "git+https://github.com/william-queant/claude-toolkit.git"
 	},
 	"devDependencies": {
 		"@biomejs/biome": "^2.4.10",
-		"@types/bun": "latest",
+		"@types/bun": "^1.3.11",
 		"husky": "^9.1.7",
 		"lint-staged": "^16.4.0",
 		"typescript": "^6.0.2"

package/src/generator.ts

@@ -1,12 +1,58 @@
-import { copyFile as fsCopyFile, readdir } from "node:fs/promises";
+import { copyFile as fsCopyFile, readdir, readFile } from "node:fs/promises";
 import { join, resolve } from "node:path";
 import type { ClaudeToolkitConfig, ResolvedConfig, StackPack } from "./types.js";
 import { copyDir, exists, readJson, removePath, writeFileEnsureDir } from "./utils.js";
 
 const TOOLKIT_ROOT = resolve(import.meta.dirname, "..");
 
+/** Branches protected when the config sets no `git.protectedBranches`. */
+const DEFAULT_PROTECTED_BRANCHES = ["main"];
+/** A protected branch name must match this before it is quoted into the guard's `case` pattern. */
+const BRANCH_NAME_PATTERN = /^[A-Za-z0-9._/][A-Za-z0-9._/-]*$/;
+
+/** Throw a clear error naming the first protected branch that fails BRANCH_NAME_PATTERN. */
+function assertValidBranchNames(branches: string[]): void {
+	const invalid = branches.find((b) => !BRANCH_NAME_PATTERN.test(b));
+	if (invalid === undefined) return;
+	throw new Error(
+		`Invalid branch name in git.protectedBranches: ${JSON.stringify(invalid)}. ` +
+			'Use only letters, digits, ".", "_", "/" and "-", and do not start with "-".',
+	);
+}
+
+/**
+ * The PreToolUse command that blocks edits on a protected branch, or null when no
+ * branch is protected. Names are validated first, then single-quoted into a `case`
+ * pattern, so each name is matched literally and never parsed by the shell.
+ */
+function buildBranchGuard(branches: string[]): string | null {
+	assertValidBranchNames(branches);
+	if (branches.length === 0) return null;
+	const patterns = branches.map((b) => `'${b}'`).join("|");
+	return `# Prevent editing on protected branches\ncase "$(git branch --show-current)" in ${patterns}) echo '{"block": true, "message": "Cannot edit files on a protected branch. Create a feature branch first."}' >&2; exit 2;; esac`;
+}
+
+/** File in .claude/ recording the toolkit version that last generated it. */
+const MARKER_FILE = ".toolkit-version";
+
+/** The installed toolkit version, read from the toolkit's own package.json. */
+export async function readToolkitVersion(): Promise<string> {
+	const { version } = await readJson<{ version: string }>(join(TOOLKIT_ROOT, "package.json"));
+	return version;
+}
+
+/** The version recorded in `<projectDir>/.claude/.toolkit-version`, or null when absent. */
+export async function readMarker(projectDir: string): Promise<string | null> {
+	const markerPath = join(projectDir, ".claude", MARKER_FILE);
+	if (!exists(markerPath)) return null;
+	return (await readFile(markerPath, "utf-8")).trim();
+}
+
 /** Resolve the full configuration by merging core + stacks + project config */
 async function resolveConfig(config: ClaudeToolkitConfig): Promise<ResolvedConfig> {
+	// Fail before anything is written when a branch name is unsafe to quote into a hook.
+	assertValidBranchNames(config.git?.protectedBranches ?? DEFAULT_PROTECTED_BRANCHES);
+
 	const stacks: StackPack[] = [];
 	const allMappings: Record<string, string> = {};
 
@@ -79,10 +125,8 @@ async function removeGenerated(claudeDir: string): Promise<void> {
 		// Toolkit hook files (copied from core/hooks) + the generated skill-rules.json.
 		...hookFiles.map((f) => removePath(join(claudeDir, "hooks", f))),
 		removePath(join(claudeDir, "hooks", "skill-rules.json")),
-		// Stale files from prior installs: skill-eval.js was renamed to .cjs, and the
-		// skill-eval.sh wrapper was dropped in favour of exec-form node registration.
+		// Stale file from prior installs: skill-eval.js was renamed to .cjs.
 		removePath(join(claudeDir, "hooks", "skill-eval.js")),
-		removePath(join(claudeDir, "hooks", "skill-eval.sh")),
 	]);
 }
 
@@ -153,8 +197,8 @@ export async function generate(
 		].join("\n"),
 	);
 
-	// 9. Scaffold base configs into the project root (committed files). Skipped for
-	//    automatic/postinstall regeneration so an install never writes committed files.
+	// 9. Scaffold base configs into the project root (committed files). Skipped by
+	//    `refresh` (scaffold: false), which must never write committed files.
 	if (options.scaffold !== false) {
 		await scaffoldConfigs(projectDir, resolved, options.quiet);
 	}
@@ -162,9 +206,9 @@ export async function generate(
 	// 10. Generate skills README
 	await generateSkillsReadme(claudeDir, resolved);
 
-	// Record the toolkit version that produced this output — drives auto-regen on update.
-	const { version } = await readJson<{ version: string }>(join(TOOLKIT_ROOT, "package.json"));
-	await writeFileEnsureDir(join(claudeDir, ".toolkit-version"), `${version}\n`);
+	// Record the toolkit version that produced this output — `refresh` compares against it.
+	const version = await readToolkitVersion();
+	await writeFileEnsureDir(join(claudeDir, MARKER_FILE), `${version}\n`);
 
 	if (!options.quiet) {
 		console.log(
@@ -230,11 +274,7 @@ async function generateSkillRules(claudeDir: string, resolved: ResolvedConfig):
 /** Generate settings.json with hooks */
 async function generateSettings(claudeDir: string, resolved: ResolvedConfig): Promise<void> {
 	const { hooks, config } = resolved;
-	const protectedBranches = config.git?.protectedBranches ?? ["main"];
-
-	const branchCheck = protectedBranches
-		.map((b) => `"$(git branch --show-current)" != "${b}"`)
-		.join(" && ");
+	const branchGuard = buildBranchGuard(config.git?.protectedBranches ?? DEFAULT_PROTECTED_BRANCHES);
 
 	const postToolUseHooks: unknown[] = [];
 
@@ -313,18 +353,16 @@ async function generateSettings(claudeDir: string, resolved: ResolvedConfig): Pr
 					],
 				},
 			],
-			PreToolUse: [
-				{
-					matcher: "Edit|MultiEdit|Write",
-					hooks: [
-						{
-							type: "command",
-							command: `# Prevent editing on protected branches\n[ ${branchCheck} ] || { echo '{"block": true, "message": "Cannot edit files on a protected branch. Create a feature branch first."}' >&2; exit 2; }`,
-							timeout: 5,
-						},
-					],
-				},
-			],
+			...(branchGuard === null
+				? {}
+				: {
+						PreToolUse: [
+							{
+								matcher: "Edit|MultiEdit|Write",
+								hooks: [{ type: "command", command: branchGuard, timeout: 5 }],
+							},
+						],
+					}),
 			PostToolUse: postToolUseHooks.map((hook) => ({
 				matcher: "Edit|MultiEdit|Write",
 				hooks: [hook],
@@ -373,7 +411,8 @@ async function generateSkillsReadme(claudeDir: string, resolved: ResolvedConfig)
 	content +=
 		"| ct-systematic-debugging | Four-phase debugging methodology, root cause analysis |\n";
 	content += "| ct-testing-patterns | Test-driven development workflow and patterns |\n";
-	content += "| ct-typescript-conventions | TypeScript strict mode and conventions |\n";
+	content +=
+		"| ct-typescript-conventions | TypeScript strict mode, conventions, and TS7 compiler selection |\n";
 	content += "| ct-verification-before-completion | Evidence-based completion claims protocol |\n";
 	content +=
 		"| ct-code-style | Code structure & style: guard clauses, lookup tables, no magic values |\n";