feat: add the check-forge-version skill (ENG-124)

[zanjonke]

Users have no way to learn that their installed plain-forge is behind the published one, so they keep following skills and rules from a superseded release without knowing it. This adds a skill that tells them.

check-forge-version enumerates every directory plain-forge can install into (both scopes, all agent layouts), reads the installed version from each .plain-forge/manifest.json, resolves the latest version from npm, and emits a PASS / WARN / FAIL verdict. For a stale install it surfaces npx plain-forge update and asks the user to run it — the skill never runs the update itself and modifies nothing on disk.

The subject is the tooling, not any project: it reads no .plain files, needs no project in the working directory, works in an empty dir, and deliberately does not invoke load-plain-reference.

Contents

• forge/skills/check-forge-version/SKILL.md — frontmatter validated by skill-creator's validate-metadata.py (1020/1024 chars, third person, positive + negative triggers).
• forge/skills/check-forge-version/scripts/check-forge-version.mjs — the deterministic half. Zero dependencies, Node ≥ 18.
• forge/skills/load-plain-reference/SKILL.md — a call to action to run the check on its first invocation in a session. It is the near-universal entry point for spec work, and a stale forge ships the stale rules it routes to. Informs and recommends; does not block authoring.

Design notes

The script mirrors bin/cli.mjs rather than re-deriving anything — the install-path model (including the two global paths that break the usual pattern, ForgeCode's ~/forge and OpenCode's ~/.config/opencode), the .agents dedupe across three agent labels, the manifest-less fallback via the four flagship skills, and compareVersions' dotted-numeric semantics. Keep them in sync.

The verdict is both the first line of stdout and the exit code, so callers need not parse the body. The registry endpoint falls back to npm view for hosts on an internal mirror.

Messaging is deliberately insistent (fa6596f). The first cut reported a stale install as a neutral aside, which reads as optional housekeeping; the report now leads with ACTION REQUIRED, says why continuing is not recommended, and notes the fix is one command that cannot touch the user's own content. PASS stays a single quiet line.

Two bugs caught by testing it as installed

Both fixed in ee84478, and both only surfaced by running the skill the way SKILL.md tells the agent to:

1. Run from its own directory — the natural reading of node scripts/check-forge-version.mjs — the script scanned the skill folder as a project root and reported NONE from inside a live install. It now locates its own install by walking up its own path. A false "not installed" is the worst failure mode for this check.
2. That walk then reported the source repo as an UNMANAGED install, since forge/ also contains a skills/ subtree. It now excludes the tree sitting next to the package's own package.json, while still recognising ForgeCode's ~/forge.

Testing

npm test — 58/58 passing. No CLI behaviour changed, so test/cli.test.mjs needed no updates; the new skill is content the installer copies like any other.

Verified against a real install built with the CLI in a temp HOME/cwd, from four invocation sites (skill dir, project root, unrelated dir, source checkout):

Installed	Verdict	Exit
latest	PASS / CURRENT	0
behind	FAIL / STALE	1
prerelease	WARN / INDETERMINATE	2
manifest removed	WARN / UNMANAGED	2
empty dir	NONE	4

Not exercised: the ERROR path (exit 3) needs the registry and npm view to both fail. The fallback logic is simple but untested.

Notes for review

• Two deliberate non-changes, easy to reverse if you disagree: the skill only reports (never runs update, following check-plain-env's precedent), and it does not hard-block — the user is asked and may decline, and authoring continues.
• Local iteration gotcha worth knowing: update short-circuits when the manifest version equals package.json's, so editing forge/ and running update re-copies nothing. Use uninstall + install.