plain-forge 1.0.20 → 1.0.21-next.55f13d7

package/forge/skills/check-forge-version/scripts/check-forge-version.mjs

@@ -0,0 +1,368 @@
+#!/usr/bin/env node
+//
+// Report whether the plain-forge installed on this machine is the latest
+// published version.
+//
+//   node check-forge-version.mjs            # human-readable report
+//   node check-forge-version.mjs --json     # machine-readable report
+//   node check-forge-version.mjs --offline  # skip the registry, list installs only
+//
+// Exit codes (the verdict is also the first line of stdout):
+//   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
+//   3  ERROR  — the latest version could not be resolved from npm
+//   4  NONE   — no plain-forge install found in any candidate directory
+//
+// Zero dependencies, Node >= 18 (global fetch). The install-path model and the
+// version comparison mirror bin/cli.mjs; keep them in sync with that file.
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { execFileSync } from "node:child_process";
+
+const PKG = "plain-forge";
+const REGISTRY = `https://registry.npmjs.org/${PKG}/latest`;
+const MANIFEST_REL = path.join(".plain-forge", "manifest.json");
+
+// Flagship skills every install ships. All four present means plain-forge is
+// installed even when no manifest is (a legacy, pre-manifest install).
+const SIGNATURE_SKILLS = [
+  "forge-plain",
+  "add-feature",
+  "debug-specs",
+  "load-plain-reference",
+];
+
+// The install this script is executing from, found by walking up its own path
+// rather than trusting cwd:
+//   <baseDir>/skills/check-forge-version/scripts/check-forge-version.mjs
+// Without this, running the script from its own directory (the natural reading
+// of "node scripts/check-forge-version.mjs") would scan the skill folder as if
+// it were a project root and report NONE while sitting inside a live install.
+// Returns null when running from the source repo, where forge/ is not an
+// install.
+function selfInstall() {
+  const here = path.dirname(fileURLToPath(import.meta.url));
+  if (path.basename(path.resolve(here, "..", "..")) !== "skills") return null;
+  const dir = path.resolve(here, "..", "..", "..");
+  const byDir = {
+    ".claude": "claude",
+    ".agents": "codex/copilot/universal",
+    ".forge": "forgecode",
+    forge: "forgecode",
+    ".opencode": "opencode",
+    opencode: "opencode",
+  };
+  const agent = byDir[path.basename(dir)];
+  if (!agent) return null;
+  // The source repo's forge/ dir also holds skills/, and ForgeCode's global
+  // install is ~/forge — same basename. Only the source tree sits next to the
+  // package's own package.json, so that is what separates them. Without this
+  // guard, running from a checkout reports the repo as an unmanaged install.
+  try {
+    const pkg = JSON.parse(
+      fs.readFileSync(path.join(dir, "..", "package.json"), "utf8"),
+    );
+    if (pkg?.name === PKG) return null;
+  } catch {
+    /* no sibling package.json -> a real install, not the source tree */
+  }
+  return { agent, scope: "self", dir };
+}
+
+// Every directory plain-forge can install into, mirroring resolveBaseDir in
+// bin/cli.mjs — including the two global paths that break the usual pattern
+// (ForgeCode uses ~/forge, OpenCode uses ~/.config/opencode). The install this
+// script lives in comes first so it survives realpath deduplication.
+function candidateInstalls() {
+  const cwd = process.cwd();
+  const home = os.homedir();
+  const self = selfInstall();
+  return [
+    ...(self ? [self] : []),
+    { agent: "claude", scope: "project", dir: path.join(cwd, ".claude") },
+    { agent: "codex/copilot/universal", scope: "project", dir: path.join(cwd, ".agents") },
+    { agent: "forgecode", scope: "project", dir: path.join(cwd, ".forge") },
+    { agent: "opencode", scope: "project", dir: path.join(cwd, ".opencode") },
+    { agent: "claude", scope: "global", dir: path.join(home, ".claude") },
+    { agent: "codex/copilot/universal", scope: "global", dir: path.join(home, ".agents") },
+    { agent: "forgecode", scope: "global", dir: path.join(home, "forge") },
+    { agent: "opencode", scope: "global", dir: path.join(home, ".config", "opencode") },
+  ];
+}
+
+function readManifest(baseDir) {
+  try {
+    const data = JSON.parse(
+      fs.readFileSync(path.join(baseDir, MANIFEST_REL), "utf8"),
+    );
+    if (data && Array.isArray(data.files)) return data;
+  } catch {
+    /* missing or malformed manifest -> treat as absent */
+  }
+  return null;
+}
+
+function hasForgeSignature(baseDir) {
+  return SIGNATURE_SKILLS.every((skill) =>
+    fs.existsSync(path.join(baseDir, "skills", skill)),
+  );
+}
+
+// Same semantics as compareVersions in bin/cli.mjs: 1 if a > b, -1 if a < b,
+// 0 if equal, null when either side is not purely dotted-numeric (a
+// prerelease such as "1.0.21-rc.1", or "unknown").
+function compareVersions(a, b) {
+  const parse = (v) => String(v).split(".").map(Number);
+  const pa = parse(a);
+  const pb = parse(b);
+  if (pa.some(Number.isNaN) || pb.some(Number.isNaN)) return null;
+  const len = Math.max(pa.length, pb.length);
+  for (let i = 0; i < len; i++) {
+    const x = pa[i] ?? 0;
+    const y = pb[i] ?? 0;
+    if (x > y) return 1;
+    if (x < y) return -1;
+  }
+  return 0;
+}
+
+// Resolve the `latest` dist-tag. Prereleases are published under `next`, so
+// `latest` is the right tag to compare a normal install against.
+async function resolveLatest() {
+  try {
+    const res = await fetch(REGISTRY, {
+      headers: { accept: "application/json" },
+      signal: AbortSignal.timeout(10000),
+    });
+    if (!res.ok) throw new Error(`registry returned HTTP ${res.status}`);
+    const version = (await res.json())?.version;
+    if (!version) throw new Error("registry response had no version field");
+    return { version, source: "registry" };
+  } catch (registryErr) {
+    // Offline, proxied, or air-gapped hosts often still have a working npm
+    // configured against an internal mirror.
+    try {
+      const out = execFileSync("npm", ["view", PKG, "version"], {
+        encoding: "utf8",
+        timeout: 20000,
+        stdio: ["ignore", "pipe", "ignore"],
+      });
+      const version = out.trim();
+      if (!version) throw new Error("npm view printed nothing");
+      return { version, source: "npm view" };
+    } catch (npmErr) {
+      return {
+        version: null,
+        source: null,
+        error: `${registryErr.message}; npm fallback: ${npmErr.message}`,
+      };
+    }
+  }
+}
+
+function findInstalls() {
+  const installs = [];
+  const seen = new Set();
+  for (const cand of candidateInstalls()) {
+    if (!fs.existsSync(cand.dir)) continue;
+    const key = fs.realpathSync(cand.dir);
+    if (seen.has(key)) continue; // .agents is shared by three agent labels
+    const manifest = readManifest(cand.dir);
+    if (manifest) {
+      seen.add(key);
+      installs.push({
+        ...cand,
+        // The manifest records which agent layout produced the install; prefer
+        // it over the label the candidate list guessed.
+        agent: manifest.agent ?? cand.agent,
+        installed: manifest.version ?? null,
+        managed: true,
+        files: manifest.files.length,
+      });
+    } else if (hasForgeSignature(cand.dir)) {
+      seen.add(key);
+      installs.push({
+        ...cand,
+        installed: null,
+        managed: false,
+        files: null,
+      });
+    }
+  }
+  return installs;
+}
+
+function classify(install, latest) {
+  if (!install.managed) return "UNMANAGED";
+  if (!install.installed) return "INDETERMINATE";
+  const cmp = compareVersions(latest, install.installed);
+  if (cmp === null) return "INDETERMINATE";
+  if (cmp > 0) return "STALE";
+  return "CURRENT"; // equal, or ahead of the registry (a local dev build)
+}
+
+// Greedy wrap so the report reads as prose in a terminal instead of breaking
+// mid-sentence at hardcoded string boundaries.
+function wrap(text, width = 84) {
+  const out = [];
+  let line = "";
+  for (const word of text.split(/\s+/)) {
+    if (line && line.length + 1 + word.length > width) {
+      out.push(line);
+      line = word;
+    } else {
+      line = line ? `${line} ${word}` : word;
+    }
+  }
+  if (line) out.push(line);
+  return out;
+}
+
+function report(installs, latest, statuses) {
+  const lines = [];
+  const stale = statuses.filter((s) => s.status === "STALE");
+  const unclear = statuses.filter(
+    (s) => s.status === "UNMANAGED" || s.status === "INDETERMINATE",
+  );
+
+  let verdict;
+  if (stale.length > 0) verdict = "FAIL";
+  else if (unclear.length > 0) verdict = "WARN";
+  else verdict = "PASS";
+
+  lines.push(
+    `${verdict} — latest ${PKG} on npm is v${latest.version} (via ${latest.source})`,
+  );
+  lines.push("");
+  lines.push(`Found ${installs.length} install(s):`);
+  for (const s of statuses) {
+    const where = `${s.install.agent} (${s.install.scope})`;
+    const version = s.install.installed ? `v${s.install.installed}` : "version unknown";
+    lines.push(`  [${s.status}] ${where} — ${version}`);
+    lines.push(`      ${s.install.dir}`);
+    if (s.status === "UNMANAGED") {
+      lines.push(
+        "      no .plain-forge/manifest.json — a pre-manifest install; update adopts it",
+      );
+    }
+  }
+  lines.push("");
+  if (verdict === "PASS") {
+    lines.push("Every install is at the latest published version. Nothing to do.");
+    return { text: lines.join("\n"), verdict };
+  }
+
+  lines.push("ACTION REQUIRED — please update plain-forge before continuing.");
+  lines.push("");
+  if (stale.length > 0) {
+    const n = stale.length;
+    lines.push(
+      ...wrap(
+        `${n} ${n === 1 ? "install is" : "installs are"} behind v${latest.version}. ` +
+          "Continuing on an outdated plain-forge is not recommended: its skills and rules have " +
+          "been superseded, so specs authored against them may not match what the current " +
+          "codeplain renderer expects, and fixes released since this version are not in effect.",
+      ),
+    );
+  }
+  if (unclear.length > 0) {
+    const n = unclear.length;
+    if (stale.length > 0) lines.push("");
+    lines.push(
+      ...wrap(
+        `${n} ${n === 1 ? "install could" : "installs could"} not be confirmed as current. ` +
+          "Treat it as outdated until proven otherwise — updating is the cheapest way to " +
+          "remove the doubt.",
+      ),
+    );
+  }
+  lines.push("");
+  lines.push("    npx plain-forge update");
+  lines.push("");
+  lines.push(
+    ...wrap(
+      "One run covers everything: update auto-detects every install across both scopes, prunes " +
+        "files that no longer ship, and never touches your own or third-party skills. Re-run " +
+        "this check afterwards to confirm.",
+    ),
+  );
+  return { text: lines.join("\n"), verdict };
+}
+
+async function main() {
+  const argv = process.argv.slice(2);
+  const asJson = argv.includes("--json");
+  const offline = argv.includes("--offline");
+
+  const installs = findInstalls();
+
+  if (installs.length === 0) {
+    const msg =
+      `NONE — no ${PKG} install found.\n\n` +
+      "Checked these directories (none held a .plain-forge/manifest.json or a\n" +
+      "recognizable forge skill tree):\n" +
+      candidateInstalls().map((c) => `  ${c.dir}`).join("\n") +
+      `\n\nInstall it with:\n\n    npx ${PKG} install\n`;
+    console.log(asJson ? JSON.stringify({ verdict: "NONE", installs: [] }, null, 2) : msg);
+    process.exit(4);
+  }
+
+  if (offline) {
+    const out = installs
+      .map(
+        (i) =>
+          `  ${i.agent} (${i.scope}) — ${i.installed ? `v${i.installed}` : "version unknown"}\n      ${i.dir}`,
+      )
+      .join("\n");
+    console.log(
+      asJson
+        ? JSON.stringify({ verdict: "OFFLINE", installs }, null, 2)
+        : `OFFLINE — registry not queried.\n\nFound ${installs.length} install(s):\n${out}\n`,
+    );
+    process.exit(0);
+  }
+
+  const latest = await resolveLatest();
+  if (!latest.version) {
+    const out = installs
+      .map(
+        (i) =>
+          `  ${i.agent} (${i.scope}) — ${i.installed ? `v${i.installed}` : "version unknown"}`,
+      )
+      .join("\n");
+    const msg =
+      `ERROR — could not resolve the latest ${PKG} version from npm.\n\n` +
+      `Reason: ${latest.error}\n\n` +
+      `Installed versions found (not compared against anything):\n${out}\n\n` +
+      "Re-run when the network is available, or check https://www.npmjs.com/package/" +
+      `${PKG} manually.\n`;
+    console.error(
+      asJson
+        ? JSON.stringify({ verdict: "ERROR", error: latest.error, installs }, null, 2)
+        : msg,
+    );
+    process.exit(3);
+  }
+
+  const statuses = installs.map((install) => ({
+    install,
+    status: classify(install, latest.version),
+  }));
+
+  const { text, verdict } = report(installs, latest, statuses);
+  console.log(
+    asJson
+      ? JSON.stringify({ verdict, latest: latest.version, source: latest.source, installs: statuses }, null, 2)
+      : text,
+  );
+  process.exit(verdict === "FAIL" ? 1 : verdict === "WARN" ? 2 : 0);
+}
+
+main().catch((err) => {
+  console.error(`ERROR — check-forge-version failed unexpectedly: ${err.message}`);
+  process.exit(3);
+});

