feat(init): name a package.json pin older than the running CLI

An upgrade through a launcher leaves the project's own pins alone, and
those pins are what CI, scripts and git hooks run. After a migration, a
pin that predates the new schema refuses the project with
SCAFFOLD_VERSION_MISMATCH, so CI breaks on the push carrying the
migrated files.

init (batch and wizard) now names every bounded pin of @taskless/cli or
@taskless/cli-nightly that cannot reach the running version, in the
dependency fields or spelled out in a script, and offers the bump
without editing package.json. After a migration the notice states the
breakage as certain and ties the bump to the same commit as .taskless/.
init --json carries the pins as pinnedCli, and the update recipe (topic
v11) tells an agent to offer the bump.

Author: theCodeDrift

.changeset/init-stale-cli-pins.md

@@ -0,0 +1,5 @@
+---
+"@taskless/cli": patch
+---
+
+`taskless init` names any `package.json` pin of `@taskless/cli` (a dependency entry, or a script spelling out `@taskless/cli@<version>`) that cannot resolve to the CLI that just ran, and offers bumping it as part of the upgrade. Scripts, CI and git hooks run that pin, and a CLI older than the project's `.taskless/` refuses the layout. The install does not edit `package.json`. `init --json` carries the pins as `pinnedCli`, and the `update` recipe (topic v11) tells an agent to offer the bump.

openspec/changes/archive/2026-10-05-init-stale-cli-pins/proposal.md

@@ -0,0 +1,55 @@
+## Why
+
+An upgrade is usually run through a launcher, `npx @taskless/cli@latest init`,
+and the launcher leaves the project's own pins alone. A `devDependencies` entry
+of `^0.10.2`, or a script spelling out `npx @taskless/cli@0.10.2 check`, is
+what CI, a git hook and `pnpm lint` actually run. After the upgrade those run a
+CLI older than the `.taskless/` it now finds, and an older CLI refuses a layout
+newer than it understands ("Upgrade the CLI to continue"). Nothing about the
+upgrade itself fails, so the first sign is a red CI run on the next push, and it
+does not read as an upgrade problem when it arrives.
+
+The upgrade trailer already tells the caller what to commit and that `update`
+exists. It says nothing about the one other place the upgrade is incomplete.
+
+## What Changes
+
+- `taskless init`, both the batch path and the wizard, reads `package.json` in
+  the working directory and names every pin of `@taskless/cli` or
+  `@taskless/cli-nightly` whose ceiling sits below the running CLI: an exact
+  version, or a `^`/`~` range that cannot reach it, in `dependencies`,
+  `devDependencies`, `optionalDependencies`, or spelled out in a script. It
+  offers the bump; it does not make it.
+- When the same run migrated `.taskless/`, the notice states the breakage as
+  certain rather than likely: a CLI that predates the new schema refuses the
+  project with `SCAFFOLD_VERSION_MISMATCH`, so CI breaks on the push carrying
+  the migrated files, and the bump belongs in that same commit.
+- `init --json` carries the pins as `pinnedCli`, always present, empty when
+  nothing is stale.
+- The `update` recipe goes to topic v11 with a step telling the agent to offer
+  the bump as part of the upgrade, without making it silently.
+- `compareVersions` moves from `reconcile-marker.ts` to
+  `util/version-compare.ts`, unchanged, so both callers share it.
+
+## Capabilities
+
+### New Capabilities
+
+None.
+
+### Modified Capabilities
+
+- `cli-init`: one ADDED requirement. No standing requirement is restated,
+  renamed or removed. The notice is separate from the upgrade trailer, so the
+  standing "a no-op re-install prints no upgrade trailer" scenario still holds.
+
+## Impact
+
+Additive output on `init`, plus one envelope field. `patch`: the package is
+pre-1.0. A spec this change cannot bound (`latest`, `*`, `>=`, `workspace:`, a
+URL) is not reported, so a project that floats its pin sees nothing new.
+
+## Delivery shape
+
+**Single PR.** The spec, detector, wiring, recipe step and tests are one small
+reviewable diff. It is the tip, so the change is archived here.

