get-tbd 0.2.1 → 0.2.2

package/dist/docs/guidelines/pnpm-monorepo-patterns.md

@@ -24,31 +24,31 @@ author: Joshua Levy (github.com/jlevy) with LLM assistance
 
 | Tool / Package | Version | Check For Updates |
 | --- | --- | --- |
-| **Node.js** | 24 (LTS “Krypton”) | [nodejs.org/releases](https://nodejs.org/en/about/previous-releases) — Node 24 Active LTS until Oct 2026. **Node 26 Current** shipped 2026-05-05 (Temporal API enabled by default, V8 14.6, Undici 8.0). **Node 20 went EOL 2026-03-24.** Node 26 is the last release on the old two-major-per-year cadence; starting v27, all majors become LTS (one per year). |
-| **pnpm** | ^11.0.0 (11.2.x too recent) | [github.com/pnpm/pnpm/releases](https://github.com/pnpm/pnpm/releases) — **Pinned to 11.0.0 (2026-04-28) per the 14-day rule**; 11.2.0/11.2.2 shipped 2026-05-20/21 (1–2 days old today). Breaking changes: pure ESM (requires **Node 22+**); SQLite-based store (`$STORE/index.db`); **`minimumReleaseAge` defaults to 1440 minutes (1 day)** for supply-chain hygiene; **`blockExoticSubdeps` defaults to `true`**; `onlyBuiltDependencies`/`neverBuiltDependencies` removed and replaced by **`allowBuilds`**; `patchedDependencies` format simplified; experimental Rust-based `@pnpm/pacquet` engine arrives in 11.2+. v11.1 added `pnpm audit signatures`, `pnpm bugs`, `pnpm owner`. |
-| **TypeScript** | ^6.0.3 | [github.com/microsoft/TypeScript/releases](https://github.com/microsoft/TypeScript/releases) — **6.0.3 stable** (shipped 2026-03-23). 6.0 is the last JavaScript-based release; `strict: true` is now the default, ESM is the default module system, ~9 compiler settings flipped defaults. **TS 7.0 Beta** (Project Corsa, Go rewrite) shipped 2026-04-21 as `@typescript/native-preview` (binary: `tsgo`); claims ~10× type-check speed and ~3× less memory. Stable expected mid-to-late 2026. Do not adopt `tsgo` for production builds yet. |
-| **tsdown** | ^0.22.0 | [github.com/rolldown/tsdown/releases](https://github.com/rolldown/tsdown/releases) — 0.22.0 (2026-05-07). Has not reached 1.0; incremental 0.20→0.22 releases since Feb 2026; no deprecations. Requires Node.js 20.19+. |
-| **publint** | ^0.3.20 (0.3.21 too recent) | [npmjs.com/package/publint](https://www.npmjs.com/package/publint) — **Pinned to 0.3.20 (2026-05-08) per the 14-day rule**; 0.3.21 (2026-05-13) is 9 days old today. Re-enabled TS/TSX file existence checks; `exports["default"]` support; bug fixes. |
-| **@changesets/cli** | ^2.31.0 | [github.com/changesets/changesets/releases](https://github.com/changesets/changesets/releases) — 2.31.0 latest. No native Bun support added. |
-| **@types/node** | ^24.0.0 | [@types/node npm](https://www.npmjs.com/package/@types/node) — Track Node.js major version. @types/node@25.x available; @types/node@26.x will follow Node 26. |
-| **actions/checkout** | v6 | [github.com/actions/checkout/releases](https://github.com/actions/checkout/releases) — v6.0.2 (2026-01-09). Credentials now stored in `$RUNNER_TEMP` rather than `.git/config`; Node 24 runtime; requires runner ≥ 2.327.1. |
-| **actions/setup-node** | v6 | [github.com/actions/setup-node/releases](https://github.com/actions/setup-node/releases) — Supports Node 24 by default. **Note GitHub’s 2026-06-02 deadline forcing Node.js 20 actions to Node.js 24.** |
-| **pnpm/action-setup** | v6 | [github.com/pnpm/action-setup/releases](https://github.com/pnpm/action-setup/releases) — **v6 required for pnpm 11+ support.** v4 (previously documented) does not handle pnpm 11’s ESM-only distribution correctly. |
-| **changesets/action** | v1 | [github.com/changesets/action](https://github.com/changesets/action) — Still v1. No v2. |
-| **lefthook** | ^2.1.5 (2.1.7/2.1.8 too recent) | [github.com/evilmartians/lefthook/releases](https://github.com/evilmartians/lefthook/releases) — **Pinned to 2.1.5 (2026-04-06) per the 14-day rule**; 2.1.7/2.1.8 both shipped 2026-05-19. Patch-level since 2.1.1. v2 still excludes regexp `exclude` and `skip_output` from v1. |
-| **npm-check-updates** | ^22.0.0 (22.2.0 too recent) | [npmjs.com/package/npm-check-updates](https://www.npmjs.com/package/npm-check-updates) — **Major version jump from 19 to 22.** **Pinned to 22.0.0 (2026-04-25) per the 14-day rule**; 22.2.0 (2026-05-12) is 10 days old today. Now pure ESM; named imports only (`import { run } from 'npm-check-updates'`); `.ncurc.js` with `module.exports` no longer works in `"type": "module"` projects (use `.ncurc.cjs`). **Ships `--cooldown <days>` to refuse versions younger than the specified age** — primary enforcement for the 14-day package-age rule. See [Supply-Chain Mitigation](#supply-chain-mitigation). |
-| **tsx** | ^4.21.0 (4.22.x too recent) | [github.com/privatenumber/tsx/releases](https://github.com/privatenumber/tsx/releases) — **Pinned to 4.21.0 (2025-11-30) per the 14-day rule**; 4.22.0 shipped 2026-05-14 (8 days old) and 4.22.3 shipped 2026-05-19 (3 days old). Bump on next refresh once 4.22.x has aged. |
-| **prettier** | ^3.8.3 | [github.com/prettier/prettier/releases](https://github.com/prettier/prettier/releases) — 3.8.3 stable. Prettier 4.0 is in alpha (4.0.0-alpha.13, CLI performance rewrite) — **not stable yet**; do not adopt. |
+| **Node.js** | 24 (LTS “Krypton”) | [nodejs.org/releases](https://nodejs.org/en/about/previous-releases)—Node 24 Active LTS until Oct 2026. **Node 26 Current** shipped 2026-05-05 (Temporal API enabled by default, V8 14.6, Undici 8.0). **Node 20 went EOL 2026-03-24.** Node 26 is the last release on the old two-major-per-year cadence; starting v27, all majors become LTS (one per year). |
+| **pnpm** | ^11.0.0 (11.2.x too recent) | [github.com/pnpm/pnpm/releases](https://github.com/pnpm/pnpm/releases)—**Pinned to 11.0.0 (2026-04-28) per the 14-day rule**; 11.2.0/11.2.2 shipped 2026-05-20/21 (1–2 days old today). Breaking changes: pure ESM (requires **Node 22+**); SQLite-based store (`$STORE/index.db`); **`minimumReleaseAge` defaults to 1440 minutes (1 day)** for supply-chain hygiene; **`blockExoticSubdeps` defaults to `true`**; `onlyBuiltDependencies`/`neverBuiltDependencies` removed and replaced by **`allowBuilds`**; `patchedDependencies` format simplified; experimental Rust-based `@pnpm/pacquet` engine arrives in 11.2+. v11.1 added `pnpm audit signatures`, `pnpm bugs`, `pnpm owner`. |
+| **TypeScript** | ^6.0.3 | [github.com/microsoft/TypeScript/releases](https://github.com/microsoft/TypeScript/releases)—**6.0.3 stable** (shipped 2026-03-23). 6.0 is the last JavaScript-based release; `strict: true` is now the default, ESM is the default module system, ~9 compiler settings flipped defaults. **TS 7.0 Beta** (Project Corsa, Go rewrite) shipped 2026-04-21 as `@typescript/native-preview` (binary: `tsgo`); claims ~10× type-check speed and ~3× less memory. Stable expected mid-to-late 2026. Do not adopt `tsgo` for production builds yet. |
+| **tsdown** | ^0.22.0 | [github.com/rolldown/tsdown/releases](https://github.com/rolldown/tsdown/releases)—0.22.0 (2026-05-07). Has not reached 1.0; incremental 0.20→0.22 releases since Feb 2026; no deprecations. Requires Node.js 20.19+. |
+| **publint** | ^0.3.20 (0.3.21 too recent) | [npmjs.com/package/publint](https://www.npmjs.com/package/publint)—**Pinned to 0.3.20 (2026-05-08) per the 14-day rule**; 0.3.21 (2026-05-13) is 9 days old today. Re-enabled TS/TSX file existence checks; `exports["default"]` support; bug fixes. |
+| **@changesets/cli** | ^2.31.0 | [github.com/changesets/changesets/releases](https://github.com/changesets/changesets/releases)—2.31.0 latest. No native Bun support added. |
+| **@types/node** | ^24.0.0 | [@types/node npm](https://www.npmjs.com/package/@types/node)—Track Node.js major version. @types/node@25.x available; @types/node@26.x will follow Node 26. |
+| **actions/checkout** | v6 | [github.com/actions/checkout/releases](https://github.com/actions/checkout/releases)—v6.0.2 (2026-01-09). Credentials now stored in `$RUNNER_TEMP` rather than `.git/config`; Node 24 runtime; requires runner ≥ 2.327.1. |
+| **actions/setup-node** | v6 | [github.com/actions/setup-node/releases](https://github.com/actions/setup-node/releases)—Supports Node 24 by default. **Note GitHub’s 2026-06-02 deadline forcing Node.js 20 actions to Node.js 24.** |
+| **pnpm/action-setup** | v6 | [github.com/pnpm/action-setup/releases](https://github.com/pnpm/action-setup/releases)—**v6 required for pnpm 11+ support.** v4 (previously documented) does not handle pnpm 11’s ESM-only distribution correctly. |
+| **changesets/action** | v1 | [github.com/changesets/action](https://github.com/changesets/action)—Still v1. No v2. |
+| **lefthook** | ^2.1.5 (2.1.7/2.1.8 too recent) | [github.com/evilmartians/lefthook/releases](https://github.com/evilmartians/lefthook/releases)—**Pinned to 2.1.5 (2026-04-06) per the 14-day rule**; 2.1.7/2.1.8 both shipped 2026-05-19. Patch-level since 2.1.1. v2 still excludes regexp `exclude` and `skip_output` from v1. |
+| **npm-check-updates** | ^22.0.0 (22.2.0 too recent) | [npmjs.com/package/npm-check-updates](https://www.npmjs.com/package/npm-check-updates)—**Major version jump from 19 to 22.** **Pinned to 22.0.0 (2026-04-25) per the 14-day rule**; 22.2.0 (2026-05-12) is 10 days old today. Now pure ESM; named imports only (`import { run } from 'npm-check-updates'`); `.ncurc.js` with `module.exports` no longer works in `"type": "module"` projects (use `.ncurc.cjs`). **Ships `--cooldown <days>` to refuse versions younger than the specified age**—primary enforcement for the 14-day package-age rule. See [Supply-Chain Mitigation](#supply-chain-mitigation). |
+| **tsx** | ^4.21.0 (4.22.x too recent) | [github.com/privatenumber/tsx/releases](https://github.com/privatenumber/tsx/releases)—**Pinned to 4.21.0 (2025-11-30) per the 14-day rule**; 4.22.0 shipped 2026-05-14 (8 days old) and 4.22.3 shipped 2026-05-19 (3 days old). Bump on next refresh once 4.22.x has aged. |
+| **prettier** | ^3.8.3 | [github.com/prettier/prettier/releases](https://github.com/prettier/prettier/releases)—3.8.3 stable. Prettier 4.0 is in alpha (4.0.0-alpha.13, CLI performance rewrite)—**not stable yet**; do not adopt. |
 | **eslint-config-prettier** | ^10.0.0 | [github.com/prettier/eslint-config-prettier/releases](https://github.com/prettier/eslint-config-prettier/releases) |
-| **ESLint** | ^10.0.0 | [github.com/eslint/eslint/releases](https://github.com/eslint/eslint/releases) — **ESLint 10.0.0 shipped 2026-02-06.** **Breaking**: `.eslintrc.*` configuration is completely removed — flat config (`eslint.config.js`) is the only supported format. Download size reduced (11 MB → 9.4 MB). Improved JSX reference tracking. **Minimum Node.js v20.19.0.** ESLint 9.x EOL is 2026-08-06. |
-| **Vitest** | ^4.1.5 (4.1.6/4.1.7 too recent) | [github.com/vitest-dev/vitest/releases](https://github.com/vitest-dev/vitest/releases) — **Pinned to 4.1.5 (2026-04-21) per the 14-day rule**; 4.1.7 (2026-05-20) is 2 days old today. v4.1 (Mar 2026) added Vite 8 support, test tags, extended chai-style assertions for mocking. Vitest now reuses installed Vite instead of bundling. Browser Mode stable, visual regression added. `coverage.all` was removed in v4. Vitest 5.0.0-beta.3 in pre-release (requires Node 22+, Vite 6.4+) — **do not adopt yet**. |
-| **Zod** | ^4.4.3 | [github.com/colinhacks/zod/releases](https://github.com/colinhacks/zod/releases) — **Zod 4 fully stable.** 14× faster string parsing, 7× faster array parsing, 6.5× faster object parsing vs Zod 3; core bundle 2.3× smaller. New `@zod/mini` package (~1.9 KB gzipped) for tree-shakable frontend validation. Migration from Zod 3 required — see [zod.dev/v4/changelog](https://zod.dev/v4/changelog). |
-| **commander** | ^15.0.0 | [github.com/tj/commander.js/releases](https://github.com/tj/commander.js/releases) — Commander 15 shipping May 2026, **ESM-only, requires Node v22.12.0+**. Commander 14 moves to maintenance (security only) until May 2027. |
-| **picocolors** | ^1.1.1 | [npmjs.com/package/picocolors](https://www.npmjs.com/package/picocolors) — Last release October 2024. Stable; no changes expected. |
-| **dotenv** | ^17.4.2 | [npmjs.com/package/dotenv](https://www.npmjs.com/package/dotenv) — Stable. **Prefer Node.js native `--env-file` for Node ≥20.6** (production-ready since Node 24 LTS); use dotenv only when you need variable expansion, multiline values, or custom precedence logic. |
-| **atomically** | ^2.1.1 | [npmjs.com/package/atomically](https://www.npmjs.com/package/atomically) — 2.1.1 (2026-02-08). Still maintained. |
-| **yaml** | ^2.8.4 | [npmjs.com/package/yaml](https://www.npmjs.com/package/yaml) — 2.8.4 (2026-05-02). v3.0.0-1 is tagged “next” (pre-release) — do not adopt yet. |
-| **@vitest/coverage-v8** | ^4.1.7 | [npmjs.com/package/@vitest/coverage-v8](https://www.npmjs.com/package/@vitest/coverage-v8) — Track Vitest version. |
+| **ESLint** | ^10.0.0 | [github.com/eslint/eslint/releases](https://github.com/eslint/eslint/releases)—**ESLint 10.0.0 shipped 2026-02-06.** **Breaking**: `.eslintrc.*` configuration is completely removed—flat config (`eslint.config.js`) is the only supported format. Download size reduced (11 MB → 9.4 MB). Improved JSX reference tracking. **Minimum Node.js v20.19.0.** ESLint 9.x EOL is 2026-08-06. |
+| **Vitest** | ^4.1.5 (4.1.6/4.1.7 too recent) | [github.com/vitest-dev/vitest/releases](https://github.com/vitest-dev/vitest/releases)—**Pinned to 4.1.5 (2026-04-21) per the 14-day rule**; 4.1.7 (2026-05-20) is 2 days old today. v4.1 (Mar 2026) added Vite 8 support, test tags, extended chai-style assertions for mocking. Vitest now reuses installed Vite instead of bundling. Browser Mode stable, visual regression added. `coverage.all` was removed in v4. Vitest 5.0.0-beta.3 in pre-release (requires Node 22+, Vite 6.4+)—**do not adopt yet**. |
+| **Zod** | ^4.4.3 | [github.com/colinhacks/zod/releases](https://github.com/colinhacks/zod/releases)—**Zod 4 fully stable.** 14× faster string parsing, 7× faster array parsing, 6.5× faster object parsing vs Zod 3; core bundle 2.3× smaller. New `@zod/mini` package (~1.9 KB gzipped) for tree-shakable frontend validation. Migration from Zod 3 required—see [zod.dev/v4/changelog](https://zod.dev/v4/changelog). |
+| **commander** | ^15.0.0 | [github.com/tj/commander.js/releases](https://github.com/tj/commander.js/releases)—Commander 15 shipping May 2026, **ESM-only, requires Node v22.12.0+**. Commander 14 moves to maintenance (security only) until May 2027. |
+| **picocolors** | ^1.1.1 | [npmjs.com/package/picocolors](https://www.npmjs.com/package/picocolors)—Last release October 2024. Stable; no changes expected. |
+| **dotenv** | ^17.4.2 | [npmjs.com/package/dotenv](https://www.npmjs.com/package/dotenv)—Stable. **Prefer Node.js native `--env-file` for Node ≥20.6** (production-ready since Node 24 LTS); use dotenv only when you need variable expansion, multiline values, or custom precedence logic. |
+| **atomically** | ^2.1.1 | [npmjs.com/package/atomically](https://www.npmjs.com/package/atomically)—2.1.1 (2026-02-08). Still maintained. |
+| **yaml** | ^2.8.4 | [npmjs.com/package/yaml](https://www.npmjs.com/package/yaml)—2.8.4 (2026-05-02). v3.0.0-1 is tagged “next” (pre-release)—do not adopt yet. |
+| **@vitest/coverage-v8** | ^4.1.7 | [npmjs.com/package/@vitest/coverage-v8](https://www.npmjs.com/package/@vitest/coverage-v8)—Track Vitest version. |
 
 ### Reminders When Updating
 
@@ -56,7 +56,7 @@ author: Joshua Levy (github.com/jlevy) with LLM assistance
 
 2. **Update the table** with new versions and any relevant notes
 
-3. **Search and update code examples** — version numbers appear in:
+3. **Search and update code examples**—version numbers appear in:
 
    - GitHub Actions workflows (CI and Release sections)
 
@@ -68,7 +68,7 @@ author: Joshua Levy (github.com/jlevy) with LLM assistance
 
    - Appendices A, B, and D (complete examples)
 
-4. **Verify compatibility** — check that tools still work together (e.g., new
+4. **Verify compatibility**—check that tools still work together (e.g., new
    pnpm/action-setup versions may change caching behavior)
 
 5. **Update the “Last Updated” date** at the top of the document
@@ -76,9 +76,9 @@ author: Joshua Levy (github.com/jlevy) with LLM assistance
 6. **Review “Open Research Questions”** section for any resolved items
 
 7. **Honor the 14-day package-age rule** when bumping versions in code examples.
-   See [Supply-Chain Mitigation](#supply-chain-mitigation) — versions cited here should
-   be ≥14 days old at the time the table is updated, except where a clearly-noted
-   security exception applies.
+   See [Supply-Chain Mitigation](#supply-chain-mitigation)—versions cited here should be
+   ≥14 days old at the time the table is updated, except where a clearly-noted security
+   exception applies.
 
 * * *
 
@@ -137,7 +137,7 @@ recommendations from the TypeScript and JavaScript ecosystem maintainers.
 
 ## Research Findings
 
-### 1. Package Manager & Workspace Structure
+### 1. Package Manager and Workspace Structure
 
 #### pnpm Workspaces
 
@@ -157,7 +157,7 @@ recommendations from the TypeScript and JavaScript ecosystem maintainers.
 
 - **pnpm 11 (shipped 2026-04-28)** adds significant supply-chain hardening defaults:
   `minimumReleaseAge: 1440` (1 day) and `blockExoticSubdeps: true`. We recommend
-  overriding `minimumReleaseAge` to 14 days — see
+  overriding `minimumReleaseAge` to 14 days—see
   [Supply-Chain Mitigation](#supply-chain-mitigation).
 
 - **pnpm 11 is pure ESM and requires Node.js 22+.** Lifecycle script gating has moved
@@ -469,7 +469,7 @@ Only provide dual ESM/CJS if you have confirmed CJS consumer requirements.
 
 * * *
 
-### 4. Package Exports & Dual Module Support
+### 4. Package Exports and Dual Module Support
 
 #### Subpath Exports
 
@@ -668,7 +668,7 @@ package. Essential for any published package.
 
 * * *
 
-### 7. Versioning & Release Automation
+### 7. Versioning and Release Automation
 
 #### Changesets
 
@@ -733,7 +733,7 @@ Changesets provides:
 
 **Assessment**: Changesets is the de facto standard for *multi-package* monorepo
 versioning and integrates seamlessly with pnpm and GitHub Actions.
-For a repo that publishes a single package, its per-PR ceremony rarely pays off — prefer
+For a repo that publishes a single package, its per-PR ceremony rarely pays off—prefer
 the tag-triggered approach below (see the LLM-era note).
 
 **References**:
@@ -1139,8 +1139,8 @@ Vite’s transformation pipeline.
   extended chai-style assertions for mocking.
   Vitest now reuses the installed Vite instead of bundling a separate dependency.
 
-- **`coverage.all` was removed in v4** — use `coverage.include` and `coverage.exclude`
-  to control which files are reported.
+- **`coverage.all` was removed in v4**—use `coverage.include` and `coverage.exclude` to
+  control which files are reported.
 
 - **Vitest 5.0.0-beta** is in pre-release (requires Node 22+ and Vite 6.4+). Stay on
   4.1.x for production until stable.
@@ -1572,7 +1572,7 @@ CI) provides the best developer experience while ensuring CI catches issues.
 
 * * *
 
-### 11. Git Hooks & Local Validation
+### 11. Git Hooks and Local Validation
 
 #### Lefthook
 
@@ -1886,13 +1886,13 @@ workflow. This makes upgrades consistent and discoverable.
 
 **Workflow**:
 
-1. **Check for updates**: `pnpm upgrade:check` — see what’s available without changing
+1. **Check for updates**: `pnpm upgrade:check`—see what’s available without changing
    anything
 
-2. **Safe upgrade**: `pnpm upgrade` — upgrade minor/patch versions and run tests to
-   verify nothing breaks
+2. **Safe upgrade**: `pnpm upgrade`—upgrade minor/patch versions and run tests to verify
+   nothing breaks
 
-3. **Major upgrades**: `pnpm upgrade:major` — interactively review major version bumps,
+3. **Major upgrades**: `pnpm upgrade:major`—interactively review major version bumps,
    select which to apply, then test and review changelogs
 
 **Key insight**: Running tests after `upgrade` catches regressions immediately.
@@ -2546,8 +2546,8 @@ than discovering them when users try to use the library in browser/edge contexts
 
 **References**:
 
-- [CLI Tool Development Rules](../../agent-rules/typescript-cli-tool-rules.md) —
-  CLI-specific patterns using Commander.js, picocolors, and @clack/prompts
+- [CLI Tool Development Rules](../../agent-rules/typescript-cli-tool-rules.md)—CLI-specific
+  patterns using Commander.js, picocolors, and @clack/prompts
 
 * * *
 
@@ -2556,7 +2556,7 @@ than discovering them when users try to use the library in browser/edge contexts
 Supply-chain hardening applies to **every repo, not just new monorepos**, so the full
 policy and hands-on enforcement now live in a standalone guideline:
 **`tbd guidelines supply-chain-hardening`**. It covers the cross-ecosystem 14-day
-cool-off plus the Node/pnpm/Bun specifics — lifecycle-script allowlists, lockfile
+cool-off plus the Node/pnpm/Bun specifics—lifecycle-script allowlists, lockfile
 discipline, `npm-check-updates --cooldown 14`, the CI audit gate, and the
 `check-package-age` pre-push guard.
 Deeper background and the named-incident watch list:
@@ -2707,7 +2707,7 @@ Deeper background and the named-incident watch list:
    `@typescript/native-preview` (binary `tsgo`). Claims ~10× type-check speed and ~3×
    less memory; passes 95%+ of the test suite.
    Available in Visual Studio 2026 18.6 Insiders by default.
-   **Do not adopt for production builds yet** — wait for stable (expected mid-to-late
+   **Do not adopt for production builds yet**—wait for stable (expected mid-to-late
    2026). Monitor for tsdown/Vitest compatibility announcements.
 
 4. **Native TypeScript Execution**: TypeScript 5.8+ supports `--erasableSyntaxOnly`,
@@ -2716,9 +2716,9 @@ Deeper background and the named-incident watch list:
    Monitor for broader tooling adoption (linters, coverage tools).
 
 5. ~~**ESLint v10**~~: **SHIPPED** 2026-02-06. `.eslintrc.*` configuration is completely
-   removed — flat config (`eslint.config.js`) is the only supported format.
+   removed—flat config (`eslint.config.js`) is the only supported format.
    Download size reduced 11 MB → 9.4 MB. Minimum Node.js v20.19.0. ESLint 9.x EOL is
-   2026-08-06 — migrate now.
+   2026-08-06—migrate now.
 
 6. ~~**pnpm 11**~~: **SHIPPED** 2026-04-28 (currently 11.2.2). Breaking changes: pure
    ESM (requires Node 22+), SQLite-based store, `minimumReleaseAge` default (1 day),
@@ -2729,7 +2729,7 @@ Deeper background and the named-incident watch list:
 7. ~~**Zod 4**~~: **SHIPPED** (currently 4.4.3). 14× faster string parsing, 7× faster
    array parsing, 6.5× faster object parsing vs Zod 3; core bundle 2.3× smaller; new
    `@zod/mini` (~1.9 KB gzipped) for tree-shakable frontend validation.
-   Migration from Zod 3 required — see
+   Migration from Zod 3 required—see
    [zod.dev/v4/changelog](https://zod.dev/v4/changelog).
 
 8. **Commander 15 (ESM-only)**: Commander 15 ships May 2026, requires Node v22.12.0+,
@@ -2831,7 +2831,7 @@ ready for public release.
 
 - [Node.js Releases](https://nodejs.org/en/about/previous-releases)
 
-### Guides & Articles
+### Guides and Articles
 
 - [Complete Monorepo Guide 2025](https://jsdev.space/complete-monorepo-guide/)
 

package/dist/docs/guidelines/python-cli-patterns.md

@@ -31,7 +31,7 @@ src/myproject/
     └── options.py          # TypedDict for command options
 ```
 
-### Agent & CI Compatibility
+### Agent and CI Compatibility
 
 Support automation with explicit flags:
 - `--format text|json|jsonl`: Output format

package/dist/docs/guidelines/python-modern-guidelines.md

@@ -186,22 +186,22 @@ str(MyThing(file_path="/tmp/file.txt", title="Something " + "blah " * 50, url="h
 ## Releasing (tag-triggered, no changesets)
 
 For publishing Python packages to PyPI, follow the
-[`simple-modern-uv`](https://github.com/jlevy/simple-modern-uv) template’s model — it is
+[`simple-modern-uv`](https://github.com/jlevy/simple-modern-uv) template’s model—it is
 the standard for tbd’s Python projects.
 The same clean principles as the TypeScript guidance apply: no changesets, releases cut
 from clean conventional commits.
 
 - **Dynamic versioning from the git tag** via
-  [`uv-dynamic-versioning`](https://github.com/ninoseki/uv-dynamic-versioning) — the tag
+  [`uv-dynamic-versioning`](https://github.com/ninoseki/uv-dynamic-versioning)—the tag
   *is* the version (no manual `version =` bump in `pyproject.toml`, no version commit).
 - **Release/tag-triggered publish**: a `publish.yml` workflow runs on
   `on: release: types: [published]` (or a `v*` tag), builds with `uv build`, and
-  publishes with `uv publish --trusted-publishing always` — **PyPI Trusted Publishing
+  publishes with `uv publish --trusted-publishing always`—**PyPI Trusted Publishing
   (OIDC), no API token**.
 - **Supply-chain cool-off in CI**: set `UV_EXCLUDE_NEWER` to a 14-days-ago cutoff so the
   build never resolves a brand-new (potentially yanked/compromised) release.
 - **Release notes** are written per `release-notes-guidelines` from the commits since
-  the last tag — there is no per-PR changeset file.
+  the last tag—there is no per-PR changeset file.
 - Expose the version at runtime with `importlib.metadata.version("<pkg>")`.
 
 So a release is just: clean commits → create the GitHub release/tag `vX.Y.Z` → CI builds

package/dist/docs/guidelines/release-notes-guidelines.md

@@ -20,6 +20,9 @@ Use these sections in order (omit empty sections):
 ### Fixes
 - Bug fixes and corrections
 
+### Guidelines and content
+- Changes to shipped guidelines, skills, shortcuts, or templates that users invoke
+
 ### Refactoring
 - Internal improvements (only if user-visible impact)
 
@@ -29,6 +32,13 @@ Use these sections in order (omit empty sections):
 **Full commit history**: [link to compare]
 ```
 
+**Releases are not code-only.** If the project ships content—bundled guidelines, skills,
+shortcuts, prompts, or templates that users invoke—changes to that content are product
+changes. Review those diffs (not just code commits) and give them their own
+`### Guidelines and content` section.
+Reserve `### Documentation` for docs *about* the project (README, dev/internal docs);
+shipped content a user can invoke is never an “internal doc” to skip.
+
 ## Core Principle: Describe the Delta
 
 **Think in terms of two points in time:**
@@ -105,17 +115,23 @@ Don’t include:
 - Test-only changes (unless they fix flaky tests users noticed)
 - Pure refactoring with no user impact
 - CI/tooling changes
-- Minor doc typo fixes
+- Minor typo fixes in docs *about* the project (README, dev/internal docs)
+
+Do **not** treat shipped content as internal.
+Changes to guidelines, skills, shortcuts, or templates that users invoke are product
+changes—include them under `Guidelines and content` (see Structure).
 
 ## Review Checklist
 
 Before finalizing release notes:
 
 - [ ] Does each item describe the aggregate delta from the previous release?
-- [ ] Are related changes (features + their fixes) consolidated under one heading?
+- [ ] Are related changes (features and their fixes) consolidated under one heading?
 - [ ] Would a user understand what’s different after upgrading?
 - [ ] Are feature names/commands in consistent format?
 - [ ] Are internal-only changes excluded?
+- [ ] Did you review shipped-content diffs (guidelines, skills, shortcuts, templates),
+  not just code commits, and give them a section?
 
 ## Example
 

package/dist/docs/guidelines/supply-chain-hardening.md

@@ -1,6 +1,6 @@
 ---
 title: Supply-Chain Hardening
-description: Strongly recommended for EVERY repo — apply it if a repo has not been hardened yet. Cross-ecosystem policy for installing dependencies safely (the 14-day cool-off, disabled install scripts, lockfile discipline, untrusted-repo handling). Use whenever a user mentions hardening, security, supply chain, or setting up a new repo; before adding/upgrading dependencies; when auditing for compromised packages; or when reviewing install/build/run commands across npm/pnpm, PyPI, Cargo, or Go.
+description: Strongly recommended for EVERY repo—apply it if a repo has not been hardened yet. Cross-ecosystem policy for installing dependencies safely (the 14-day cool-off, disabled install scripts, lockfile discipline, untrusted-repo handling). Use whenever a user mentions hardening, security, supply chain, or setting up a new repo; before adding/upgrading dependencies; when auditing for compromised packages; or when reviewing install/build/run commands across npm/pnpm, PyPI, Cargo, or Go.
 author: Joshua Levy (github.com/jlevy) with LLM assistance
 ---
 # Supply-Chain Hardening
@@ -12,8 +12,8 @@ malicious package versions are published, exfiltrate credentials or install pers
 and are usually yanked within minutes to days.
 
 **Strongly recommended for every repo.** If a project has not been hardened yet, apply
-this policy (and the per-ecosystem playbooks it links) as part of setup — it is
-especially worth doing when standing up a new repo or whenever security comes up.
+this policy (and the per-ecosystem playbooks it links) as part of setup—it is especially
+worth doing when standing up a new repo or whenever security comes up.
 
 **This is the concise policy.** For the full playbooks (per-ecosystem ten-minute setups,
 a zero-dependency audit script, a curated watch list of named incidents, CI/publish-side
@@ -23,23 +23,22 @@ see `tbd guidelines bun-monorepo-patterns` or `tbd guidelines pnpm-monorepo-patt
 
 **When to use this guideline**: before adding or upgrading any dependency; when
 hardening a workstation, repo, or CI pipeline; when assessing whether an installed
-package is compromised; or when reviewing any `install` / `build` / `run` command —
-especially in a freshly cloned third-party repo.
+package is compromised; or when reviewing any `install` / `build` / `run`
+command—especially in a freshly cloned third-party repo.
 
 ## The Default: a 14-Day Cool-Off
 
 **Never install or upgrade to a package version less than 14 days old, unless a
 documented exception applies.** This is the single most effective default.
 It works because registries and researchers detect and yank malicious versions while
-legitimate versions keep accruing age — so the only cost of waiting is slightly staler
+legitimate versions keep accruing age—so the only cost of waiting is slightly staler
 dependencies.
 
 **14 days is a floor, not a ceiling.** A 30/60/90-day window is strictly safer; machines
 with publish tokens or production access should go higher.
-Scope: applies to `dependencies`, `devDependencies` (historically *more* dangerous —
-build tooling runs with full privileges), `peer`/`optionalDependencies`, new installs,
-and upgrades.
-Pins resolved before adopting the policy are grandfathered until their next
+Scope: applies to `dependencies`, `devDependencies` (historically *more* dangerous—build
+tooling runs with full privileges), `peer`/`optionalDependencies`, new installs, and
+upgrades. Pins resolved before adopting the policy are grandfathered until their next
 planned upgrade.
 
 ### Per-ecosystem control
@@ -64,23 +63,23 @@ To check one version’s age: `npm view <pkg> time.<ver>`.
    `pip install` / `cargo install` / `go install`: confirm the package is needed, the
    name is spelled correctly (typosquats are common), and the version clears the
    cool-off (or is lockfile-pinned, or has a stated exception).
-2. **Disable install/lifecycle scripts by default** — the primary exfiltration vector in
+2. **Disable install/lifecycle scripts by default**—the primary exfiltration vector in
    worm-class attacks (`NPM_CONFIG_IGNORE_SCRIPTS=true`; pnpm `ignoreScripts: true` +
    `allowBuilds` allowlist; refuse PyPI sdist builds with
    `UV_NO_BUILD`/`PIP_ONLY_BINARY`).
 3. **Commit lockfiles; install frozen.** `pnpm install --frozen-lockfile` / `npm ci` /
    `--locked`. Never auto-update without review.
-4. **Audit after every install** — `pnpm audit` / `npm audit` / `pip-audit` /
+4. **Audit after every install**—`pnpm audit` / `npm audit` / `pip-audit` /
    `cargo audit` / `govulncheck`; address findings before continuing.
-5. **Don’t update for its own sake.** The safest update is the one you skip — each bump
-   is fresh attack surface.
+5. **Don’t update for its own sake.** The safest update is the one you skip—each bump is
+   fresh attack surface.
    Bump only for a concrete reason ("show me the commit we need"); prefer fewer,
    vendored/pinned dependencies; let audits and CVE monitoring tell you when a real
    update is warranted.
 6. **No unpinned zero-install runners.** Avoid `npx` / `pnpm dlx` / `bunx` / `uvx` /
    `go run <remote>` without an explicit `@version` pin and a review of the resolved
-   `package@version` — they fetch and execute the latest code, bypassing the cool-off.
-   (When a skill references a CLI via a runner, pin it — see
+   `package@version`—they fetch and execute the latest code, bypassing the cool-off.
+   (When a skill references a CLI via a runner, pin it—see
    `tbd guidelines cli-agent-skill-patterns` §6.7.)
 7. **No `curl | sh` from untrusted sources.** Verify the installer URL belongs to the
    documented project; check signatures/checksums where available.
@@ -96,14 +95,70 @@ yesterday), take the exception **explicitly and on the record**:
   sources (OSV, GHSA, maintainer postmortem).
 - Log it, with a follow-up to confirm the version was not yanked afterward.
 
-No exception is “trivial” — the rule exists because we don’t trust ourselves to eyeball
+No exception is “trivial”—the rule exists because we don’t trust ourselves to eyeball
 which fresh versions are safe.
 **Agents never self-approve an exception**: prepare the record and a human signs off.
 
+### Safe-override patterns (verify, then install surgically)
+
+A release-age gate applies at **version resolution**, so `pkg@latest` (or a bare range)
+silently resolves to the newest version *outside* the window—which can mean you get a
+**stale** version without noticing.
+(This is the dogfood case: an `~/.npmrc` `minimum-release-age` resolved
+`npm i -g get-tbd@latest` to an older release because the newer one was still inside the
+window.) When you genuinely need the fresh version, do not weaken the global
+policy—override **surgically** for the one install, and **verify first**. The pattern is
+always *verify the publisher, timestamp, and integrity → install by an exact,
+resolution-bypassing reference → confirm afterwards.*
+
+**1. Verify before fetching** (publisher identity, publish time, integrity hash):
+
+| Ecosystem | Verify command |
+| --- | --- |
+| npm | `npm view <pkg>@<ver> _npmUser maintainers time.<ver> dist.integrity dist.tarball` |
+| PyPI | `uv pip index versions <pkg>` and inspect the file hashes on `https://pypi.org/project/<pkg>/<ver>/#files` (or `pip download --no-deps --no-binary :all:` then check the hash) |
+| Cargo | `cargo info <pkg>@<ver>` (owners, published-at); crates.io is immutable + checksummed in `Cargo.lock` |
+| Go | `go list -m -json <module>@<ver>` (the proxy returns the checksum DB entry) |
+
+For a package **you maintain** (the dogfood case), the strongest check is that the
+published artifact matches the git tag—confirm the commit/tag and, where the registry
+supports provenance/attestations (npm `--provenance`), that it was built from that
+source.
+
+**2. Install by an exact reference that bypasses version resolution**, so the gate does
+not silently re-resolve:
+
+```bash
+# npm — direct tarball URL (verified in step 1); skips before/min-release-age resolution
+npm install -g https://registry.npmjs.org/<pkg>/-/<pkg>-X.Y.Z.tgz
+
+# npm — git ref (strongest for packages you maintain: the source is auditable)
+npm install -g git+https://github.com/<org>/<repo>#vX.Y.Z
+
+# uv / pip — pin exact, with the hash recorded; --exclude-newer override is per-invocation
+uv pip install "<pkg>==X.Y.Z" --exclude-newer "$(date -u +%Y-%m-%d)"   # one-shot, not global
+
+# cargo / go — pin exact in the manifest; the committed lockfile/sum carries the checksum
+cargo add <pkg>@=X.Y.Z       # then `cargo build --locked`
+go get <module>@vX.Y.Z       # then `go mod verify`
+```
+
+A tarball-URL or git-ref install is the cleanest npm override because it never consults
+`before` / `minimum-release-age` at all (those apply only to range resolution), so you
+do not touch global config or env.
+The uv/cargo/go forms pin an exact version rather than bypassing a gate, since those
+ecosystems gate at the lockfile rather than at resolution.
+
+**3. Keep it surgical and on the record.** The override must affect **one install**, not
+global `~/.npmrc` / env / CI config; carry the same commit/PR record as any exception
+(reason, exact `pkg@version`, the verification output); and **confirm afterwards** that
+the version was not subsequently yanked.
+Never relax the global cool-off to get one fresh package—that re-exposes every install.
+
 ## Node / TypeScript Enforcement (npm, pnpm, Bun)
 
 The hands-on controls for the rules above in the Node ecosystem.
-Applies to **any** repo, not just new monorepos — drop these into an existing project.
+Applies to **any** repo, not just new monorepos—drop these into an existing project.
 
 **Lifecycle-script hygiene (the highest-value control).** Block install/build scripts by
 default and allowlist only what you trust:
@@ -149,7 +204,7 @@ One root lockfile in a monorepo.
 [npm provenance attestations](https://docs.npmjs.com/generating-provenance-statements)
 (TypeScript, Vitest, Prettier, ESLint do).
 Run `pnpm audit signatures` / `npm audit signatures` periodically.
-A provenance badge is necessary, not sufficient — the @antv worm forged one.
+A provenance badge is necessary, not sufficient—the @antv worm forged one.
 
 **CI audit gate** (alongside lint/test):
 
@@ -165,7 +220,7 @@ audit:
       # errorLevel 0 logs but doesn't fail — flip to 2 once the backlog is cleared
 ```
 
-**Pre-push age guard** — a zero-dependency Node script wired into lefthook/husky:
+**Pre-push age guard**—a zero-dependency Node script wired into lefthook/husky:
 
 ```ts
 #!/usr/bin/env tsx
@@ -192,18 +247,18 @@ leave a marker next to the pin (JSONC comment in `package.json`, or a `CHANGELOG
 note for strict JSON parsers): `// Exception: CVE-2026-XXXX patch within 14d window.
 Reviewed <date>.`
 
-## Untrusted Repos & Modes
+## Untrusted Repos and Modes
 
 - **Treat any freshly-cloned third-party repo as untrusted.** Do not run
   `install`/`build`/`test`/`run`/`npx`/`uvx`/`cargo run`/`go run <remote>` against it on
-  a machine with ambient credentials until you’ve reviewed it — ideally in a container
-  or namespace-isolated sandbox.
+  a machine with ambient credentials until you’ve reviewed it—ideally in a container or
+  namespace-isolated sandbox.
   (`build.rs`, proc-macros, `require()`-time payloads, and test files all execute code.)
 - **Modes**: default to **Balanced** (the policy above).
   Enter **Strict** (no upgrade without reviewing the change set; build-script allowlist
   required; mandatory sandbox; CI scanners checksum-verified) when the repo declares it,
   when the repo is untrusted, or on a machine with publish tokens / production access.
-  **Emergency Exception** is a single logged per-command bypass — never self-approved by
+  **Emergency Exception** is a single logged per-command bypass—never self-approved by
   an agent.
 
 ## What This Does and Doesn’t Cover
@@ -212,11 +267,11 @@ A cool-off plus disabled scripts neutralizes the dominant **fast-yanked-incident
 pattern. It does **not** stop: long-lived typosquats that survive past the window; a
 lockfile that already captured a bad version; payloads that fire on import/build rather
 than install; or **publish-pipeline compromises** (the May 2026 @antv worm shipped from
-legitimate CI with a forged “verified” provenance badge — a green badge is not proof).
-Those need lockfile review, typosquat checks, build-time controls, and — if you publish
-packages — the publish-side controls in the guidebook’s `hardening-ci-cd.md` (OIDC
-trusted publishing, staged publishing, SHA-pinned actions, runner egress limits,
-provenance monitoring).
+legitimate CI with a forged “verified” provenance badge—a green badge is not proof).
+Those need lockfile review, typosquat checks, build-time controls, and—if you publish
+packages—the publish-side controls in the guidebook’s `hardening-ci-cd.md` (OIDC trusted
+publishing, staged publishing, SHA-pinned actions, runner egress limits, provenance
+monitoring).
 
 ## Apply It Here (tbd)
 

package/dist/docs/guidelines/tbd-sync-troubleshooting.md

@@ -79,7 +79,7 @@ auto-saving, since the issue is likely temporary.
 
 **What tbd now does:**
 - `mergeIssues()` detects no-op merges and skips the version/timestamp bump
-- `getUpdatedIssues()` ignores `version` and `updated_at` when filtering — only issues
+- `getUpdatedIssues()` ignores `version` and `updated_at` when filtering—only issues
   with actual content changes (title, status, labels, description, etc.)
   are saved
 - When fetch fails, the cached `origin/tbd-sync` ref is used for comparison instead of
@@ -87,7 +87,7 @@ auto-saving, since the issue is likely temporary.
 
 **If you encounter this with an older version:**
 1. Update tbd: `npm install -g get-tbd@latest`
-2. If you already have a large outbox, you can safely import it — the import will merge
+2. If you already have a large outbox, you can safely import it—the import will merge
    using field-level LWW and the trivial changes will be harmless
 3. Run `tbd sync` to clear the outbox
 
@@ -123,7 +123,7 @@ auto-saving, since the issue is likely temporary.
 ### Don’t gitignore .tbd/workspaces/
 
 When `tbd sync` fails and auto-saves to `.tbd/workspaces/outbox/`, a new untracked
-directory appears. Do not add it to `.gitignore` — the outbox must be committed to your
+directory appears. Do not add it to `.gitignore`—the outbox must be committed to your
 working branch so unsynced data survives across sessions.
 
 **What to do instead:**