fix(cli): the stack-value guard sat at one door, and RELEASING still said 7

Both from the same independent review of the previous session's commits.

**`meta agent-docs` still silently dropped an unknown `--server` value.**
`assertKnownStackValues` was added to `initCommand`'s arg parse only, and
`agent-docs` calls `init()` directly. Side by side:

    meta init --docs-only --server klingon   → exit 2, names the value
    meta agent-docs --server klingon         → exit 0, "Scaffolded … (11 files)",
                                               manifest records "servers": []

That is the worse of the two doors to miss: `index.ts` labels `agent-docs` the
"canonical redirect target for all language ports", so the four non-TS ports
were the ones using the unguarded one. And the failure does not degrade — a
non-empty override array suppresses BOTH the prior manifest's stack and
detection, so a dropped value inverts three statements in the artifact whose
whole job is to orient an agent correctly.

The guard now lives in `init()`, the shared function every door goes through,
refusing before anything is written. `initCommand` keeps its own call so a bad
flag stays a usage error (exit 2) rather than the exit 1 an init failure gets.
Gated at both doors plus the programmatic one, proved by removing the shared
guard.

**`docs/RELEASING.md` still hardcoded Maven major 7 in three places**, one
release before the cut that makes it 8. `663f67d87` consolidated the derivation
into `scripts/maven-coordinate.mjs` and named the un-executed door as "the
hardest of the four to catch: nothing executes it" — then left the document
that instruction points at. It now states the offset as permanent, names
`8.0.0` for the 1.0 cut explicitly, and says not to type a literal `7.`
anywhere, because at the cut that asks Central for a version BELOW the last
release.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NTcEKXTQMYt84fAjuw5A2M

Author: dmealing

docs/RELEASING.md

@@ -17,7 +17,10 @@
 > number when you do (standing policy since 0.24.5, replacing the version-parity rule of
 > 0.20.13):** a registry publishes only when it has a changed product file, and when it does it
 > adopts the **current shared `minor.patch`** — skipping the numbers it sat out. npm / PyPI /
-> NuGet on `0.<m>.<p>`, Maven on `7.<m>.<p>` (only the major differs, for historical continuity).
+> NuGet on `<M>.<m>.<p>`, Maven on `<M+7>.<m>.<p>` — only the MAJOR differs, and the offset is
+> permanent (`scripts/maven-coordinate.mjs` is the single derivation; every script imports it).
+> Concretely: npm `0.25.0` is Maven `7.25.0`, and npm `1.0.0` is Maven **`8.0.0`**. Do not type
+> a literal `7.` anywhere — at the 1.0 cut it asks Central for a version BELOW the last release.
 > Two carve-outs: the **14 npm packages still move atomically with each other** (they
 > cross-depend — that is intra-npm lockstep and it is unchanged), and a change to
 > `expected-registry.json` / `metamodelVersion` **forces all four**, because that is the
@@ -161,7 +164,8 @@ Publish in tier order so a dependent never lands before its dependency. **`forge
    displayed a coordinate yet.
 
    So `release.mjs` pushes `main` and **stops**. After the ports are bumped, committed,
-   pushed and tagged (`python-v*`, `csharp-v*`, `java-v7.*`), run:
+   pushed and tagged (`python-v*`, `csharp-v*`, `java-v<npm major + 7>.*` — `java-v8.*` at the
+   1.0 cut, NOT `java-v7.*`), run:
 
    ```bash
    bun scripts/finish-release.mjs <version>            # gates, then tags and pushes
@@ -662,8 +666,8 @@ subsequent releases keyless.)
 # Releasing the Java/Kotlin modules to Maven Central
 
 The 18 `com.metaobjects:*` modules ship to **Maven Central via the Sonatype Central Portal**,
-versioned on the `7.x` line (currently `7.25.0`) in the parent + module poms. Signed with the
-maintainer's GPG key.
+versioned on its own major line — npm major + 7, so `7.x` while npm is `0.x` and `8.x` from the
+1.0 cut (currently `7.25.0`) — in the parent + module poms. Signed with the maintainer's GPG key.
 
 ## Procedure
 

server/typescript/packages/cli/src/commands/init.ts