package/forge/skills/create-import-module/SKILL.md

@@ -89,9 +89,9 @@ import:
 | Pulls in definitions | Yes | No (only `exported_concepts`) |
 | Pulls in implementation reqs | Yes | No |
 | Pulls in test reqs | Yes | No |
-| Pulls in functional specs | No | Yes (as previous requirements) |
-| Copies generated code | No | Yes |
-| Typical use | Templates, shared definitions | Build dependency chain |
+| Pulls in functional specs | No | Yes (as previous requirements, transitively) |
+| Copies generated code | No | Yes (accumulated ancestor chain) |
+| Typical use | Templates, shared definitions | Attaching a module to the build chain |
 
 ## Validation Checklist
 

package/forge/skills/create-requires-module/SKILL.md

@@ -13,28 +13,29 @@ Always use the skill `load-plain-reference` to retrieve the ***plain syntax rule
 
 ## What Requires Does
 
-`requires` establishes a build ordering between modules. The required module is built **before** the current one. This does not necessarily mean the current module extends or depends on the required module's code — it may be completely independent. The `requires` relationship simply ensures the build order is correct.
+`requires` attaches the current module to the project's build chain. The required module is built **before** the current one, and its generated code — the accumulated output of that module and all its ancestors — is copied as the starting point. The current module does not need to functionally extend the required module, but their outputs are never independent: the current module's code physically contains the required module's.
 
 When this module is rendered:
 - 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**.
