plain-forge 1.0.20 → 1.0.21-next.55f13d7

package/forge/rules/module-structure.md

@@ -0,0 +1,105 @@
+---
+description: File-level structure of .plain modules — frontmatter, sections, ordering, and section ownership
+---
+
+# Rules for `.plain` module structure
+
+When creating a new `.plain` file or reviewing the structure of a whole file, always follow these rules. Section *content* rules live in the per-section rule files linked below — this file covers only file-level structure.
+
+## File skeleton
+- A `.plain` file is one **module**: optional YAML frontmatter between `---` markers, followed by sections marked with `***section name***` headers
+- The frontmatter, when present, must be the first thing in the file
+- Every content line inside a section must be a `- ` list item — see `bullet-continuation.md`
+- Every line must be as short and plain as its content allows — see `concise-specs.md`
+
+## Frontmatter fields
+
+| Field | Purpose | Rule file |
+|---|---|---|
+| `description` | One-line summary of the module; recommended on every module | — |
+| `import` | Pull definitions, implementation reqs, and test reqs from import modules | `import-modules.md` |
+| `requires` | Attach the module to the build chain of another root module | `requires-modules.md` |
+| `exported_concepts` | Declare which of this module's concepts are visible to modules that `require` it | `exported-concepts.md` |
+| `required_concepts` | Declare concepts an import module expects the importing module to define | `required-concepts.md` |
+
+## Sections
+- There are exactly four top-level section markers: `***definitions***`, `***implementation reqs***`, `***test reqs***`, and `***functional specs***`
+- Each section appears **at most once** per file; all are optional (which ones are allowed depends on the module kind below)
+- `***acceptance tests***` is **never a top-level section** — it appears only nested under a single functional spec (see `func-specs.md`)
+- Write sections in canonical order: `***definitions***` → `***implementation reqs***` → `***test reqs***` → `***functional specs***`
+  - Definitions come first because every concept must be defined before it is referenced
+  - Functional specs come last because they are rendered incrementally and their nested acceptance tests close the file
+
+## Module kinds
+- A **root module** lives at the repository root and carries behavior: it contains `***functional specs***`
+- To be renderable, a root module needs at least one functional spec plus the implementation reqs to build it — its own or from an `import`ed module (implementation reqs are not inherited through `requires`). A frontmatter-only file is a valid scaffold, but it cannot be rendered until a functional spec is added
+- A **requires module** is a root module that is used by another root module via `requires` directive (see `requires-modules.md`)
+- An **import module** provides shared content that other modules pull in via `import`: it contains only `***definitions***`, `***implementation reqs***`, and/or `***test reqs***` — never `***functional specs***`, never `requires` (see `import-modules.md`)
+
+## Section ownership (where a fact lives)
+- The renderer reads each kind of fact **only from its owning section** — a fact placed in the wrong section is silently ignored, not flagged
+- Before writing any requirement, place it by content:
+- To move facts that are already misplaced, or to split a bullet carrying several kinds of fact, use the `resolve-section-ownership` skill
+
+| Content | Owning section | Rule file |
+|---|---|---|
+| Concepts (`:CamelCaseToken:`) | `***definitions***` | `definitions.md` |
+| HOW the software is built — tech stack, architecture, coding standards — and **everything about `:UnitTests:`** | `***implementation reqs***` | `impl-reqs.md` |
+| **Everything about `:ConformanceTests:`** — framework, run command, mocking and network policy | `***test reqs***` | `test-reqs.md` |
+| WHAT the software does — observable, language-agnostic behavior | `***functional specs***` | `func-specs.md` |
+| End-to-end workflow verification of one functional spec | nested `***acceptance tests***` | `func-specs.md` |
+
+## Comments
+- Lines beginning with `>` are ignored when rendering
+
+```plain
+> This is a comment in ***plain.
+```
+
+- Comments explain the specification to human authors — never use a comment to carry a requirement the renderer must implement
+
+## Liquid templates
+- `.plain` files are processed with [Liquid](https://shopify.github.io/liquid/) before parsing — the full Liquid syntax (variables, filters, conditionals, loops) is available in any section
+- Expansion is **textual** and happens before the specification is interpreted — unlike `import`, which includes another module semantically (see `import-modules.md`)
+
+```plain
+{% assign max_tags = 3 %}
+
+***functional specs***
+
+- A :Widget: can be created with up to {{ max_tags }} tags.
+{% if max_tags > 1 %}
+- A :Widget: can have its tags listed.
+{% endif %}
+```
+
+## Format
+
+```plain
+---
+description: Command-line task manager.
+import:
+  - airplain
+---
+
+***definitions***
+
+- :Task: is an activity tracked by the application.
+  - Name (required)
+
+- :TaskList: is the collection of all :Task: items. Initially empty.
+
+***implementation reqs***
+
+- :Implementation: keeps :TaskList: in memory.
+
+***test reqs***
+
+- :ConformanceTests: must not access the network.
+
+***functional specs***
+
+- A :Task: can be added to the :TaskList:.
+
+- The :TaskList: is displayed.
+```

package/forge/rules/required-concepts.md

@@ -9,14 +9,14 @@ When adding or editing `required_concepts` in a `.plain` file's frontmatter, alw
 ## What required_concepts does
 - `required_concepts` declares concepts that any module importing this file **must** define
 - It creates a contract: the import module references these concepts but does not define them — the importing module is responsible for providing definitions
-- This is used exclusively on import modules and templates
+- This is used exclusively on import modules
 
 ## When to use it
-- Use `required_concepts` when an import module or template (in `template/`) references concepts that vary per project or per importing module
+- Use `required_concepts` when an import module references concepts that vary per project or per importing module
 - The import module can reference these concepts in its definitions, implementation reqs, or test reqs — but their actual definitions come from whoever imports the file
 
 ## Importing module must satisfy the contract
-- Every concept listed in `required_concepts` must be defined in the importing module's own `***definitions***` section
+- Every concept listed in `required_concepts` must be defined somewhere visible to the importing module — in its own `***definitions***` section or in another module it imports
 - If the importing module does not define a required concept, the spec is invalid
 - Check `required_concepts` of all imported modules before finalizing a module
 
@@ -29,7 +29,7 @@ When adding or editing `required_concepts` in a `.plain` file's frontmatter, alw
 ```plain
 ---
 required_concepts: [":AppName:", ":AppConfig:"]
-description: Template that requires AppName and AppConfig to be defined by the importer
+description: Imported module that requires AppName and AppConfig to be defined by the importer
 ---
 
 ***definitions***
@@ -39,6 +39,6 @@ description: Template that requires AppName and AppConfig to be defined by the i
 - :MainFile: should load :AppConfig: on startup.
 ```
 
-In this example, `:AppName:` and `:AppConfig:` are referenced but not defined — the module that imports this template must define them.
+In this example, `:AppName:` and `:AppConfig:` are referenced but not defined — the module that imports this import module must define them.
 
 List concepts as a YAML array with each concept in `:ConceptName:` notation.

package/forge/rules/requires-modules.md

@@ -4,40 +4,56 @@ description: Rules for creating and using requires modules in .plain files
 
 # Rules for requires modules
 
-When creating or editing a `.plain` file that uses `requires`, always follow these rules:
+When creating or editing a `.plain` file that uses `requires`, or one that is referenced in another `.plain` file's `requires` directive, always follow these rules:
 
 ## What requires does
-- `requires` establishes a **build ordering** — the required module is built before the current one
-- The required module's generated code (`plain_modules/<required_module>/code`) is copied as the starting point
-- The required module's `***functional specs***` become visible as **previous functional specs** — this property **is transitive**
-- Only `exported_concepts` from the required module are available — not its full definitions — and this property **is not transitive**
+
+- `requires` attaches the current module to the project's **build chain**: the required module is built first, and its generated code is copied as the starting point for the current module
+- The copied code is the required module's **accumulated** output — it already contains the code of all of that module's own ancestors
+- The `***functional specs***` of the required module **and of all its ancestors** become visible as **previous functional specs** — this visibility **is transitive** down the whole chain
+- Of a required module's definitions, only the concepts listed in its `exported_concepts` are visible; the module's other definitions stay internal. Each exported concept arrives with its full definition text
+- Export visibility **is not transitive**: an ancestor's exports are visible only if that ancestor is itself listed in `requires`
+
+## Chain topology
+
+- All modules connected by `requires` form a single **tree** with a common root: code accumulates along each branch, and branches never reconverge
+- **Diamond joins are prohibited.** A module must not require two modules from divergent branches — there is no way to merge two divergent codebases into one starting point
+- When `requires` lists multiple modules, every entry must lie on **one root-to-tip ancestor path**: each listed module must be an ancestor of the deepest one
+- The **deepest entry is the attachment point** — it alone determines the build order and the starting code. The other entries add nothing to ordering; they exist **only** to make those ancestors' `exported_concepts` visible
+- Branching outward is fine: two modules may each require the same parent, creating independent branches (and therefore independent top modules)
 
 ## Tech stack must match (hard rule)
+
 - Because the required module's generated code is copied as the starting point and the renderer continues building on top of it with a single toolchain, two modules can only be linked with `requires` when they target the **same language, framework, and runtime**
 - A runtime / network dependency between systems is **not** a reason to use `requires`
 - Example of the mistake: a React frontend that talks to a Python/FastAPI backend over HTTP must **not** `requires: [backend]` — the stacks differ
-- Model that pair as two independent root modules (each with its own `config.yaml` and test scripts) and express the contract through a shared API schema in `resources/` or shared concepts in an `import`ed template — never through `requires`
+- Model that pair as two independent root modules (each with its own `config.yaml` and test scripts) and express the contract through a shared API schema in `resources/` or shared concepts in an `import`ed module — never through `requires`
 
-## Build order, not necessarily dependency
-- The current module does not need to extend or depend on the required module's code
-- The two modules may be completely independent
-- `requires` ensures the build order is correct for the project as a whole
+## Building upon but not necessarily extension
+
+- The current module does not need to functionally extend the required module — it may address a completely different concern
+- Even so, the two are never independent artifacts: the current module's output physically contains the required module's code, because both are stages of one accumulating codebase
+- Use `requires` to place a module at the right point in that lineage, whether or not it builds on the required module's functionality
 
 ## Conflict prevention
-- The current module's functional specs must not conflict with the required module's specs
-- The required module's specs are treated as previous requirements — the renderer sees them as context
-- Review the required module's functional specs before adding new ones
 
-## No access to full definitions
-- Only concepts listed in the required module's `exported_concepts` are available
-- Other concepts from the required module are internal and invisible
-- If you need shared definitions, use `import` for that — not `requires`
+- The current module's functional specs must not conflict with the specs of **any module in its ancestor chain** — all of them are previous functional specs
+- The renderer sees the whole chain's specs as prior requirements/context when rendering the current module
+- Review the ancestor chain's functional specs before adding new ones
+
+## Exports are the only visible definitions
+
+- Only concepts listed in a required module's `exported_concepts` are available, and only for modules explicitly listed in `requires`
+- Each exported concept is available with its full definition text
+- Other concepts from required modules are internal and invisible
+- To reference a concept exported by an ancestor deeper in the chain, list that ancestor in `requires` as well
+- If you need shared definitions across branches or stacks, use `import` for that — not `requires`
 
 ## File locations
+
 - Modules that use `requires` live at the **repository root** — they are functional modules with specs
 - `requires` paths point to other root-level modules (e.g., `auth`, `messaging`)
-- The default import directory is `template/` — the `template/` prefix is not needed in import paths (e.g., `airplain`)
-- Never `require` a template — templates are for `import` only
+- Never `require` an import module — import modules are for `import` only
 
 ## Format
 
@@ -47,11 +63,11 @@ requires:
   - auth
 import:
   - airplain
-description: Module built after auth, importing shared definitions
+description: Module built on top of auth, importing shared definitions
 ---
 ```
 
-A module can require multiple modules:
+A module can list multiple required modules **only when they lie on one ancestor path**. Here `messaging` itself requires `auth`, so `auth` is an ancestor of `messaging`; the module attaches after `messaging` and lists `auth` only to see its exports:
 
 ```plain
 ---

package/forge/rules/test-reqs.md

@@ -28,20 +28,24 @@ When writing or editing a `***test reqs***` section in a `.plain` file, always f
 
 ## Test type reference
 
-| Test type | Where to specify | Purpose |
-|-----------|-----------------|---------|
-| Unit tests | `***implementation reqs***` | Test individual functionalities in isolation |
-| Conformance tests | `***test reqs***` | Verify implementation conforms to the full spec |
-| Acceptance tests | `***acceptance tests***` under a functional spec | Verify a specific functional spec |
+| Test type | Where to specify | Generated | Purpose |
+|-----------|-----------------|-----------|---------|
+| Unit tests | `***implementation reqs***` | Automatically | Test individual functionalities in isolation |
+| Conformance tests | `***test reqs***` | Automatically | Verify each functionality's implementation against its functional spec |
+| Acceptance tests | `***acceptance tests***` under a functional spec | Manually | Verify implementation of a functional spec through a specific end-to-end scenario |
 
 ## No duplication
 - Do not duplicate guidance already present in the file or its imports
-- Check imported templates before adding a new test req
+- Check imported modules before adding a new test req
 
 ## Concept references
 - Reference predefined concepts like `:ConformanceTests:` where appropriate
 - All other referenced `:Concepts:` must be defined in `***definitions***`
 
+## Conciseness
+- State each req in the fewest plain words that stay exact — see `concise-specs.md`
+- Do not restate the default behavior of the test framework this section already names
+
 ## Format
 
 ```plain
@@ -50,6 +54,6 @@ When writing or editing a `***test reqs***` section in a `.plain` file, always f
 - :ConformanceTests: will be run using "pytest" command.
 - :ConformanceTests: must be implemented and executed - do not skip tests.
 - :ConformanceTests: should mock all external HTTP calls.
-- :ConformanceTests: are preapred via the preapre script [test_scripts/prepare_environment_python.sh](test_scripts/prepare_environment_python.sh).
+- :ConformanceTests: are prepared via the prepare script [test_scripts/prepare_environment_python.sh](test_scripts/prepare_environment_python.sh).
 - :ConformanceTests: are executed via the run script [test_scripts/run_conformance_tests_python.sh](test_scripts/run_conformance_tests_python.sh).
 ```

package/forge/skills/add-acceptance-test/SKILL.md

@@ -95,6 +95,7 @@ Acceptance tests extend conformance tests and are implemented according to the `
 - [ ] Nested under the correct functional spec
 - [ ] Indentation is correct (`***acceptance tests***` indented under the spec)
 - [ ] Each test describes a concrete, verifiable outcome
+- [ ] Trimmed per `concise-specs.md`: plain words, no obvious steps, no restatement of the parent spec
 - [ ] Tests are scoped to the parent functional spec only
 - [ ] Written in language-agnostic terms
 - [ ] No duplication with existing acceptance tests on the same spec

package/forge/skills/add-concept/SKILL.md

@@ -36,7 +36,7 @@ Always use the skill `load-plain-reference` to retrieve the ***plain syntax rule
 - CamelCase, starting with an uppercase letter
 - Valid characters: letters, digits, `+`, `-`, `.`, `_`
 - Must be globally unique across the spec and all its imports
-- Exported concepts from `requires` modules are **not transitive** — if a concept needs to be shared across multiple `requires` modules, define it in a common import module instead
+- Exported concepts from `requires` modules are **not transitive** — to reference an ancestor's export, list that ancestor in `requires`; if a concept is shared across branches, define it in a common import module instead
 
 ## Definition Format
 
@@ -68,4 +68,5 @@ Attributes and constraints are nested sub-bullets:
 - [ ] All referenced concepts (`:OtherConcept:`) are already defined above
 - [ ] No circular references between concepts
 - [ ] Description is clear, concise, and language-agnostic
+- [ ] Trimmed per `concise-specs.md`: one plain sentence, no restatement of the name, no rationale
 - [ ] Placed inside a `***definitions***` section

package/forge/skills/add-feature/SKILL.md

@@ -66,7 +66,7 @@ Ask one writable question per `AskUserQuestion` call, targeting exactly one of:
 - **A concept** — a new concept, or one single attribute of an existing one.
 - **A single edge case** — one invalid input, empty state, or boundary value.
 - **A single constraint** — one business rule, permission, ordering, or size limit.
-- **Implementation guidance** — only when the functionality needs technology / a library / a pattern not already in the file or its imports.
+- **Implementation guidance** — a policy that shapes how the functionality is built (retry, error handling, data format), or technology / a library / a pattern not already in the file or its imports.
 - **Verification** — only when the *Conformance gate* below is satisfied: one concrete outcome that proves this functionality works.
 
 Never bundle a second question into the prompt; never ask a question whose answer doesn't translate into a writable snippet on its own.
@@ -77,7 +77,7 @@ Route each answer to the right edit skill — never hand-author a `***plain` sec
 
 - **New concept** → `add-concept` (into `***definitions***`; define before any reference).
 - **New functional spec** → `add-functional-spec`. It runs `analyze-if-func-spec-too-complex` and `analyze-func-specs` for you — let it. **Never hand-author functional specs.** If it reports the spec is too complex, ask the user a follow-up question to split it (the next loop iteration) — do not break it down alone.
-- **New implementation req** → `add-implementation-requirement`. Only when the answer introduces technology / a library / a data format / an architectural pattern not already present.
+- **New implementation req** → `add-implementation-requirement`. When the answer states HOW the functionality is built — a retry or error-handling policy, a data format, a library, an architectural pattern — and it is not already in the file or its imports.
 - **New acceptance test** → `add-acceptance-test`, under the relevant functional spec. Only when the *Conformance gate* is satisfied and the answer describes a concrete verification.
 - **New test req** → `add-test-requirement`. Only when conformance testing is configured and the answer changes how conformance tests are run.
 

package/forge/skills/add-functional-spec/SKILL.md

@@ -19,7 +19,7 @@ Always use the skill `load-plain-reference` to retrieve the ***plain syntax rule
 
 1. **Identify the target `.plain` file.** If ambiguous, ask the user.
 2. **Read the entire file** to understand existing definitions, implementation reqs, and all current functional specs (including those in `requires` modules).
-3. **Draft the functional spec** following the rules below.
+3. **Draft the functional spec** following the rules below, then run the review pass in `concise-specs.md` over the draft — trim it to the shortest wording that keeps every fact before any other check.
 4. **Analyze complexity** — use the `analyze-if-func-spec-too-complex` skill to verify the drafted spec implies ≤ 200 LOC. If too complex, use the `break-down-func-spec` skill to split it, then repeat from step 3 for each resulting spec.
 5. **Check for conflicts** with every existing functional spec — this is critical. Run `analyze-func-specs` **once** with the new spec plus all existing specs (in the file and in any `requires` chain) as a single batch. The batched analyzer returns every conflicting pair in one call — do **not** invoke a pair-by-pair analyzer. For each conflicting pair it reports, run `resolve-spec-conflict` on that pair; re-run `analyze-func-specs` over the touched set after each resolution until the verdict is `COMPATIBLE`.
 6. **Append the spec** to the end of the `***functional specs***` section (specs are chronological; new ones go last).
@@ -80,5 +80,6 @@ If the functional spec needs verification, use the `add-acceptance-test` skill t
 - [ ] All external interfaces are explicit (endpoint paths, methods, CLI args, formats, etc.)
 - [ ] All referenced `:Concepts:` are defined in `***definitions***`
 - [ ] Sentences are short, clear, and unambiguous
+- [ ] Trimmed per `concise-specs.md`: nothing obvious, no rationale, no uncheckable adjectives or hedges, plain words throughout
 - [ ] No redundancy with existing specs
 - [ ] Placed in correct chronological position (usually at the end)

package/forge/skills/add-functional-specs/SKILL.md

@@ -28,7 +28,7 @@ This skill is `add-functional-spec` applied **one spec at a time, in order**, wi
 
 1. **Identify the target `.plain` file.** If ambiguous, ask the user.
 2. **Read the entire file** to understand existing definitions, implementation reqs, and all current functional specs (including those reachable via `import` / `requires`).
-3. **Draft all the specs you intend to add**, in the chronological order they should appear. Keep the drafts in a working list — nothing is inserted yet.
+3. **Draft all the specs you intend to add**, in the chronological order they should appear. Keep the drafts in a working list — nothing is inserted yet. Run the review pass in `concise-specs.md` over every draft before continuing; trim each to the shortest wording that keeps every fact.
 4. **For each drafted spec, in order:**
    1. **Analyze complexity.** Run `analyze-if-func-spec-too-complex` on the spec. If the verdict is `TOO COMPLEX`, run `break-down-func-spec`, replace the entry in the working list with the resulting smaller specs (preserving order), and restart this step on the first of the replacements.
    2. **Check for conflicts.** Run `analyze-func-specs` **once** with this single input set:
@@ -114,5 +114,6 @@ If any of the newly added functional specs need verification, use the `add-accep
 - [ ] All external interfaces explicit (endpoint paths, methods, CLI args, formats, etc.)
 - [ ] All referenced `:Concepts:` are defined in `***definitions***`
 - [ ] Sentences are short, clear, and unambiguous
+- [ ] Every spec trimmed per `concise-specs.md`: nothing obvious, no rationale, no uncheckable adjectives or hedges, plain words throughout
 - [ ] No redundancy with existing specs or within the batch
 - [ ] Specs placed in correct chronological positions

package/forge/skills/add-implementation-requirement/SKILL.md

@@ -66,7 +66,7 @@ Implementation reqs are bullet points in the `***implementation reqs***` section
 
 - :Implementation: should use pip for dependency management.
 
-- When writing CSV files, :Implementation: should use streaming writes to avoid holding large datasets in memory.
+- :ReportExporter: writes a :CsvFile: with streaming writes, never holding the full dataset in memory.
 
 ```
 
@@ -82,5 +82,6 @@ Reference defined `:Concepts:` where they add clarity. Implementation reqs in no
 - [ ] Describes HOW to build, not WHAT to build
 - [ ] All referenced `:Concepts:` are defined in `***definitions***`
 - [ ] Does not duplicate guidance already present in the file or its imports
+- [ ] Trimmed per `concise-specs.md`: plain words, no rationale, no standard behavior of a technology already named
 - [ ] Placed inside a `***implementation reqs***` section
 - [ ] No behavioral requirements that should be in `***functional specs***`

package/forge/skills/add-test-requirement/SKILL.md

@@ -69,5 +69,6 @@ Reference predefined concepts like `:ConformanceTests:` and any defined `:Concep
 - [ ] Describes conformance testing concerns, not unit tests or behavior
 - [ ] All referenced `:Concepts:` are defined (or are predefined like `:ConformanceTests:`)
 - [ ] Does not duplicate guidance already present in the file or its imports
+- [ ] Trimmed per `concise-specs.md`: plain words, no rationale, no default framework behavior
 - [ ] Placed inside a `***test reqs***` section
 - [ ] No behavioral requirements that should be in `***functional specs***`

package/forge/skills/break-down-func-spec/SKILL.md

@@ -201,5 +201,6 @@ If the original spec had acceptance tests, redistribute them to the most appropr
 - [ ] All `:Concepts:` referenced in replacement specs are defined
 - [ ] Any extracted technical component is defined as a concept, built by its own earlier spec, and only **referenced** (not re-described) by the original
 - [ ] Replacement specs are language-agnostic
+- [ ] Replacement specs trimmed per `concise-specs.md` — a split is not a licence to re-add prose
 - [ ] All external interfaces remain explicit
 - [ ] Acceptance tests (if any) have been redistributed or rewritten

package/forge/skills/check-forge-version/SKILL.md

@@ -0,0 +1,154 @@
+---
+name: check-forge-version
+description: >-
+  Reports whether the plain-forge installation on this machine is current. Enumerates every agent
+  directory plain-forge can install into — project scope and global scope, across all supported
+  agent layouts — reads the installed version from each `.plain-forge/manifest.json`, resolves the
+  latest published version from the npm registry, and emits a PASS / WARN / FAIL verdict naming
+  every install that is current, stale, or unmanaged. For a stale install it surfaces the exact
+  `npx plain-forge update` command and asks the user to run it. This concerns the plain-forge
+  tooling itself, so it is not tied to any ***plain project or authoring workflow. Use when someone
+  asks whether plain-forge is up to date, on the first use of a forge skill in a session, after a
+  forge skill or rule behaves unexpectedly, or when a rule referenced in conversation appears to be
+  missing. Do not use to perform the update, which stays the user's decision. Do not use to check a
+  project's host tooling, which is what `check-plain-env` covers.
+---
+
+# Check Forge Version
+
+This skill answers one question: **is the plain-forge installed on this machine the latest published
+version?** It reads the installed version from every install's manifest, compares each against the
+`latest` dist-tag on npm, and — when an install is behind — asks the user to run
+`npx plain-forge update`.
+
+The subject is **plain-forge itself**, not any project it is used on. This skill reads no `.plain`
+files, needs no ***plain project in the working directory, and is equally valid in an empty
+directory. Do not invoke `load-plain-reference` for it; no authoring rules apply.
+
+## When to run
+
+- **On the first use of any forge skill in a session** — the cheapest moment to discover that the
+  skills and rules about to be followed are from a superseded release.
+- **On demand** — whenever the user asks whether plain-forge is up to date, which version is
+  installed, or where it is installed.
+- **After a forge skill or rule behaves unexpectedly** — a skill that contradicts the documented
+  behavior, or a rule file that is missing entirely, is most often a stale install rather than a bug.
+- **When a skill or rule named in conversation does not exist on disk** — a newer release probably
+  added it.
+- **After a plain-forge release is announced**, to confirm the update actually landed in every scope.
+
+## What this skill does NOT do
+
+- It does **not** run `npx plain-forge update`, or install, or uninstall anything. It reports and
+  asks; acting is the user's decision.
+- It does **not** modify any file — not a manifest, not a skill, not a rule. It is read-only apart
+  from the network read against the npm registry.
+- It does **not** check project host tooling, runtimes, services, or credentials. That is
+  `check-plain-env`.
+- It does **not** validate `.plain` specs. That is `plain-healthcheck`.
+- It does **not** resolve which agent the user *should* install into. It reports what is present.
+
+## Workflow
+
+### Step 1 — Run the check
+
+Run the bundled script with the `terminal` tool, passing its path relative to this `SKILL.md`:
+
+```
+node scripts/check-forge-version.mjs
+```
+
+**Run it from the project root** whose project-scope install should be checked, giving the full path
+to the script — for a Claude layout, `node .claude/skills/check-forge-version/scripts/check-forge-version.mjs`.
+The script always reports the install it lives in and the global installs regardless of where it is
+invoked, but it can only find a *project-scope* install in the current working directory. When the
+report is missing an install that is known to exist, re-run it from that project's root before
+concluding anything.
+
+Add `--json` for a machine-readable report, or `--offline` to list the installs without querying npm.
+
+The script is the single source of truth for this check. It mirrors `bin/cli.mjs` for both the
+install-path model (including the two global paths that break the usual pattern — ForgeCode's
+`~/forge` and OpenCode's `~/.config/opencode`) and the version comparison. Do not re-derive either by
+hand, and do not substitute an ad-hoc `npm view` plus a guess at where the install lives.
+
+### Step 2 — Read the verdict
+
+The verdict is the **first line of stdout**, and it is also the exit code:
+
+| Exit | Verdict | Meaning |
+|---|---|---|
+| 0 | `PASS` | Every install found is at the latest version. |
+| 1 | `FAIL` | At least one install is behind the latest version. |
+| 2 | `WARN` | Installs found, but at least one version is indeterminate (no manifest, or a prerelease). |
+| 3 | `ERROR` | The latest version could not be resolved from npm. |
+| 4 | `NONE` | No install found in any candidate directory. |
+
+Per-install statuses are `CURRENT`, `STALE`, `UNMANAGED` (a pre-manifest install — `update` adopts
+it and writes a manifest going forward), or `INDETERMINATE`.
+
+Each install is labelled with its scope: `self` is the install this skill is running from, `project`
+is one found in the current working directory, and `global` is one under the home directory.
+
+### Step 3 — Report and prompt
+
+Relay the verdict to the user, then act on it:
+
+- **`PASS`** — state the installed version and that it is current. Stop. Do not suggest an update.
+- **`FAIL`** or **`WARN`** — do not report this as a passing aside. Lead with the recommendation,
+  name each affected install by agent, scope, and path, give the installed version and the latest
+  version, and **ask the user directly to update before continuing**:
+
+  ```
+  npx plain-forge update
+  ```
+
+  State plainly that **continuing on an outdated plain-forge is not recommended** — its skills and
+  rules have been superseded, specs authored against them may not match what the current `codeplain`
+  renderer expects, and fixes released since the installed version are not in effect. On `WARN`,
+  where the version could not be confirmed, say the install should be treated as outdated until
+  proven otherwise.
+
+  Add that a single `update` run covers every install across both scopes, prunes files that no longer
+  ship, and never touches the user's own or third-party skills — so the fix is one command and
+  carries no risk to their content.
+
+  Then **stop and wait for the user** — do not run the update. If the user chooses to continue
+  without updating, proceed with the task, but say once that the stale rules are a likely source of
+  any surprising behaviour that follows.
+- **`NONE`** — report that plain-forge is not installed here and surface `npx plain-forge install`,
+  noting that the script's output lists every directory that was checked.
+- **`ERROR`** — report that the installed versions could not be compared against anything, give the
+  reason from the script, and offer the two options: re-run when the network is reachable, or check
+  https://www.npmjs.com/package/plain-forge directly. Never guess whether the install is current.
+
+When the user agrees to update, they run the command themselves. After it completes, re-run Step 1 to
+confirm the result rather than assuming it worked.
+
+## Error Handling
+
+- **Registry unreachable** — the script already falls back from the registry endpoint to
+  `npm view plain-forge version`, which succeeds on hosts pointed at an internal mirror. If both
+  fail it exits 3; treat the version as unknown and surface the reason instead of assuming staleness.
+- **`node` unavailable** — plain-forge requires Node ≥ 18, so this is itself the finding. Report that
+  Node is missing and that no plain-forge command, including `update`, can run without it.
+- **Malformed or hand-edited manifest** — the script treats an unparseable manifest as absent and
+  falls back to detecting the install by its skill footprint, reporting it as `UNMANAGED`. Recommend
+  `npx plain-forge update`, which rewrites a correct manifest.
+- **An install ahead of the registry** — a local development build reports `CURRENT`, not stale. Do
+  not prompt for an update in that case.
+- **Prerelease installed** — a version such as `1.0.21-rc.1` is not dotted-numeric and reports
+  `INDETERMINATE`. Prereleases ship under npm's `next` tag, so a comparison against `latest` is not
+  meaningful; say so rather than prompting for an update that would move the user off the prerelease.
+
+## Validation Checklist
+
+- [ ] `scripts/check-forge-version.mjs` was actually executed; no verdict was inferred from memory or
+      from a bare `npm view`.
+- [ ] The verdict reported to the user matches the script's first line and exit code.
+- [ ] Every install the script listed was relayed with its agent, scope, and path.
+- [ ] `npx plain-forge update` was **offered**, never executed by this skill.
+- [ ] Nothing on disk was modified.
+- [ ] No `.plain` file was read and `load-plain-reference` was not invoked — this skill is about the
+      tooling, not about any project.
+- [ ] On `ERROR` or `NONE`, no claim was made about whether the install is current.