@@ -603,6 +603,16 @@ async function writeConfigFile(opts: InitOptions, result: InitResult, agentDir:
 }
 
 export async function init(opts: InitOptions): Promise<InitResult> {
+  // Refused HERE, in the shared function, before anything is written — NOT at one CLI
+  // entry point. It was at `initCommand`'s arg parse only, and `meta agent-docs` calls
+  // this directly: `meta init --docs-only --server klingon` exited 2 with the message
+  // while `meta agent-docs --server klingon` exited 0, reported "11 files", and recorded
+  // `"servers": []`. That is the worse of the two doors to miss — `agent-docs` is the
+  // canonical redirect target for every language port, so the ports used the unguarded
+  // one. A non-empty override array suppresses both the prior manifest's stack AND
+  // detection, so a dropped value does not degrade, it inverts three statements in the
+  // generated context.
+  assertKnownStackValues({ servers: opts.servers ?? [], clients: opts.clients ?? [] });
   const result: InitResult = { created: [], preserved: [], removed: [], warnings: [] };
   const agentDir = join(opts.cwd, DEFAULT_METAOBJECTS_DIR);
   const metaobjectsDir = join(opts.cwd, DEFAULT_METADATA_DIR);
@@ -1138,10 +1148,8 @@ export async function initCommand(args: string[], cwd: string): Promise<number>
   let flags;
   try {
     flags = parseInitArgs(args);
-    // Refused HERE, before anything is written: a value that names nothing used to be
-    // dropped silently, and a non-empty override array then suppressed both the prior
-    // manifest's stack and detection — so the scaffolded context asserted an empty stack
-    // and a missing config about a project that had both. See `assertKnownStackValues`.
+    // Also here, so a bad value is a USAGE error (exit 2) rather than the exit 1 an
+    // init failure gets. `init()` refuses it too, which is what covers every other door.
     assertKnownStackValues({ servers: flags.servers ?? [], clients: flags.clients ?? [] });
   } catch (err) {
     log.error((err as Error).message);

server/typescript/packages/cli/test/unit/stack-values.test.ts

@@ -45,3 +45,45 @@ describe("stack value validation", () => {
     expect(stack.servers).toContain("typescript");
   });
 });
+
+// The guard has to sit in the SHARED function, not at one CLI entry point.
+//
+// It was at `initCommand`'s arg parse only, and `meta agent-docs` calls `init()` directly:
+// `meta init --docs-only --server klingon` exited 2 with the message, while
+// `meta agent-docs --server klingon` exited 0, reported "Scaffolded … (11 files)" and
+// wrote `"servers": []` into the manifest. That is the worse door to miss — index.ts
+// labels `agent-docs` the "canonical redirect target for all language ports", so the four
+// non-TS ports were the ones using the unguarded one.
+describe("every door refuses an unknown stack value", () => {
+  test("init() itself refuses, so a programmatic caller cannot bypass it", async () => {
+    const { init } = await import("../../src/commands/init.js");
+    const { mkdtemp, rm } = await import("node:fs/promises");
+    const { tmpdir } = await import("node:os");
+    const { join } = await import("node:path");
+    const dir = await mkdtemp(join(tmpdir(), "stack-guard-"));
+    try {
+      await expect(init({ cwd: dir, servers: ["klingon"], docsOnly: true })).rejects.toThrow(/klingon/);
+    } finally { await rm(dir, { recursive: true, force: true }); }
+  });
+
+  test("meta agent-docs refuses it too, and writes nothing", async () => {
+    const { run } = await import("../../src/index.js");
+    const { mkdtemp, rm, readdir } = await import("node:fs/promises");
+    const { tmpdir } = await import("node:os");
+    const { join } = await import("node:path");
+    const dir = await mkdtemp(join(tmpdir(), "stack-guard-cli-"));
+    const orig = console.error;
+    const lines: string[] = [];
+    console.error = (...a: unknown[]) => { lines.push(a.map(String).join(" ")); };
+    try {
+      const exit = await run(["agent-docs", "--server", "klingon", "--out", dir]);
+      expect(exit).not.toBe(0);
+      expect(lines.join("\n")).toContain("klingon");
+      // Nothing scaffolded: the refusal lands before any write, as it does for init.
+      expect(await readdir(dir)).toEqual([]);
+    } finally {
+      console.error = orig;
+      await rm(dir, { recursive: true, force: true });
+    }
+  });
+});