-- Only `exported_concepts` from the required module are available (not its full definitions).
+- The `***functional specs***` of the required module **and all its ancestors** become visible as **previous functional specs**.
+- Of the required module's definitions, only the concepts in its `exported_concepts` are visible, each with its full definition text. Export visibility is **not** transitive — to see an ancestor's exports, list that ancestor in `requires` too.
+
+All modules connected by `requires` form a single tree with a common root. **Diamond joins are prohibited**: multiple `requires` entries must lie on one root-to-tip ancestor path. The deepest entry is the attachment point; the other entries exist only to make those ancestors' exports visible.
 
 Use `requires` for:
-- Ensuring a module is built after another in the build chain
 - Building on top of an existing module's functionality
-- Extending a base module with additional features
+- Attaching a module at the right point in the build chain, even when it addresses a different concern
 
 If you only need shared definitions and reqs (no functional specs, no generated code), use `import` instead — see the `create-import-module` skill.
 
 ## Workflow
 
-1. **Identify the dependency.** Determine which module this new module builds on. That module must already exist and be renderable.
+1. **Identify the attachment point.** Determine which existing module this new module attaches after in the build chain. That module must already exist and be renderable. If listing additional modules, verify each is an ancestor of the attachment point — no diamond joins.
 2. **Create the `.plain` file at the repository root** with YAML frontmatter containing the `requires` field. Modules with functional specs live at the root, not in `template/`.