openspec/changes/archive/2026-10-05-init-stale-cli-pins/specs/cli-init/spec.md

@@ -0,0 +1,54 @@
+## ADDED Requirements
+
+### Requirement: Init names a package.json pin older than the running CLI
+
+After a successful install, `taskless init` SHALL read `package.json` in the working directory and report every pin of `@taskless/cli` or `@taskless/cli-nightly` that cannot resolve to the running CLI's version or later. A pin is:
+
+- an entry in `dependencies`, `devDependencies`, or `optionalDependencies`; or
+- a script in `scripts` that spells out `@taskless/cli@<spec>` or `@taskless/cli-nightly@<spec>`.
+
+A pin SHALL be reported only when its spec is bounded and its bound sits below the running version: an exact version (optionally prefixed `=` or `v`), or a `^` or `~` range whose exclusive ceiling is at or below the running version, with caret ranges holding the left-most non-zero part as npm does. Versions SHALL be compared on their numeric core, ignoring a prerelease suffix. A spec the CLI cannot bound (`latest`, `*`, a comparator range, `workspace:`, a URL or git spec) SHALL NOT be reported. An absent or unparseable `package.json` SHALL produce no report and SHALL NOT fail the install.
+
+The install SHALL NOT modify `package.json`. The report SHALL offer the bump rather than claim it.
+
+On the human path (batch and wizard), when at least one pin is reported, the CLI SHALL print a notice naming each pin's location (the dependency field, or `scripts.<name>`), package and spec, stating that what runs those pins runs a CLI older than the project, and offering to update them to the running version. The notice SHALL print whether or not the run changed anything. On the batch path it SHALL print after the upgrade trailer, and the onboarding trailer SHALL remain the final line.
+
+When the same run migrated `.taskless/`, the notice SHALL NOT hedge. It SHALL name the schema version the run wrote, state that a CLI predating that schema refuses the project with `SCAFFOLD_VERSION_MISMATCH` so CI running the pins will break on the push carrying the migrated files, and say the bump belongs in the same commit as `.taskless/`. Without a migration the notice SHALL describe the failure as likely, not certain.
+
+Under `--json`, the envelope SHALL carry `pinnedCli`: an array of `{ location, name, spec }`, present on every successful run and empty when nothing is stale.
+
+#### Scenario: A stale dependency and script pin are named and left alone
+
+- **WHEN** `taskless init` runs at version `V` in a project whose `package.json` has `devDependencies["@taskless/cli"]` set to a version below `V`, and a script running `npx @taskless/cli@<older>`
+- **THEN** stdout SHALL name both pins with their location and spec, and offer updating them to `V`
+- **AND** `package.json` SHALL be byte-identical afterwards
+- **AND** the notice SHALL appear after the upgrade trailer, with the onboarding trailer still the final line
+
+#### Scenario: A pre-1.0 caret range that cannot reach the running version is stale
+
+- **WHEN** `package.json` pins `@taskless/cli` at `^0.10.2` and the running CLI is `0.11.2`
+- **THEN** the pin SHALL be reported
+
+#### Scenario: A floating or current pin is not reported
+
+- **WHEN** `package.json` pins `@taskless/cli` at `latest`, `*`, `>=0.10.0`, `workspace:*`, or a range that admits the running version, or a script runs `@taskless/cli@latest`
+- **THEN** no pin SHALL be reported
+
+#### Scenario: A migration makes the breakage definite
+
+- **WHEN** `taskless init` migrates `.taskless/` to schema version `N` in a project with a stale pin
+- **THEN** the notice SHALL name schema version `N` and `SCAFFOLD_VERSION_MISMATCH`
+- **AND** SHALL state that CI running the pins will break, and that the bump belongs in the same commit as `.taskless/`
+- **AND** SHALL NOT describe the failure as merely likely
+
+#### Scenario: A stale pin is named on a re-install that changed nothing
+
+- **WHEN** `taskless init` runs against a project that is already current and whose `package.json` holds a stale pin
+- **THEN** stdout SHALL NOT contain the upgrade trailer
+- **AND** stdout SHALL name the stale pin
+
+#### Scenario: The JSON envelope carries the pins
+
+- **WHEN** `taskless init --json` runs
+- **THEN** the envelope SHALL contain `pinnedCli`, an array with one `{ location, name, spec }` entry per stale pin
+- **AND** `pinnedCli` SHALL be an empty array when there is no `package.json` or nothing in it is stale

