node-version-discipline

name	node-version-discipline
version	1.1.0
user-invocable	true
description	Node version discipline — before running tsc / eslint / build / test / install in any Node project, align the Node version to the project's declared version (.nvmrc / .node-version / .tool-versions / volta / engines.node) and disclose it in the verification report, preventing false-pass / false-fail when the host default Node mismatches the project-pinned version; when the project declares no Node version at all, ask the user for the version and offer to persist a declaration file so future sessions/CI auto-align. Use this skill whenever the user is about to run a version-sensitive Node command, or mentions Node version mismatch / wrong Node / version conflict. 中文触发词「node 版本对齐」「nvm 对齐」「.nvmrc」「Node 版本纪律」「对齐 Node 版本」「切换 node 版本」「版本不匹配」「初始化 node 版本管理」「为工程增加 node 版本声明」「给工程加 .nvmrc」「无 .nvmrc 时补一个」「工程没有 node 版本管理」, English aliases node version discipline, nvm use, align node version, switch node version, add nvmrc, initialize node version.

Node Version Discipline

Before running any build / lint / type-check / test / install command in a Node project, align the Node version to the project's declared version (probe the full chain: .nvmrc → .node-version → .tool-versions → volta.node → engines.node → CI config). Otherwise verification results are untrustworthy.

1. Why alignment is mandatory

The host's default Node version (e.g. v22) frequently mismatches the project's .nvmrc-pinned version (e.g. v14). Running tsc / eslint / npm run build / npm test on the default version produces:

Risk	Effect
False pass	Higher Node is more permissive — tsc/eslint pass, but the pinned version actually crashes at runtime
False fail	Higher Node breaks legacy toolchains (e.g. Webpack 4 native deps), surfacing build errors unrelated to the code and misdirecting the investigation
Behavioral drift	Older versions lack APIs (structuredClone, AbortController...) — runtime behavior diverges
Dependency resolution skew	node_modules installs native modules for whichever Node is active; mismatch installs the wrong variant

Core lesson: even if a higher version happens to pass and results coincidentally match, the .nvmrc-pinned version is the source of truth. "It passed on a higher version" never justifies skipping alignment.

2. Decision rules

When to align

If the project declares a Node version by any means (see the priority chain below), align before running:

• tsc / npx tsc / npm run type-check
• eslint / npm run lint
• npm run build / webpack / any build script
• npm test / jest / any test command
• npm install / npm ci (installing deps on the wrong version pulls wrong native modules)
• any npm run <script> (scripts may invoke version-sensitive tools internally)

Version-declaration priority chain

.nvmrc is the nvm convention, not the only one. Node version managers disagree on which file they read, so probe the whole chain in order — first hit wins:

#	Source	Kind	Cross-tool notes
1	.nvmrc	exact	nvm + fnm native; asdf needs legacy_version_file; Volta ignores
2	.node-version	exact	fnm / nodenv / nvs native; asdf needs legacy flag; nvm ignores
3	.tool-versions	exact	asdf native
4	package.json → "volta".node	exact	Volta native — the only source Volta reads
5	package.json → engines.node	range	declarative only (npm warns, doesn't enforce unless engine-strict); pick an installed version inside the range
6	CI config node-version (e.g. .github/workflows/*.yml)	exact	inference — label it as such in the report

Walk up the directory tree for files (rows 1-3); read package.json and CI config from the project root. The two cross-tool blind spots in rows 1 and 2 are non-obvious — see §4.

When no declaration exists

If the chain finds nothing, do not silently fall back to the default Node or pick a version on the user's behalf — that is exactly the false-pass/false-fail trap this skill prevents, and guessing a version risks running the whole verification on the wrong Node. Turn the user's answer into a persistent project asset so this round-trip never has to repeat:

1. Stop and ask the user which Node version to use. Prompt with: "This project declares no Node version (no .nvmrc / .node-version / .tool-versions / volta / engines.node / CI pin found). Which Node version should I align to before running [tsc / build / test / ...]?" Wait for the user's answer; do not proceed with a guessed version.
2. Probe the toolchain with the read-only detect_manager snippet (§2.2) to recommend which declaration file fits this project/env. The snippet prints signals only — it does not write anything.
3. Confirm with the user before persisting. Offer to write the recommended declaration file containing the exact version the user just gave (§2.1 picks the file type; the version is the user's, in full X.Y.Z form — e.g. 22.5.0, not a bare major). Persist only after the user agrees; if they decline, skip writing and continue with alignment-only for this session. Either way, align to the stated version (SOP §3) before running the real command.
4. Pure file I/O / git / grep (no Node runtime) needs no alignment and no declaration file.

Why ask rather than default to Active LTS: the "correct" Node for a project depends on context the AI doesn't have — production runtime, CI matrix, teammate environments, legacy constraints. A wrong guess silently invalidates every downstream result. Asking is one cheap round-trip; a false pass/fail can misdirect an entire investigation.

Why persist the answer (not just align once): the user's version choice is high-value engineering information. If it lives only in the conversation, every future session, CI run, and collaborator hits the same "no declaration" wall and may converge on a different version. Writing one small declaration file closes the loop — the next session reads it on the first probe and never asks again.

2.1 Which declaration file to write

Pick the file type from the signals detect_manager (§2.2) reported. First matching row wins; .nvmrc is the catch-all default because nvm/fnm (and asdf with legacy_version_file) all read it, giving the broadest cross-tool coverage.

Signal (from §2.2)	File to write	Content shape	Why this file
package.json already has a volta block, or volta is installed on the host	package.json → volta.node field	"volta": { "node": "22.5.0" } (merge into existing volta object)	Volta reads only this source; a .nvmrc would be invisible to Volta users
asdf installed on host, or project already has a .tool-versions for other languages	.tool-versions (append a line)	nodejs 22.5.0	asdf's native source; keeps all language pins in one file
fnm or nodenv installed (and neither of the above)	.node-version	22.5.0	fnm/nodenv native source; nvm ignores this file, so don't pick it when nvm is the only manager
None of the above / unsure	.nvmrc	22.5.0	Broadest coverage: nvm + fnm native, asdf with legacy_version_file; the safe default

Version format — write the exact patch. Use the full X.Y.Z the user specified (or the exact installed version if the user said "use what's installed" — capture it via node -v and strip the leading v). Do not write a bare major (22) or a range (>=20): a declaration file's job is to pin one reproducible version so every environment converges identically. .nvmrc/.node-version take the bare 22.5.0 (no v prefix, nvm convention); .tool-versions takes nodejs 22.5.0; engines.node/volta.node take the quoted string "22.5.0". (If the user later wants a range for engines.node, that's a separate conscious choice — the persist step here pins exact.)

Persist-then-install order. Write the declaration file first, then handle installation. The file is a statement of intent for CI and collaborators — it does not depend on the local machine having that version. After writing, if ls ~/.nvm/versions/node/ shows the version is missing locally, prompt nvm install <version> (or the manager equivalent) per SOP §3 Step 2, then proceed. This way the project asset exists even if the user defers installation.

Where to write. Project root (same level as package.json). For .nvmrc/.node-version/.tool-versions create a new file; for volta.node/engines.node merge into the existing package.json — never overwrite the file, always edit the JSON in place.

2.2 detect_manager — read-only toolchain probe

Paste-ready, read-only. It prints signals so the AI can pick the right file per §2.1; it must not write any file. Writing is a separate, user-confirmed step (§2 step 3).

# Read-only: detect which Node version manager this project/env uses.
# Prints one signal per line. AI maps them to a declaration file via §2.1.
# Does NOT write anything — persistence is a separate, user-confirmed step.
[ -f package.json ] && node -e "require('./package.json').volta && console.log('volta-struct')" 2>/dev/null
command -v volta  >/dev/null && echo "volta-installed"
command -v asdf   >/dev/null && echo "asdf-installed"
[ -f .tool-versions ] && echo "tool-versions-exists"
command -v fnm    >/dev/null && echo "fnm-installed"
command -v nodenv >/dev/null && echo "nodenv-installed"
# No output above → default to .nvmrc (broadest cross-tool coverage).

The probe detects the manager, not the version. The version always comes from the user (§2 step 1) — never from the host default.

3. Standard Operating Procedure (SOP)

Step 1 — Detect the constraint

# Prefer .nvmrc (walk up the tree)
cat .nvmrc 2>/dev/null
# Fallback to package.json engines
node -e "console.log(require('./package.json').engines?.node || 'no engines constraint')" 2>/dev/null

The snippet above shows the two most common sources for clarity. The full cross-tool priority chain (.nvmrc → .node-version → .tool-versions → volta.node → engines.node → CI config) is implemented as a paste-ready script in §7 — use that in practice.

Step 2 — Confirm the target version is installed

ls ~/.nvm/versions/node/ | grep <target-version>

Not installed → prompt the user to nvm install <version> and stop.

Step 3 — Switch and run in a single command (recommended)

source ~/.nvm/nvm.sh && nvm use <target-version> >/dev/null 2>&1 && node -v && <actual-command>

Shell state is not persistent. nvm use only affects the current shell process. Each Bash tool call may spawn an independent shell, so nvm use does not carry across calls. Every version-sensitive command must do source ~/.nvm/nvm.sh && nvm use <version> && <command> inside the same call — never split into "nvm use first, then run".

Step 4 — Confirm the switch succeeded

After switching, always node -v before the real command. nvm use can fail silently (e.g. target not installed); skipping confirmation risks assuming a switch that never happened.

4. Common error patterns (callers must intercept)

Pattern	Consequence	Correct approach
npx tsc --noEmit directly, ignoring .nvmrc	Untrustworthy result	Detect .nvmrc first, nvm use, then run
Two steps: nvm use 14 then tsc in the next call	Shell state lost, reverts to default	Single call: source && nvm use && cmd
nvm use 14 without node -v	Silent failure mistaken for success	Always node -v after switching
nvm use on an uninstalled version	Errors or silent failure	ls ~/.nvm/versions/node/ first; prompt nvm install if missing
nvm use node / nvm use default	May not hit the .nvmrc version	Use the exact version, or nvm use $(cat .nvmrc)
"Higher version passed" ≡ "pinned version passes"	False pass	Pinned version is the source of truth
Project has .node-version but you're on nvm	nvm ignores .node-version → silent fall-back to default	Probe the full chain (§2); if only .node-version exists, nvm use $(cat .node-version)
Project pins via Volta (package.json "volta") but you're on nvm/fnm	Volta's pin is invisible to nvm/fnm	Read package.json "volta".node and nvm use that exact version

5. Verification report disclosure

When reporting verification results, disclose the Node version — not just pass/fail:

## Code quality
- Node version (.nvmrc v14.21.3): ✅ switched via nvm use
- tsc --noEmit: ✅ 0 errors
- eslint: ✅ no errors/warnings

When the project declared no version and the user supplied one, disclose that fact explicitly so the source is auditable. Distinguish whether the declaration was persisted (so the next session auto-aligns) or only applied this once:

- Node version (user-specified v20.11.0, no prior project declaration): ✅ aligned; persisted to .nvmrc (22.5.0) — future sessions will auto-align

If the user declined to persist, make that explicit so the gap is visible:

- Node version (user-specified v20.11.0, no project declaration): ✅ aligned for this run; user declined to persist — declaration still missing, recommend adding .nvmrc

If a command ran without switching, mark ⚠️ and re-run.

6. Two integration contracts

This skill is the dependee, offering two ways to be referenced.

6.1 Hard-dependency contract (core skills)

For zero-tolerance scenarios where alignment is a hard precondition (tsc / eslint / build):

# in the caller's frontmatter
dependencies:
  - node-version-discipline

The caller runs a precondition check at startup (same pattern as solve-workflow): if this skill is absent, abort immediately and prompt to install. No silent degradation — guarantees trustworthy verification in any environment.

6.2 Soft-reference contract (extension skills)

For scenarios where alignment is best practice (npm test / browser debug / general engineering commands), add one line at the relevant step in the caller body:

Before running, invoke the node-version-discipline skill to align Node to .nvmrc.

No dependencies declared, no precondition check — relies on the AI invoking it consciously at that step.

7. Self-contained detection script (paste-ready)

# Probe the full version-declaration chain (cross-tool), then switch via nvm.
# First hit in priority order wins. See §2 for why we probe beyond .nvmrc.
probe_file() {  # $1 = filename; prints a version walking up the tree
  for d in . .. ../.. ../../..; do
    [ -f "$d/$1" ] && { cat "$d/$1" | grep -Eo 'v?[0-9]+(\.[0-9]+){0,2}' | head -1 | sed 's/^v//'; return; }
  done
}
NODE_VER="$(probe_file .nvmrc)"
[ -z "$NODE_VER" ] && NODE_VER="$(probe_file .node-version)"
[ -z "$NODE_VER" ] && NODE_VER="$(probe_file .tool-versions)"
# package.json: volta.node (exact) preferred over engines.node (range — handled manually)
if [ -z "$NODE_VER" ] && [ -f package.json ]; then
  NODE_VER="$(node -e "const p=require('./package.json'); console.log(p.volta?.node || '')" 2>/dev/null)"
fi
if [ -n "$NODE_VER" ]; then
  source ~/.nvm/nvm.sh 2>/dev/null && nvm use "$NODE_VER" >/dev/null 2>&1
  echo "✅ Node: $(node -v) (aligned to $NODE_VER)"
else
  echo "ℹ️ No declaration found — STOP and ask the user which Node version to use (do not guess). Current host default: $(node -v)"
  echo "   Then run detect_manager (§2.2) to pick a declaration file, confirm with the user, and persist it (§2.1) so future sessions auto-align."
fi

8. Fallback for non-nvm environments

The SOP assumes nvm (Unix / macOS). Other environments:

Environment	Fallback action
Windows	Prompt the user to switch manually (nvm-windows / volta use); mark ⚠️ "not auto-aligned, confirm version manually" in the report
fnm / volta / asdf	Replace nvm use with the equivalent (fnm use / volta pin / asdf local nodejs <version>)
Container / CI	Node version is fixed by the image; confirm the image version matches .nvmrc

Never pretend alignment happened — always state explicitly when auto-alignment was not performed.

9. Related

• Origin: a real-world fix where a mobile project pinned .nvmrc = v14.21.3 while the host defaulted to v22, producing tsc/eslint false-passes under the higher version.
• No-declaration path: when a project declares no Node version at all, §2 turns the user's answer into a persistent declaration file (§2.1 picks the type via §2.2's toolchain probe), closing the loop so the next session reads it on the first probe instead of asking again.
• Referenced by: PDCA hosts and related tools via frontmatter dependencies (hosts are SoT; this skill does not maintain an integrator name list). test-suite-ensure may soft-reference alignment before tests.