-3. **Review the required module's functional specs** — they will be treated as previous requirements. Your new functional specs must not conflict with them.
-4. **Review the required module's `exported_concepts`** — only those concepts are available to reference from the required module.
+3. **Review the functional specs of the whole ancestor chain** — they will be treated as previous requirements. Your new functional specs must not conflict with any of them.
+4. **Review each listed module's `exported_concepts`** — only those concepts are available to reference; an ancestor's exports require listing that ancestor.
 5. **Add module-specific content** — definitions, implementation reqs, test reqs, and functional specs unique to this module.
-6. **Check for conflicts** between your new functional specs and the required module's specs.
+6. **Check for conflicts** between your new functional specs and any spec in the ancestor chain.
 
 ## Format
 
@@ -60,6 +61,8 @@ description: Extended module that builds on base_module
 
 A module can use both `requires` and `import` together. `requires` points to other root-level modules; `import` resolves from the default `template/` directory (no prefix needed).
 
+Multiple `requires` entries are legal only when they lie on one ancestor path (e.g., `requires: [auth, messaging]` where `messaging` itself requires `auth`). The deepest entry (`messaging`) is the attachment point; `auth` is listed only to make its exports visible.
+
 ## Exported Concepts
 
 The required module controls what concepts are visible via `exported_concepts`:
@@ -71,17 +74,17 @@ exported_concepts: [":StorageClient:", ":BackupResult:"]
 ---
 ```
 
-Only `:StorageClient:` and `:BackupResult:` would be available to modules that `require` this one. All other concepts from the required module are internal.
+Only `:StorageClient:` and `:BackupResult:` would be available to modules that `require` this one, each with its full definition text. All other concepts from the required module are internal.
 
 ## Chronological Ordering with Requires
 
-Functional specs from `requires` modules are considered **previous functional specs**. This means:
+Functional specs from the whole `requires` ancestor chain are considered **previous functional specs**. This means:
 - They are already rendered and their code exists.
 - Your new specs are rendered after them, with full awareness of what they defined.
-- Your new specs must not conflict with the required module's specs.
-- The renderer sees the required module's functional specs as context when rendering yours.
+- Your new specs must not conflict with any spec in the ancestor chain.
+- The renderer sees the chain's functional specs as context when rendering yours.
 
-The current module may or may not be functionally related to the required module. In some cases `requires` simply enforces build order — the two modules may be independent pieces of the same project that need to be built in sequence.
+The current module may or may not be functionally related to the required module — `requires` places it at the right point in the accumulating build chain either way.
 
 ## Import vs Requires
 
@@ -90,16 +93,18 @@ The current module may or may not be functionally related to the required module
 | Pulls in definitions | Yes | No (only `exported_concepts`) |
 | Pulls in implementation reqs | Yes | No |
 | Pulls in test reqs | Yes | No |
-| Pulls in functional specs | No | Yes (as previous requirements) |
-| Copies generated code | No | Yes |
-| Typical use | Templates, shared definitions | Build dependency chain |
+| Pulls in functional specs | No | Yes (as previous requirements, transitively) |
+| Copies generated code | No | Yes (accumulated ancestor chain) |
+| Typical use | Templates, shared definitions | Attaching a module to the build chain |
 
 ## Validation Checklist
 
 - [ ] Module file is at the repository root (not in `template/`)
 - [ ] Required module exists and is renderable
-- [ ] Required module's `exported_concepts` provide the concepts you need
-- [ ] New functional specs do not conflict with the required module's specs
+- [ ] All `requires` entries lie on one ancestor path — no diamond joins
+- [ ] The deepest `requires` entry is the intended attachment point
+- [ ] Every listed module's `exported_concepts` provide the concepts you need
+- [ ] New functional specs do not conflict with any spec in the ancestor chain
 - [ ] Module has at least one functional spec and one implementation req
 - [ ] Both `requires` and `import` are used correctly (not mixed up)
 - [ ] YAML frontmatter is correctly formatted between `---` markers

package/forge/skills/forge-plain/SKILL.md

@@ -82,7 +82,7 @@ When entering a phase, read its reference file and walk its topics **in order**
 | Phase | Reference | Finished when |
 |---|---|---|
 | 0 — What is the intent? | `references/phase-0-intent.md` | a concise intent brief covering the problem, primary user and outcome, and initial boundary is explicitly confirmed; nothing is written to disk |
-| 1 — What are we building? | `references/phase-1-product.md` | the new `***definitions***` and `***functional specs***` are on disk and approved |
+| 1 — What are we building? | `references/phase-1-product.md` | the new `***definitions***` and `***functional specs***`, plus any technology-free `***implementation reqs***`, are on disk and approved |
 | 2 — What tech should it use? | `references/phase-2-tech.md` | the new `***implementation reqs***` are on disk and approved |
 | 3 — How is testing done? | `references/phase-3-testing.md` | the `***test reqs***` (and `***acceptance tests***` if conformance is on) are on disk, the `test_scripts/` and `config.yaml`(s) exist, and `check-plain-env` passed or each gap was acknowledged |
 | 4 — Validate and hand off | `references/phase-4-validate-handoff.md` | the agent ran `codeplain <module>.plain --dry-run` successfully against the render target, and the user has the render command plus every side-channel command |

package/forge/skills/forge-plain/references/checklist.md

@@ -37,7 +37,8 @@ A box is met only when its source confirms it. Return `APPROVED` only when every
 - [ ] **[disk]** `.plain` module structure created with YAML frontmatter; template (if any) has no `***functional specs***`.
 - [ ] **[both]** Every concept authored in `***definitions***` via `add-concept`, defined before use.
 - [ ] **[both]** Every feature authored as functional specs via `add-functional-spec(s)`, each ≤200 LOC, in chronological build order.
-- [ ] **[disk]** No `***implementation reqs***`, `***test reqs***`, or `***acceptance tests***` written in this phase.
+- [ ] **[disk]** No `***test reqs***` or `***acceptance tests***` written in this phase.
+- [ ] **[disk]** Every `***implementation reqs***` bullet written this phase is technology-free policy — none names a language, framework, library, storage engine, or deployment target.
 - [ ] **[record]** Summarized the full feature list and module/concept layout; got explicit overall confirmation.
 
 ## Phase 2 — What tech should it use?

package/forge/skills/forge-plain/references/phase-1-product.md

@@ -11,8 +11,9 @@ The moment the user answers, write the resulting snippet to disk using the right
 - **Module structure** — create or update the `.plain` file(s) (single module, template + modules, or chained modules). Set up YAML frontmatter (`import`, `requires`, `description`) and the proposed module name. If a template is used, create it in `template/` **without** a `***functional specs***` section. Use the `create-import-module` skill where applicable.
 - **`***definitions***`** — add or refine concepts (entities, attributes, relationships). Define every concept before it is referenced. Use the `add-concept` skill.
 - **`***functional specs***`** — translate each answer into a single chronological, incremental spec (≤200 lines of code change, language-agnostic, no conflicts). Use `add-functional-spec` for one new spec; use `add-functional-specs` only when a single answer naturally decomposes into a tight cluster of specs flowing from the same answer (e.g. list / create / delete CRUD on one entity). **Never hand-author the `***functional specs***` section directly.**
+- **`***implementation reqs***`** — only a requirement that can be stated without naming a technology: an error-handling or retry policy, an idempotency or ordering guarantee, a data-format or precision rule. Use the `add-implementation-requirement` skill, on the module whose behavior it constrains. The moment stating it takes a language, framework, library, storage engine, or deployment target, it is a Phase 2 answer — note it and steer back.
 
-Do **not** add `***implementation reqs***`, `***test reqs***`, or `***acceptance tests***` in this phase — they belong to later phases.
+Do **not** add `***test reqs***` or `***acceptance tests***` in this phase — they belong to later phases.
 
 ## Topics (in order)
 
@@ -25,7 +26,7 @@ Do **not** add `***implementation reqs***`, `***test reqs***`, or `***acceptance
 4. **Core entities** — the main "things" in the system (Users, Tasks, Orders, Messages, …), their attributes, and relationships. Author one concept per entity in `***definitions***`. Review each concept snippet.
 5. **Key features** — every distinct thing the app should do. For each feature capture the trigger, the expected outcome, and edge cases / validation rules. Author one or more functional specs per feature, in chronological build order, each ≤200 LOC. Break large features into smaller specs together with the user. Review each new functional spec (or tight group of related specs).
 6. **User flows** — walk through the app from the user's perspective: what happens first, what happens next, and at each decision point. Author the ordering and any missing intermediate functional specs. Review the affected sequence of specs.