openspec/changes/archive/2026-10-05-init-stale-cli-pins/tasks.md

@@ -0,0 +1,36 @@
+## 1. Spec
+
+- [x] 1.1 Add the requirement to `cli-init` as an ADDED block, separate from
+      the upgrade trailer, so no standing requirement is restated and the
+      no-op scenario keeps holding.
+- [x] 1.2 Dry-run `openspec archive` and compare the scenario count in
+      `cli-init` before and after.
+
+## 2. Detector
+
+- [x] 2.1 Move `compareVersions` to `util/version-compare.ts`, unchanged.
+- [x] 2.2 `install/pinned-cli.ts`: read `package.json`, report bounded pins
+      whose ceiling is at or below the running version, in the three
+      dependency fields and in scripts.
+- [x] 2.3 Treat an absent or unparseable `package.json` as no pins.
+
+## 3. Wiring
+
+- [x] 3.1 Batch `init`: print the notice after the upgrade trailer, not gated
+      on the run having changed anything; add `pinnedCli` to the envelope.
+- [x] 3.2 Wizard: print the notice after the outro.
+- [x] 3.3 When the run migrated, state the breakage as certain: name the
+      schema version and `SCAFFOLD_VERSION_MISMATCH`, and put the bump in the
+      same commit as `.taskless/`.
+
+## 4. Recipe
+
+- [x] 4.1 `update` topic v11: a step offering the bump, without making it
+      silently, before recording the walk.
+
+## 5. Tests
+
+- [x] 5.1 Detector: the spec table in both directions, every dependency
+      field, the nightly name, scripts, an unreadable `package.json`.
+- [x] 5.2 Integration: notice order and content, `package.json` untouched,
+      the no-op re-install, and the `--json` field.

openspec/specs/cli-init/spec.md

@@ -825,3 +825,56 @@ The `migrated` field is unchanged: present with the migration report when a migr
 - **WHEN** `taskless init --json` runs
 - **THEN** the envelope SHALL contain `cliVersion.previous` (a string or `null`), `cliVersion.installed`, a `targets` array with one entry per install target, and a boolean `changed`
 - **AND** `changed` SHALL be `true` exactly when `migrated` is present, any target's written or removed list is non-empty, or `cliVersion.previous` is non-null and differs from `cliVersion.installed`
