fix(init): one silently dropped flag value made three statements false

F54 — `meta init --server node`, the value the CLI's own `--help` gives as an
example, exited 0 with no warning and recorded `"servers": []`. The four missing
reference fragments were the small half.

F56 is the large half, and it is the SAME defect: a non-empty override array
suppresses both the prior manifest's stack and detection, so `["node"]` filtered
to `[]` left the scaffolded context declaring "Stack: no server, no client" and
telling the agent that this project has no `metaobjects.config.ts` — about a
project with a Fastify server, a React client, and the very config file the same
CLI had just read to run `meta gen`. One dropped value made three statements
false in the artifact whose entire job is to orient an agent correctly.

An unknown `--server` / `--client` value is now REFUSED before anything is
written, naming the vocabulary; and `node` is ACCEPTED, as an alias for
`typescript`, because the help text gives it and it is the more natural word for
a Fastify backend run by the Node CLI. Either accept it or say so — never
neither. Being accepted is not the same as being resolved, so the test asserts
`node` lands as `typescript` and not merely that it stopped throwing. The help
text is corrected too: it now names the vocabulary instead of examples, one of
which (`--client vue`) was a value this CLI has never accepted.

F53 — the scaffold manifest recorded the hash of content it DECLINED to write.
`hashContents(f.contents)` was stamped for every assembled file before the
write/decline decision, so a path whose fresh content went to `<path>.new` —
"tell, don't merge" working exactly as designed — was recorded with the hash of
the file that was not written: a value matching neither the disk nor anything
this tool had ever written, in the one record that exists to tell "still what we
scaffolded" from "hand-edited", under a `generatedBy` asserting the context was
current while the file on disk was the predecessor's text. A declined path now
keeps the PRIOR hash — what we last actually wrote, so reverting the edit lets
the next refresh see an unmodified file — and a declined path we have never
written gets no entry, because there is no true value to record.

F55 — `meta init` reports "(11 files)" while eight land under `.claude/`, which
many projects git-ignore under a comment about credentials. Ignored, they exist
only on the machine that ran the command — not committed, absent from CI and a
fresh clone, invisible to a teammate — while `.agent-context.json`, which IS
committed, records every one. That silently voids the whole downstream
agent-context design, and the answer was available from the outputs the command
had just written. Now an advisory naming the count and the directories, never an
error: ignoring `.claude/` may be exactly what the project wants.

cli 852 pass, sdk 278 pass, workspace typecheck clean.

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

Author: dmealing

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

@@ -8,7 +8,8 @@ import {
   assemble, resolveAgentContextRoot, planScaffold,
   AGENT_CONTEXT_MANIFEST_PATH, type Manifest, type Stack,
 } from "@metaobjectsdev/sdk/agent-context";
-import { resolveStack } from "../lib/detect-stack.js";
+import { assertKnownStackValues, resolveStack } from "../lib/detect-stack.js";
+import { reportIgnoredScaffold } from "../lib/ignored-scaffold-check.js";
 import { parseInitArgs } from "../lib/args.js";
 import { log } from "../lib/log.js";
 import { cliVersion } from "../lib/version.js";