-7. **Constraints and rules** — business rules, validation, permissions, error-handling behavior. Fold these into the relevant functional specs, and add concepts where they are first-class entities (e.g. roles). Review the updated specs.
+7. **Constraints and rules** — business rules, validation, permissions, error-handling behavior. Fold the observable part into the relevant functional specs, and add concepts where they are first-class entities (e.g. roles); route the part that shapes how the behavior is built — retries, backoff, error taxonomy — to `***implementation reqs***`. Review the updated specs.
 8. **User interface (optional)** — skip entirely if the project has no UI. Otherwise ask, one question per iteration:
    - How does the UI look and feel?
    - Where are the key UI elements located?

package/forge/skills/forge-plain/references/phase-2-tech.md

@@ -1,6 +1,6 @@
 # Phase 2 — What technologies should it use?
 
-Gather the technical stack **and** the project's structure/architecture. This phase affects only `***implementation reqs***` — testing concerns come later. Run the core loop (ask → author → review) from `SKILL.md` for each topic below, in order. When the user has no preference, propose a sensible default that fits earlier answers and ask them to confirm.
+Gather the technical stack **and** the project's structure/architecture. This phase affects only `***implementation reqs***` — testing concerns come later. Phase 1 may already have left technology-free policy reqs there (retries, error handling, data formats); read them before topic 1, and revisit one only where the chosen stack contradicts it or supplies it natively. Run the core loop (ask → author → review) from `SKILL.md` for each topic below, in order. When the user has no preference, propose a sensible default that fits earlier answers and ask them to confirm.
 
 ## Author target for this phase
 