+
+### Requirement: Init names a package.json pin older than the running CLI
+
+After a successful install, `taskless init` SHALL read `package.json` in the working directory and report every pin of `@taskless/cli` or `@taskless/cli-nightly` that cannot resolve to the running CLI's version or later. A pin is:
+
+- an entry in `dependencies`, `devDependencies`, or `optionalDependencies`; or
+- a script in `scripts` that spells out `@taskless/cli@<spec>` or `@taskless/cli-nightly@<spec>`.
+
+A pin SHALL be reported only when its spec is bounded and its bound sits below the running version: an exact version (optionally prefixed `=` or `v`), or a `^` or `~` range whose exclusive ceiling is at or below the running version, with caret ranges holding the left-most non-zero part as npm does. Versions SHALL be compared on their numeric core, ignoring a prerelease suffix. A spec the CLI cannot bound (`latest`, `*`, a comparator range, `workspace:`, a URL or git spec) SHALL NOT be reported. An absent or unparseable `package.json` SHALL produce no report and SHALL NOT fail the install.
+
+The install SHALL NOT modify `package.json`. The report SHALL offer the bump rather than claim it.
+
+On the human path (batch and wizard), when at least one pin is reported, the CLI SHALL print a notice naming each pin's location (the dependency field, or `scripts.<name>`), package and spec, stating that what runs those pins runs a CLI older than the project, and offering to update them to the running version. The notice SHALL print whether or not the run changed anything. On the batch path it SHALL print after the upgrade trailer, and the onboarding trailer SHALL remain the final line.
+
+When the same run migrated `.taskless/`, the notice SHALL NOT hedge. It SHALL name the schema version the run wrote, state that a CLI predating that schema refuses the project with `SCAFFOLD_VERSION_MISMATCH` so CI running the pins will break on the push carrying the migrated files, and say the bump belongs in the same commit as `.taskless/`. Without a migration the notice SHALL describe the failure as likely, not certain.
+
+Under `--json`, the envelope SHALL carry `pinnedCli`: an array of `{ location, name, spec }`, present on every successful run and empty when nothing is stale.
+
+#### Scenario: A stale dependency and script pin are named and left alone
+
+- **WHEN** `taskless init` runs at version `V` in a project whose `package.json` has `devDependencies["@taskless/cli"]` set to a version below `V`, and a script running `npx @taskless/cli@<older>`
+- **THEN** stdout SHALL name both pins with their location and spec, and offer updating them to `V`
+- **AND** `package.json` SHALL be byte-identical afterwards
+- **AND** the notice SHALL appear after the upgrade trailer, with the onboarding trailer still the final line
+
+#### Scenario: A pre-1.0 caret range that cannot reach the running version is stale
+
+- **WHEN** `package.json` pins `@taskless/cli` at `^0.10.2` and the running CLI is `0.11.2`
+- **THEN** the pin SHALL be reported
+
+#### Scenario: A floating or current pin is not reported
+
+- **WHEN** `package.json` pins `@taskless/cli` at `latest`, `*`, `>=0.10.0`, `workspace:*`, or a range that admits the running version, or a script runs `@taskless/cli@latest`
+- **THEN** no pin SHALL be reported
+
+#### Scenario: A migration makes the breakage definite
+
+- **WHEN** `taskless init` migrates `.taskless/` to schema version `N` in a project with a stale pin
+- **THEN** the notice SHALL name schema version `N` and `SCAFFOLD_VERSION_MISMATCH`
+- **AND** SHALL state that CI running the pins will break, and that the bump belongs in the same commit as `.taskless/`
+- **AND** SHALL NOT describe the failure as merely likely
+
+#### Scenario: A stale pin is named on a re-install that changed nothing
+
+- **WHEN** `taskless init` runs against a project that is already current and whose `package.json` holds a stale pin
+- **THEN** stdout SHALL NOT contain the upgrade trailer
+- **AND** stdout SHALL name the stale pin
+
+#### Scenario: The JSON envelope carries the pins
+
+- **WHEN** `taskless init --json` runs
+- **THEN** the envelope SHALL contain `pinnedCli`, an array with one `{ location, name, spec }` entry per stale pin
+- **AND** `pinnedCli` SHALL be an empty array when there is no `package.json` or nothing in it is stale

packages/cli/src/agent/update.md

@@ -1,4 +1,4 @@
-# Topic: update     (CLI v%(CLI_VERSION)s / topic v10)
+# Topic: update     (CLI v%(CLI_VERSION)s / topic v11)
 
 ## You are here
 This is `update`. It tells you what an upgrade changed for the rules
@@ -54,7 +54,27 @@ that you finished.
    it means for existing rules. A section that says there is nothing to
    do means exactly that; it is a claim, not an oversight.
 
