chore(ci): make vendor upgrade PRs self-consistent so Validate is green by construction

[theCodeDrift]

What

The bot pin-bump workflows (vale-upgrade.yml → vendor/vale/upgrade, ast-grep-upgrade.yml → vendor/ast-grep/upgrade) now produce a commit that is self-consistent under engine-version-consistency.test.ts, and run that test before vendor-pr.cjs pushes anything.

Why

VALE_VERSION / AST_GREP_VERSION in packages/cli/src/rules/capabilities.ts are maintained by hand, and test/engine-version-consistency.test.ts holds them to the pins in packages/cli/package.json. That check is deliberate and the constant is deliberately not derived from package.json (the test's docblock says why). The bot moved only the pins, so every bot PR failed Validate by construction.

Today's instance: #368 (red) with child #372, which had to carry the constant, the regenerated Vale vocabulary and a test literal along with its real work, and the stack could not use GitHub's landing because its base was red. Neither open PR is affected by this change; see the rollout note.

What the bot now does

Both engines

• --write in sg-detect.cjs / vale-upgrade-detect.cjs also rewrites the export const <NAME> = "…"; line in capabilities.ts, via a new bumpVersionConstant in pin-bump.cjs. It anchors on the exact declaration, fails the run unless it is found exactly once, and leaves every other byte alone (a {@link VALE_VERSION} or a version in a docblock is not a candidate). Covered by node --test: constant rewritten, unrelated constant untouched, missing declaration throws, doubled declaration refused, idempotent.
• After the lockfile is regenerated, pnpm install (registry-only, default GITHUB_TOKEN, no NODE_AUTH_TOKEN; under CI pnpm applies --frozen-lockfile itself and the just-regenerated lockfile satisfies it).
• pnpm --filter @taskless/cli test --project cli engine-version-consistency before vendor-pr.cjs. It needs no build. A failure fails the run and proposes nothing.
• The regenerated artifacts are added to the staged paths.

Vale: VALE_VERSION takes the base version (3.22.0, not the stamp). pnpm --filter @taskless/cli generate:vale-schema regenerates src/generated/vale-vocabulary.ts and vale-vocabulary-report.md from the new binary. Its generator refuses a binary that does not report VALE_VERSION, which is why the constant moves first, and vale-rule.ts typechecks VALE_VOCABULARY_VERSION against VALE_VERSION, which is why the vocabulary has to move at all.

ast-grep: pnpm --filter @taskless/cli generate:ast-grep-schema refetches src/generated/ast-grep-rule-schema.json from raw.githubusercontent.com by the new tag. The job already reaches GitHub for release notes, so this is the same network. The script used to stamp a wall-clock time into $comment, which would have made the artifact differ on every scheduled run and defeated vendor-pr.cjs's "unchanged, do not force-push" guard; the stamp is dropped (the version and URL are the provenance, git has the date). The committed schema is regenerated here and the comment is the only byte that changed.

What stays in the child PR

Judgment, not bookkeeping: the measured vendor contract (vale-vendor-contract, vale-schema-contract, ast-grep-vendor-contract), the update ledger, any migration, and the changeset prose.

One deliberate deviation from the brief: the contract tests are not in the bot's gate, only engine-version-consistency is. They hold a recorded corpus of what the binary does, so a new engine that adds a language or changes a verdict fails them, correctly, and the fix is exactly the child's work. Gated in the bot job, that signal would become a scheduled run failing every day with no PR and no changelog to read; left on Validate, it is a red check on a PR that already carries upstream's notes. Measured: rewinding ast-grep to 0.45.2 through the exact workflow steps passed engine-version-consistency and failed four behaviours the contract recorded at 0.45.3. So "green by construction" means the bookkeeping is consistent; a red contract on a bot PR is upstream telling us something.

Also

• test/reconcile-marker.test.ts asserted { sg: "0.45.3", vale: "3.21.0" } as literals. It now asserts against the constants; the test is about the marker carrying the engine versions, not their values. Other version literals under test/ are measured facts ("changed at 0.45.3", a "Vale 3.21.0" block) and stay.
• Header comments of both workflows and the engine-version-consistency docblock describe the new division of labour. Validate is untouched and the consistency test is not weakened.

How verified

Locally, in a worktree:

• pnpm test:scripts (453 pass), pnpm typecheck, pnpm lint (builds, then pnpm cli check: no issues), pnpm --filter @taskless/cli test (96 files, 1588 pass), prettier --check on every touched file, both workflows parsed with the yaml package. actionlint is not installed here.
• Vale, end to end, against the real registry (3.22.0 is ahead of the pin today): node .github/scripts/vale-upgrade-detect.cjs --write moved six pins and VALE_VERSION 3.21.0 → 3.22.0; pnpm install --lockfile-only --ignore-scripts; CI=1 pnpm install; generate:vale-schema against the 3.22.0 binary (6s, diff is the version string only, prettier-clean); pnpm --filter @taskless/cli test --project cli engine-version-consistency vale-schema-contract 21/21 pass, with the binary-spawning assertion confirmed to run against the 3.22.0 package; pnpm --filter @taskless/cli typecheck clean. Then reverted and reinstalled.
• ast-grep, rewound to 0.45.2 via bumpPins + bumpVersionConstant, then the same lockfile / install / generate:ast-grep-schema / test steps: engine-version-consistency passed, ast-grep-vendor-contract failed on four 0.45.3-measured behaviours (the case described above). Then reverted.
• pnpm … test -- <filter> with a literal -- reaches vitest and runs the whole suite; the workflow steps omit it.

The workflows themselves run next on the next upstream release (Vale daily, ast-grep weekly, or workflow_dispatch).

Rollout

No effect on the open #368/#372: those branches were built by the old workflow and land as planned. The next bot PR is the first exercise. If vale-upgrade.yml is dispatched after this merges and before #368 lands, vendor-pr.cjs will rebuild vendor/vale/upgrade from main with the fuller commit; its foreign-commit guard still refuses to touch a branch with a human commit on it.

[theCodeDrift]

@claude /review

[claude]

Claude finished @theCodeDrift's task in 8m 15s —— View job

---

Review complete

Review mode: incremental — read 0 prior review thread(s) before reviewing. .prior-review.json contains no reviewThreads and no reviews, only the @claude /review trigger comment itself — this is the first review of this PR, so the full diff was assessed from scratch (nothing to classify as already-addressed).

• Read .prior-review.json
• Fetch PR diff and metadata (gh pr diff 374, gh pr view)
• Review each changed file (all 12: pin-bump.cjs/test, sg-detect.cjs/test, vale-upgrade-detect.cjs/test, both workflow YAMLs, fetch-ast-grep-schema.ts, the generated schema, and both test files under packages/cli/test/)
• Post findings

Overall assessment: this is a well-reasoned, well-tested change — bumpVersionConstant's anchor was verified against the actual capabilities.ts declarations (both match exactly), the new tests cover the missing/duplicated-declaration and untouched-neighbour cases thoroughly, and the workflow step ordering (bump → lockfile → real install → regenerate artifacts → consistency check → propose) is sound. I found one real correctness gap and two minor cleanups, posted inline:

1. .github/scripts/sg-detect.cjs (and the same pattern in vale-upgrade-detect.cjs) — writeFileSync(packageJsonPath, bumped) now happens before the new bumpVersionConstant(...) call, which can throw (renamed/missing/duplicated constant). That leaves package.json bumped on disk while capabilities.ts is untouched, directly contradicting the file's own comment that "the file on disk is either fully bumped or untouched." Masked in CI because the ephemeral checkout is discarded on step failure, but real for a local --write run and worth fixing (validate/compute both writes before persisting either) or at least updating the stale comment.
2. Both upgrade workflows — the new Install step runs a plain unfiltered pnpm install, pulling in every workspace package's dependencies when only @taskless/cli's closure is needed for the schema regen + consistency check. pnpm install --filter @taskless/cli... would be cheaper on every scheduled run.
3. vale-upgrade-detect.cjs — minor: baseVersion(upstream) is now called a third time; could be computed once and reused.

No security issues, no test-adequacy gaps beyond what's noted above, and no CLAUDE.md convention violations found in the diff.

[theCodeDrift]

Re: @claude[bot] — "Claude finished @theCodeDrift's task in 8m 15s — Review complete…"
#374 (comment)

Read. The medium item (filtered pnpm install) was measured and is a no-op in this workspace; replied and resolved on the thread. The three low items (partial write before the constant rewrite, baseVersion computed three times) are collected for the owner's call and left open. Branch rebased onto main at fd896f9, which brought in the Vale 3.22.0 upgrade; the reconcile-marker assertion now reads the constants, so it needed no literal.

— AI Coding Agent