package/forge/skills/load-plain-reference/SKILL.md

@@ -12,6 +12,18 @@ description: >-
 Load only the rules and references required for the current task. Files under `../../rules/` are
 the source of truth for `.plain` syntax and authoring constraints. Do not restate or override them.
 
+**First, confirm the rules about to be loaded are current.** On the first invocation of this skill in
+a session, invoke `check-forge-version` before loading any rule file. A stale plain-forge ships stale
+rules, so every routing decision below inherits its verdict.
+
+If that skill reports a stale or unconfirmed install, tell the user clearly that **authoring on an
+outdated plain-forge is not recommended** and ask them to run `npx plain-forge update` before
+continuing — the rules routed to below may not match what the current `codeplain` renderer expects.
+Give them the choice rather than blocking: if they decline, continue with the rules on disk and treat
+the stale install as the first suspect for anything that later behaves unexpectedly.
+
+Skip the check on later invocations in the same session, and skip it when the network is unavailable.
+
 ## 1. Account for rules already loaded
 
 - In Claude Code, applicable `.claude/rules/*.md` files are loaded natively. Do not read those rule
@@ -27,6 +39,8 @@ All paths are relative to this `SKILL.md`.
 
 | Task or content | Rule files |
 |---|---|
+| New module, file skeleton, section placement, or comments | `../../rules/module-structure.md` |
+| Moving facts between sections (see `resolve-section-ownership`) | `../../rules/module-structure.md`, plus the rule file of each section involved |
 | Definitions or concept usage | `../../rules/definitions.md` |
 | Functional specs or acceptance tests | `../../rules/func-specs.md` |
 | Implementation requirements or unit tests | `../../rules/impl-reqs.md` |
@@ -36,7 +50,8 @@ All paths are relative to this `SKILL.md`.
 | `required_concepts` | `../../rules/required-concepts.md` |
 | `exported_concepts` | `../../rules/exported-concepts.md` |
 | Linked files or `resources/` | `../../rules/linked-resources.md` |
-| Any `.plain` text or example | `../../rules/bullet-continuation.md` |
+| Any `.plain` text or example | `../../rules/bullet-continuation.md`, `../../rules/concise-specs.md` |
+| Drafting or trimming spec wording, or reviewing a spec for verbosity | `../../rules/concise-specs-examples.md` |
 
 For a whole-file review or a task spanning several sections, load the union of the applicable rule
 files. Do not load every rule by default.