-4. **Record that you finished.** Run:
+4. **Offer to bump a pinned CLI.** If `package.json` pins
+   `@taskless/cli` (a dependency entry, or a script spelling out
+   `@taskless/cli@<version>`) below the installed CLI, `init` named each
+   pin when it upgraded the project, and `init --json` carries them as
+   `pinnedCli`. Those pins are what scripts, CI, and git hooks run.
+
+   If the upgrade also migrated `.taskless/` (`init` printed a migration,
+   or `init --json` carried `migrated`), this is not optional advice: a
+   CLI that predates the new schema refuses the project with
+   `SCAFFOLD_VERSION_MISMATCH`, so CI breaks on the push that carries the
+   migrated files. The bump belongs in that same commit. Without a
+   migration the pin still reads the layout, but checks rules against
+   engines this walk has moved past.
+
+   Offer the user the bump to the installed version, along with
+   reinstalling dependencies. Do not make it silently: a pin can be
+   deliberate, and the bump changes the lockfile. The walk does not
+   depend on the answer, so record it either way, but if they decline
+   after a migration, tell them plainly that CI will fail.
+
+5. **Record that you finished.** Run:
    ```
    %(TASKLESS_CLI)s update --rules
    ```

packages/cli/src/commands/init.ts

@@ -16,6 +16,11 @@ import { getMandatorySkillNames } from "../install/catalog";
 import type { InstallMode } from "../install/state";
 import { getReloadNotice, versionMoved } from "../install/reload-notice";
 import { getUpgradeTrailer } from "../install/upgrade-trailer";
+import {
+  findStalePins,
+  getPinnedCliNotice,
+  type PinnedCli,
+} from "../install/pinned-cli";
 import { readInstallState } from "../install/state";
 import { getTelemetry } from "../telemetry";
 import { getCliVersion } from "../wizard/intro";
@@ -120,6 +125,9 @@ export const initCommand = defineCommand({
           // is the one value an agent gates its commit step on, and folding
           // four lists and a presence check is how a consumer gets it wrong.
           changed: result.changed,
+          // Always present, empty when nothing is stale, for the same reason
+          // `cliVersion.previous` is `null` rather than absent.
+          pinnedCli: result.pinnedCli,
           // Absent when nothing ran, so a caller distinguishes "the tree was
           // rewritten" from "nothing happened" by presence, never by reading
           // empty arrays out of it.
@@ -147,6 +155,17 @@ export const initCommand = defineCommand({
       if (upgradeTrailer !== undefined) {
         console.log(upgradeTrailer);
       }
+      // Not gated on the run having changed anything. A re-install that wrote
+      // nothing still leaves the pin and the project disagreeing, and this is
+      // the one place that looks.
+      const pinnedNotice = getPinnedCliNotice(
+        result.pinnedCli,
+        result.cliVersion,
+        { migratedTo: result.migrated?.to }
+      );
+      if (pinnedNotice !== undefined) {
+        console.log(pinnedNotice);
+      }
       if (result.reloadNotice !== undefined) {
         console.log(result.reloadNotice);
       }
@@ -315,6 +334,8 @@ async function runNonInteractive(
   targets: TargetOutcome[];
   /** Whether a migration ran or any target wrote or removed anything. */
   changed: boolean;
+  /** `package.json` pins that cannot resolve to the CLI that ran this. */
+  pinnedCli: PinnedCli[];
 }> {
   // Under `--json`, stdout carries only the envelope printed by the caller.
   // This per-target summary is not on that envelope (it is finer-grained than
@@ -466,6 +487,7 @@ async function runNonInteractive(
       migrated !== undefined ||
       targets.some((target) => targetChanged(target)) ||
       versionMoved({ previousCliVersion, cliVersion }),
+    pinnedCli: await findStalePins(cwd, cliVersion),
   };
 }