@@ -1135,6 +1136,11 @@ 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`.
+    assertKnownStackValues({ servers: flags.servers ?? [], clients: flags.clients ?? [] });
   } catch (err) {
     log.error((err as Error).message);
     return 2;
@@ -1163,6 +1169,14 @@ export async function initCommand(args: string[], cwd: string): Promise<number>
     }
 
     if (!flags.quiet) {
+      // A count is not a guarantee that the files reached the repository. Many projects
+      // git-ignore `.claude/` under a comment about credentials — a common and defensible
+      // convention — and eight of the eleven files land there. Ignored, they exist only on
+      // the machine that ran this: not committed, absent from CI and from a fresh clone,
+      // invisible to a teammate, while `.agent-context.json` (which IS committed) tracks
+      // them. That silently voids the whole downstream agent-context design, and the answer
+      // was available from the outputs this command had just written.
+      reportIgnoredScaffold(cwd, result.created);
       if (flags.docsOnly) {
         log.info(`Scaffolded the MetaObjects agent context (${result.created.length} files): .metaobjects/AGENTS.md + .claude/skills/metaobjects-*.`);
         for (const w of result.warnings) log.info(`  ${w}`);

server/typescript/packages/cli/src/index.ts

@@ -300,10 +300,12 @@ FLAGS:
   --docs-only           Write only the agent-context files — no metadata sources, no
                         codegen scaffold, no config. Pair with --refresh-docs to update
                         an existing project after upgrading.
-  --server <lang>       Declare a server language for the agent context (repeatable;
-                        e.g. csharp, kotlin, python, node)
-  --client <fw>         Declare a client framework for the agent context (repeatable;
-                        e.g. react, vue)
+  --server <lang>       Declare a server language for the agent context (repeatable):
+                        typescript | java | kotlin | csharp | python
+                        ('node' is accepted as an alias for typescript; an unknown
+                        value is refused, never dropped)
+  --client <fw>         Declare a client framework for the agent context (repeatable):
+                        react | tanstack | angular
   --no-skills           Skip the .claude/skills/ scaffold
   --force               Overwrite existing files
   --quiet               Suppress output
@@ -320,8 +322,8 @@ USAGE:
   meta agent-docs [--server <lang>]... [--client <fw>]... [--out <dir>] [flags]
 
 FLAGS:
-  --server <lang>       Server language (repeatable; e.g. csharp, kotlin, python, node)
-  --client <fw>         Client framework (repeatable; e.g. react, vue)
+  --server <lang>       Server language (repeatable): typescript|java|kotlin|csharp|python
+  --client <fw>         Client framework (repeatable): react|tanstack|angular
   --out <dir>           Output directory (default: current directory)
   --no-skills           Skip .claude/skills/ scaffold
   --no-wire-root        Skip wiring root CLAUDE.md @import

server/typescript/packages/cli/src/lib/detect-stack.ts

@@ -48,14 +48,85 @@ async function probe(cwd: string): Promise<ProjectProbe> {
   };
 }
 
+/**
+ * Spellings accepted for a stack value that is not the canonical one.
+ *
+ * `node` is here because the CLI's OWN `--help` gives it as an example of `--server`, and it
+ * is the more natural word for a Fastify backend run by the Node CLI. It used to be filtered
+ * out silently — see `assertKnownStackValues` for what that silence cost.
+ */
+const SERVER_ALIASES: Readonly<Record<string, ServerLang>> = {
+  node: "typescript",
+  nodejs: "typescript",
+  ts: "typescript",
+  "c#": "csharp",
+  dotnet: "csharp",
+  py: "python",
+};
+
+const CLIENT_ALIASES: Readonly<Record<string, ClientFramework>> = {
+  reactjs: "react",
+  "react-query": "tanstack",
+};
+
+/** Canonicalize one value, or `undefined` when it names nothing we know. */
+function canonical<T extends string>(
+  raw: string,
+  valid: readonly string[],
+  aliases: Readonly<Record<string, T>>,
+): T | undefined {
+  const v = raw.trim().toLowerCase();
+  if (valid.includes(v)) return v as T;
+  return aliases[v];
+}
+
+/**
+ * Refuse an unknown `--server` / `--client` value instead of dropping it.
+ *
+ * `--server node` — the CLI's own help example — used to exit 0 with no warning and record
+ * `"servers": []`. Worse than the missing four reference fragments: a non-empty override
+ * array suppresses BOTH the prior manifest's stack and detection, so the emitted context then
+ * declared "Stack: no server, no client" and told the agent that this project has no
+ * `metaobjects.config.ts` — about a project with a Fastify server, a React client, and the
+ * very config file the same CLI had just read. One silently-dropped flag value made three
+ * statements false in the artifact whose whole job is to orient an agent correctly.
+ *
+ * Either accept the value or say so; never neither.
+ */
+export function assertKnownStackValues(overrides: { servers: string[]; clients: string[] }): void {
+  const bad: string[] = [];
+  for (const s of overrides.servers) {
+    if (canonical(s, SERVER_LANGS as readonly string[], SERVER_ALIASES) === undefined) {
+      bad.push(`--server ${s} (known: ${SERVER_LANGS.join(", ")})`);
+    }
+  }
+  for (const c of overrides.clients) {
+    if (canonical(c, CLIENT_FRAMEWORKS as readonly string[], CLIENT_ALIASES) === undefined) {
+      bad.push(`--client ${c} (known: ${CLIENT_FRAMEWORKS.join(", ")})`);
+    }
+  }
+  if (bad.length > 0) {
+    throw new Error(
+      `unknown stack value(s): ${bad.join("; ")}. A value that names nothing is refused rather ` +
+        "than dropped: an empty stack suppresses both the prior manifest and detection, and the " +
+        "generated agent context then states the project has no server, no client and no " +
+        "metaobjects.config.ts.",
+    );
+  }
+}
+
 /** Resolve the stack: explicit --server/--client overrides take precedence; otherwise detect.
  * Concern tokens (e.g. requirements) are always OBSERVED from project state, independent of
  * any --server/--client override — a concern is not a stack axis. */
 export async function resolveStack(cwd: string, overrides: { servers: string[]; clients: string[] }): Promise<Stack> {
   const validServers = SERVER_LANGS as readonly string[];
   const validClients = CLIENT_FRAMEWORKS as readonly string[];
-  const oServers = overrides.servers.filter((s): s is ServerLang => validServers.includes(s));
-  const oClients = overrides.clients.filter((c): c is ClientFramework => validClients.includes(c));
+  const oServers = overrides.servers
+    .map((s) => canonical<ServerLang>(s, validServers, SERVER_ALIASES))
+    .filter((s): s is ServerLang => s !== undefined);
+  const oClients = overrides.clients
+    .map((c) => canonical<ClientFramework>(c, validClients, CLIENT_ALIASES))
+    .filter((c): c is ClientFramework => c !== undefined);
   const p = await probe(cwd);
   const concerns = detectConcerns(p);
   if (oServers.length > 0 || oClients.length > 0) return makeStack(oServers, oClients, concerns);

server/typescript/packages/cli/src/lib/ignored-scaffold-check.ts

@@ -0,0 +1,57 @@
+// Advisory: did the scaffold land in a directory this repository ignores?
+//
+// `meta init` reports "(11 files)". Eight of them go under `.claude/skills/`, and many
+// projects git-ignore `.claude/` — commonly under a comment about credentials, which is a
+// defensible convention, not a mistake. Ignored, those files exist only on the machine that
+// ran the command: never committed, absent from CI and from a fresh clone, invisible to a
+// teammate — while `.metaobjects/.agent-context.json`, which IS committed, records every one
+// of them. The count says eleven; the repository gets three.
+//
+// The failure is INVISIBLE, which is why it is worth a check rather than a doc: nothing
+// errors, nothing looks wrong, and the whole downstream agent-context design is simply void
+// for that repo.
+//
+// Deliberately ADVISORY. Ignoring `.claude/` may be exactly what the project wants — it is a
+// per-repo policy call, and a scaffolder has no standing to fail a build over it.
+
+import { relative } from "node:path";
+import { log } from "./log.js";
+import { gitIgnored } from "./git-ignore.js";
+
+/**
+ * Warn when some of the scaffolded paths are git-ignored, naming how many and where.
+ *
+ * Silent when: nothing is ignored, the project is not a git repository, or git cannot be
+ * consulted — "cannot say" must never be reported as "there is a problem".
+ *
+ * `honourGlobalExcludes: false` for the same reason the docs-drift gate uses it: this is a
+ * property of the REPOSITORY, and a personal `~/.gitignore` is not something a teammate
+ * shares. A warning that fires for one developer and not another is worse than none.
+ */
+export function reportIgnoredScaffold(cwd: string, created: readonly string[]): void {
+  const rels = created
+    .map((p) => relative(cwd, p) || p)
+    .map((p) => p.split("\\").join("/"))
+    .filter((p) => p.length > 0 && !p.startsWith(".."));
+  if (rels.length === 0) return;
+
+  const res = gitIgnored(cwd, rels, { honourGlobalExcludes: false });
+  if ("unavailable" in res) return;   // not a git repo, or git could not answer
+  const ignored = rels.filter((p) => res.ignored.has(p));
+  if (ignored.length === 0) return;
+
+  // Report the DIRECTORIES rather than every path: an adopter fixes this by editing one
+  // `.gitignore` line, and a wall of forty filenames buries that.
+  const dirs = [...new Set(ignored.map((p) => {
+    const i = p.indexOf("/");
+    return i < 0 ? p : p.slice(0, i) + "/";
+  }))].sort();
+
+  log.warn(
+    `${ignored.length} of ${rels.length} scaffolded file(s) are git-ignored (${dirs.join(", ")}), ` +
+      "so they exist only on this machine — not committed, absent from CI and from a fresh " +
+      "clone, invisible to a teammate — while .metaobjects/.agent-context.json is committed " +
+      "and records them. If the agent context is meant to be shared, un-ignore those paths; " +
+      "if it is deliberately local, nothing to do.",
+  );
+}

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

@@ -0,0 +1,47 @@
+// A stack value that names nothing is REFUSED, not dropped.
+//
+// `--server node` — the CLI's own help example — exited 0 with no warning and recorded
+// `"servers": []`. The missing four reference fragments were the small half. The large half is
+// that a NON-EMPTY override array suppresses both the prior manifest's stack AND detection, so
+// the scaffolded agent context then declared "Stack: no server, no client" and told the agent
+// this project has no `metaobjects.config.ts` — about a project with a Fastify server, a React
+// client, and the very config file the same CLI had just read to run `meta gen`. One silently
+// dropped flag value made three statements false in the artifact whose whole job is to orient
+// an agent correctly.
+import { describe, test, expect } from "bun:test";
+import { assertKnownStackValues, resolveStack } from "../../src/lib/detect-stack.js";
+
+describe("stack value validation", () => {
+  test("an unknown --server is refused, and the message names the vocabulary", () => {
+    expect(() => assertKnownStackValues({ servers: ["klingon"], clients: [] }))
+      .toThrow(/unknown stack value.*--server klingon.*typescript, java, kotlin, csharp, python/s);
+  });
+
+  test("an unknown --client is refused too", () => {
+    expect(() => assertKnownStackValues({ servers: [], clients: ["vue"] }))
+      .toThrow(/--client vue.*react, tanstack, angular/s);
+  });
+
+  test("`node` is ACCEPTED as an alias for typescript — the help text's own example", () => {
+    expect(() => assertKnownStackValues({ servers: ["node"], clients: [] })).not.toThrow();
+  });
+
+  test("canonical values pass unchanged", () => {
+    expect(() => assertKnownStackValues({
+      servers: ["typescript", "java", "kotlin", "csharp", "python"],
+      clients: ["react", "tanstack", "angular"],
+    })).not.toThrow();
+  });
+
+  test("case and surrounding space do not decide whether a value is known", () => {
+    expect(() => assertKnownStackValues({ servers: [" Node ", "TypeScript"], clients: [] }))
+      .not.toThrow();
+  });
+
+  test("...and the alias resolves to the canonical language, not to nothing", async () => {
+    // The half that actually cost the estate its four reference fragments: being accepted is
+    // not the same as being RESOLVED. `node` must land as `typescript`.
+    const stack = await resolveStack(process.cwd(), { servers: ["node"], clients: [] });
+    expect(stack.servers).toContain("typescript");
+  });
+});

server/typescript/packages/sdk/src/agent-context/scaffold.ts

@@ -68,17 +68,32 @@ export function planScaffold(opts: {
   const conflicts: ScaffoldDecision["conflicts"] = [];
   const files: Record<string, string> = {};
 
+  // The manifest records what we WROTE, never what we merely produced. It used to be
+  // stamped with `hashContents(f.contents)` for every assembled file, before the write /
+  // decline decision — so a DECLINED path (contents parked in `<path>.new`, original left
+  // alone by design) was recorded with the hash of the file that was not written. That hash
+  // matched neither the disk nor anything this tool had ever written: pure fiction in the
+  // one record that exists to tell "still exactly what we scaffolded" from "hand-edited",
+  // sitting under a `generatedBy` asserting the context was current at this version while
+  // the file on disk was the predecessor's text.
+  //
+  // A declined path keeps the PRIOR hash — what we last actually wrote — so the comparison
+  // stays meaningful: revert the hand edit and the next refresh sees an unmodified file and
+  // refreshes it. A declined path we have never written (a file that was already there,
+  // unmanaged) gets no entry at all, because there is no true value to record.
   for (const f of assembled) {
-    files[f.path] = hashContents(f.contents);
     const current = readCurrent(f.path);
     if (current === undefined) {
+      files[f.path] = hashContents(f.contents);
       writes.push({ path: f.path, contents: f.contents });
       continue;
     }
     const priorHash = prior?.files[f.path];
     if (priorHash !== undefined && hashContents(current) === priorHash) {
+      files[f.path] = hashContents(f.contents);
       writes.push({ path: f.path, contents: f.contents }); // unmodified → refresh to latest
     } else {
+      if (priorHash !== undefined) files[f.path] = priorHash;
       conflicts.push({ path: f.path, newPath: `${f.path}.new`, contents: f.contents });
     }
   }

server/typescript/packages/sdk/test/agent-context/scaffold.test.ts

@@ -168,3 +168,60 @@ describe("agentContextStaleness", () => {
     expect(agentContextStaleness({ manifest: m("dev"), currentVersion: "0.24.4" })).not.toBeNull();
   });
 });
+
+// F53 — the manifest must record what was WRITTEN, never what was merely produced.
+//
+// It used to stamp `hashContents(f.contents)` for every assembled file, before the
+// write/decline decision. So a DECLINED path — contents parked in `<path>.new`, original
+// left alone, which is the "tell, don't merge" design working — was recorded with the hash
+// of the file that was NOT written: a value matching neither the disk nor anything this
+// tool had ever written, in the one record that exists to tell "still exactly what we
+// scaffolded" from "hand-edited", under a `generatedBy` asserting the context was current
+// at this version while the file on disk was the predecessor's text.
+describe("planScaffold — the manifest never records content it declined to write", () => {
+  const hand: AssembledFile[] = [{ path: ".metaobjects/AGENTS.md", contents: "fresh v3" }];
+
+  test("a declined path keeps the PRIOR hash, not the hash of the unwritten file", () => {
+    const prior: Manifest = {
+      version: 1,
+      servers: ["typescript"],
+      clients: ["react"],
+      files: { ".metaobjects/AGENTS.md": hashContents("what we wrote last time") },
+    };
+    const d = planScaffold({
+      stack,
+      assembled: hand,
+      prior,
+      readCurrent: () => "hand-edited by the adopter",
+      generatedBy: "1.0.0",
+    });
+    expect(d.conflicts.map((c) => c.newPath)).toEqual([".metaobjects/AGENTS.md.new"]);
+    expect(d.writes).toEqual([]);
+    // The recorded value is what we last WROTE — so reverting the hand edit makes the next
+    // refresh see an unmodified file and refresh it cleanly.
+    expect(d.manifest.files[".metaobjects/AGENTS.md"]).toBe(hashContents("what we wrote last time"));
+    expect(d.manifest.files[".metaobjects/AGENTS.md"]).not.toBe(hashContents("fresh v3"));
+  });
+
+  test("a declined path we have NEVER written gets no entry at all", () => {
+    // A file that was simply already there, unmanaged (the estate's `forge init`-era
+    // context). There is no true value to record, so nothing is recorded.
+    const d = planScaffold({
+      stack,
+      assembled: hand,
+      prior: undefined,
+      readCurrent: () => "a file this tool never wrote",
+      generatedBy: "1.0.0",
+    });
+    expect(d.conflicts).toHaveLength(1);
+    expect(Object.keys(d.manifest.files)).not.toContain(".metaobjects/AGENTS.md");
+  });
+
+  test("...and a path that WAS written still records the new hash", () => {
+    const d = planScaffold({
+      stack, assembled: hand, prior: undefined, readCurrent: () => undefined, generatedBy: "1.0.0",
+    });
+    expect(d.writes).toHaveLength(1);
+    expect(d.manifest.files[".metaobjects/AGENTS.md"]).toBe(hashContents("fresh v3"));
+  });
+});