@@ -53,6 +68,9 @@ Then read the rule matching the integration shape:
 - Standalone integration: `../../rules/integration-standalone.md`
 - Embedded integration test scripts: `../../rules/integration-embedded-testing.md`
 
+When drafting or trimming the wording of an integration spec, also read
+`../../rules/concise-specs-integration-examples.md`.
+
 Do not load integration rules for ordinary non-integration specs.
 
 ## 4. Load operational references only when needed
@@ -61,7 +79,7 @@ Authoring rules remain authoritative if a reference appears to conflict with the
 
 | Need | Reference |
 |---|---|
-| Project layout, source-of-truth model, templates, or comments | `references/project-model.md` |
+| Project layout, source-of-truth model, or template inclusion | `references/project-model.md` |
 | Rendering order, generated artifacts, conformance workflow, or test scripts | `references/rendering-and-testing.md` |
 | `codeplain` path resolution or CLI options | Invoke `load-codeplain-reference` |
 

package/forge/skills/load-plain-reference/references/project-model.md

@@ -35,14 +35,3 @@ In addition to frontmatter `import`, ***plain supports parameterized template in
 
 Parameters are key-value pairs. Templates access them with `{{ variable_name }}`. Only variable
 substitution is supported; conditionals, loops, and other Liquid features are not available.
-
-## Comments
-
-Lines beginning with `>` are ignored during rendering:
-
-```plain
-> This is a comment in ***plain.
-```
-
-Comments explain the specification to human authors. Do not use comments to carry requirements the
-renderer must implement.

package/forge/skills/plain-healthcheck/SKILL.md

@@ -36,7 +36,7 @@ The skill is a **detect → fix → re-run** loop. It does not stop at the first
 
 ### Step 1 — Inventory the project
 
-1. List every `.plain` file in the repo root (and any subdirectories that contain `.plain` files). Build the module graph from each file's YAML frontmatter (`requires`, `import`).
+1. List every `.plain` file in the repo root (and any subdirectories that contain `.plain` files). Build the module graph from each file's YAML frontmatter (`requires`, `import`). Verify the `requires` graph forms a tree: every module's multiple `requires` entries must lie on one root-to-tip ancestor path.
 2. Identify **top modules** — every module that is not `requires`-ed by any other module. A single-stack project has one top module; a multi-part project (e.g. backend + frontend) has one top module per part.
 3. List every `config.yaml` in the repo (root and per-part directories such as `backend/`, `frontend/`).
 4. List every script under `test_scripts/`.

package/forge/skills/refactor-module/SKILL.md

@@ -125,7 +125,7 @@ For each subsequent module in the chain:
 
 After all new modules are created:
 - If the original module is being fully replaced (all specs moved out), delete it or rename it to avoid confusion.
-- If the original module was required by other modules, update those modules to `require` the last module in the new chain instead (since it transitively includes all prior modules' specs and generated code).
+- If the original module was required by other modules, update those modules to `require` the last module in the new chain instead — its accumulated code and previous functional specs cover the whole chain. Exported concepts are **not** transitive, though: if a downstream module references a concept now exported by an earlier module in the new chain, it must list that earlier module in its `requires` as well.
 
 ## Phase 4 — Verify
 
@@ -145,7 +145,7 @@ Verify that the chronological order of all functional specs — when read across
 ### 4c. Concept availability check
 
 For each module, verify:
-- [ ] Every `:Concept:` referenced in its specs is either defined locally, available via `import`, or available via `exported_concepts` from the `requires` chain
+- [ ] Every `:Concept:` referenced in its specs is either defined locally, available via `import`, or available via `exported_concepts` from a module listed in `requires`
 - [ ] `exported_concepts` includes every concept that downstream modules need
 - [ ] No concept name collisions between modules
 
@@ -193,5 +193,5 @@ Acceptance tests are nested under their parent functional spec. When moving a sp
 - [ ] Each module has at least one functional spec and one implementation req
 - [ ] `requires` chain is correctly ordered (base → leaf)
 - [ ] Original module removed or updated
-- [ ] Downstream modules (if any) updated to require the correct module
+- [ ] Downstream modules (if any) updated to require the chain tip, plus any earlier chain modules whose exported concepts they reference
 - [ ] User approved the final result