@warpgogol/forge 5.3.0 → 5.3.2

package/os/rfc/handlers/validate.ts

@@ -13,6 +13,7 @@ Mechanical v1 to v2 header migration across the workspace: 942 files rewritten
   <item>RFC-1097: sweep — werkstatt-engine clean
 
 Sweep batch 4: 73 Compass headers on headerless engine files (certification, component-runtime, isolation, evolution, testing), real KEY_DECISIONS on 75 files (kernel, cache, dht, swim, gitmesh, runtime), ~80 purpose expansions (CONTRACT-02/PURPOSE-02), non-goals on 13 CONTRACT-03 files, CS-07 history literal fix repo-wide (253 files). Policy: .template.ts/.template.astro excludedPaths. werkstatt-engine now 0 diagnostics.</item>
+  <item>Guard --id against non-string values (boolean/array from unvalidated flag input) — throws a clear flag error instead of TypeError in rfcFileMatchesId.</item>
 </CHANGE_SUMMARY>
 */
 
@@ -48,7 +49,11 @@ export async function runRfcValidate(
   const { workspaceRoot, logger, outputFormat } = context;
   const rfcDirPath = path.join(workspaceRoot, RFC_DIR);
 
-  const targetId = input.flags["id"] as string | undefined;
+  const rawId = input.flags["id"];
+  if (rawId !== undefined && typeof rawId !== "string") {
+    throw new Error(`Flag "--id" for command "rfc.validate" requires a single string value.`);
+  }
+  const targetId = rawId as string | undefined;
 
   const allFiles = await listRfcFiles(rfcDirPath);
   const filesToValidate = targetId

package/os/werkstatt/handlers/workspace-deps.ts

@@ -9,7 +9,6 @@
 <CHANGE_SUMMARY>
   <item>RFC-0682: extract dynamic-import helper so forge publishes without workspace:* deps.</item>
   <item>RFC-0940: moved from os/core/handlers/ to os/werkstatt/handlers/ — this module imports @warpgogol/werkstatt-engine and belongs in the adapter directory.</item>
-  <item>2026-09-22: fingerprint import switched from @warpgogol/werkstatt-engine/fingerprint to @warpgogol/werkstatt-shared/fingerprint (canonical home since RFC-1104) — breaks the forge↔engine package cycle reported by turbo.</item>
 </CHANGE_SUMMARY>
 */
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@warpgogol/forge",
-  "version": "5.3.0",
+  "version": "5.3.2",
   "private": false,
   "type": "module",
   "license": "Apache-2.0",

package/profiles/forge-shell.yaml

@@ -525,7 +525,7 @@ workspace:
           "hooks": {
             "pre_user_prompt": [
               {
-                "command": "node $ROOT_WORKSPACE_PATH/hooks/pre-user-prompt-wrapper.mjs",
+                "command": "node \"${ROOT_WORKSPACE_PATH:-$PWD}/hooks/pre-user-prompt-wrapper.mjs\"",
                 "show_output": true
               }
             ]

package/profiles/godot-game.yaml

@@ -1002,7 +1002,7 @@ workspace:
           "hooks": {
             "pre_user_prompt": [
               {
-                "command": "node $ROOT_WORKSPACE_PATH/hooks/pre-user-prompt-wrapper.mjs",
+                "command": "node \"${ROOT_WORKSPACE_PATH:-$PWD}/hooks/pre-user-prompt-wrapper.mjs\"",
                 "show_output": true
               }
             ]

package/profiles/knowledge.yaml

@@ -378,7 +378,7 @@ workspace:
           "hooks": {
             "pre_user_prompt": [
               {
-                "command": "node $ROOT_WORKSPACE_PATH/hooks/pre-user-prompt-wrapper.mjs",
+                "command": "node \"${ROOT_WORKSPACE_PATH:-$PWD}/hooks/pre-user-prompt-wrapper.mjs\"",
                 "show_output": true
               }
             ]

package/profiles/phaser-game.yaml

@@ -605,7 +605,7 @@ workspace:
           "hooks": {
             "pre_user_prompt": [
               {
-                "command": "node $ROOT_WORKSPACE_PATH/hooks/pre-user-prompt-wrapper.mjs",
+                "command": "node \"${ROOT_WORKSPACE_PATH:-$PWD}/hooks/pre-user-prompt-wrapper.mjs\"",
                 "show_output": true
               }
             ]

package/profiles/site-workshop.yaml

@@ -516,7 +516,7 @@ workspace:
           "hooks": {
             "pre_user_prompt": [
               {
-                "command": "node $ROOT_WORKSPACE_PATH/hooks/pre-user-prompt-wrapper.mjs",
+                "command": "node \"${ROOT_WORKSPACE_PATH:-$PWD}/hooks/pre-user-prompt-wrapper.mjs\"",
                 "show_output": true
               }
             ]

package/profiles/typescript.yaml

@@ -453,7 +453,7 @@ workspace:
           "hooks": {
             "pre_user_prompt": [
               {
-                "command": "node $ROOT_WORKSPACE_PATH/hooks/pre-user-prompt-wrapper.mjs",
+                "command": "node \"${ROOT_WORKSPACE_PATH:-$PWD}/hooks/pre-user-prompt-wrapper.mjs\"",
                 "show_output": true
               }
             ]

package/src/cli-flags.ts

@@ -0,0 +1,284 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Argv-to-flags resolution for the standalone forge CLI — a standalone
+port of the kernel's RFC-0260 semantics (resolveCommandFlags for schema-carrying
+commands, the heuristic parser for schema-less ones). Ensures a declared string
+flag never reaches a handler as `true`, which crashed `forge rfc.validate --id`
+with `TypeError: targetId.toLowerCase is not a function`.</purpose>
+<non-goals>
+  <item>Do not import from @warpgogol/* — forge is autonomous (FORGE-AUTONOMY-01); keep this a self-contained port.</item>
+  <item>Do not call console.* or process.exit — bin/cli.ts renders diagnostics and decides the exit code.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>Standalone port of kernel argv resolution for the forge CLI (RFC-0260 lineage): strict KERNEL-FLAG-01/02/03 + KERNEL-ARG-01 diagnostics for schema-carrying commands, legacy heuristic parse (with KERNEL-ARG-01) for schema-less commands; repeated single-value string flags diagnose instead of silently promoting to an array that crashes handlers; indexOf-based inline-value split preserves values containing "=" that split("=", 2) silently truncated.</item>
+</CHANGE_SUMMARY>
+*/
+
+import type { Diagnostic, ForgeCommandDefinition, ForgeFlagSpec, ForgeFlagValue } from "./types.ts";
+
+/**
+ * Flags every CLI command accepts regardless of its own declared schema —
+ * mirrors the kernel's KERNEL_UNIVERSAL_FLAGS so both entry points accept the
+ * same universal switches.
+ */
+export const CLI_UNIVERSAL_FLAGS: Record<string, ForgeFlagSpec> = {
+  site: { kind: "string", description: "Target a specific site by name." },
+  all: { kind: "boolean", description: "Run against every discovered app." },
+  json: { kind: "boolean", description: "Emit machine-readable JSON instead of pretty output." },
+  quiet: { kind: "boolean", description: "Suppress non-essential log output." },
+  verbose: { kind: "boolean", description: "Emit additional diagnostic log output." },
+  root: { kind: "string", description: "Override the resolved workspace root." },
+  "dry-run": { kind: "boolean", description: "Report intended mutations without writing them." },
+  force: { kind: "boolean", description: "Bypass a normally-blocking safety check." },
+  help: { kind: "boolean", description: "Print command help instead of executing." },
+};
+
+/**
+ * Boolean switches for the legacy heuristic path (schema-less commands).
+ * Mirrors the kernel's KERNEL_BOOLEAN_FLAGS: a listed flag never consumes the
+ * following token as its value.
+ */
+const CLI_BOOLEAN_FLAGS = new Set<string>([
+  "all",
+  "all-apps",
+  "approve-all",
+  "dry-run",
+  "force",
+  "help",
+  "inplace",
+  "json",
+  "mini",
+  "packages",
+  "page",
+  "prod",
+  "quiet",
+  "regen",
+  "regenerate",
+  "report-only",
+  "show-versions",
+  "strict",
+  "verbose",
+  "version",
+  "write",
+]);
+
+function addFlagValue(
+  target: Record<string, ForgeFlagValue>,
+  key: string,
+  value: string | boolean,
+): void {
+  const existing = target[key];
+
+  if (existing === undefined) {
+    target[key] = value;
+    return;
+  }
+
+  if (Array.isArray(existing)) {
+    if (typeof value === "string") {
+      target[key] = [...existing, value];
+    }
+    return;
+  }
+
+  if (typeof existing === "string") {
+    if (typeof value === "string") {
+      target[key] = [existing, value];
+      return;
+    }
+
+    target[key] = existing;
+    return;
+  }
+
+  target[key] = value;
+}
+
+function positionalDiagnostic(entry: string, commandName?: string): Diagnostic {
+  const scope = commandName ? ` for command "${commandName}"` : "";
+  return {
+    ruleId: "KERNEL-ARG-01",
+    severity: "error",
+    message: `Unexpected positional argument "${entry}"${scope}. All arguments must be passed as flags.`,
+    fixHint: `Convert "${entry}" to a flag, e.g. --id ${entry}.`,
+  };
+}
+
+/**
+ * Legacy heuristic parse for commands without a `flags` schema — mirrors the
+ * kernel's parseKernelArgv: unknown flags are accepted, boolean-ness comes
+ * from CLI_BOOLEAN_FLAGS, and positional tokens produce KERNEL-ARG-01.
+ */
+export function parseCliArgs(argv: string[]): {
+  flags: Record<string, ForgeFlagValue>;
+  diagnostics: Diagnostic[];
+} {
+  const flags: Record<string, ForgeFlagValue> = {};
+  const diagnostics: Diagnostic[] = [];
+  let passthrough = false;
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const entry = argv[index]!;
+
+    if (passthrough) {
+      diagnostics.push(positionalDiagnostic(entry));
+      continue;
+    }
+
+    if (entry === "--") {
+      passthrough = true;
+      continue;
+    }
+
+    if (!entry.startsWith("--")) {
+      diagnostics.push(positionalDiagnostic(entry));
+      continue;
+    }
+
+    const withoutPrefix = entry.slice(2);
+    const eqIndex = withoutPrefix.indexOf("=");
+    const flagName = eqIndex === -1 ? withoutPrefix : withoutPrefix.slice(0, eqIndex);
+    const inlineValue = eqIndex === -1 ? undefined : withoutPrefix.slice(eqIndex + 1);
+    if (!flagName) continue;
+
+    if (inlineValue !== undefined) {
+      addFlagValue(flags, flagName, inlineValue);
+      continue;
+    }
+
+    if (CLI_BOOLEAN_FLAGS.has(flagName)) {
+      addFlagValue(flags, flagName, true);
+      continue;
+    }
+
+    const next = argv[index + 1];
+    if (typeof next === "string" && !next.startsWith("--")) {
+      addFlagValue(flags, flagName, next);
+      index += 1;
+      continue;
+    }
+
+    addFlagValue(flags, flagName, true);
+  }
+
+  return { flags, diagnostics };
+}
+
+function resolveStrict(
+  rawArgv: string[],
+  command: ForgeCommandDefinition,
+): { flags: Record<string, ForgeFlagValue>; diagnostics: Diagnostic[] } {
+  const schema: Record<string, ForgeFlagSpec> = {
+    ...CLI_UNIVERSAL_FLAGS,
+    ...(command.flags ?? {}),
+  };
+  const validFlagNames = Object.keys(schema).sort();
+  const flags: Record<string, ForgeFlagValue> = {};
+  const diagnostics: Diagnostic[] = [];
+  let passthrough = false;
+
+  for (let index = 0; index < rawArgv.length; index += 1) {
+    const entry = rawArgv[index]!;
+
+    if (passthrough) {
+      diagnostics.push(positionalDiagnostic(entry, command.name));
+      continue;
+    }
+
+    if (entry === "--") {
+      passthrough = true;
+      continue;
+    }
+
+    if (!entry.startsWith("--")) {
+      diagnostics.push(positionalDiagnostic(entry, command.name));
+      continue;
+    }
+
+    const withoutPrefix = entry.slice(2);
+    const eqIndex = withoutPrefix.indexOf("=");
+    const flagName = eqIndex === -1 ? withoutPrefix : withoutPrefix.slice(0, eqIndex);
+    const inlineValue = eqIndex === -1 ? undefined : withoutPrefix.slice(eqIndex + 1);
+    if (!flagName) continue;
+
+    const spec = schema[flagName];
+    if (!spec) {
+      diagnostics.push({
+        ruleId: "KERNEL-FLAG-01",
+        severity: "error",
+        message: `Unknown flag "--${flagName}" for command "${command.name}". Valid flags: ${validFlagNames.join(", ")}`,
+        fixHint: `Remove --${flagName}, fix the typo, or add it to the flags schema for ${command.name}.`,
+      });
+      continue;
+    }
+
+    if (inlineValue !== undefined) {
+      addFlagValue(
+        flags,
+        flagName,
+        spec.kind === "boolean" ? inlineValue !== "false" : inlineValue,
+      );
+      continue;
+    }
+
+    if (spec.kind === "boolean") {
+      addFlagValue(flags, flagName, true);
+      continue;
+    }
+
+    const next = rawArgv[index + 1];
+    if (typeof next === "string" && !next.startsWith("--")) {
+      addFlagValue(flags, flagName, next);
+      index += 1;
+      continue;
+    }
+
+    diagnostics.push({
+      ruleId: "KERNEL-FLAG-02",
+      severity: "error",
+      message: `Flag "--${flagName}" for command "${command.name}" requires a value but none was given.`,
+      fixHint: `Pass --${flagName} <value> or --${flagName}=<value>.`,
+    });
+  }
+
+  for (const [flagName, spec] of Object.entries(schema)) {
+    const value = flags[flagName];
+    if (spec.required && value === undefined) {
+      diagnostics.push({
+        ruleId: "KERNEL-FLAG-03",
+        severity: "error",
+        message: `Required flag "--${flagName}" is missing for command "${command.name}".`,
+        fixHint: `Pass --${flagName} <value>.`,
+      });
+    } else if (value === undefined && spec.default !== undefined) {
+      flags[flagName] = spec.default;
+    } else if (spec.kind === "string" && Array.isArray(value)) {
+      diagnostics.push({
+        ruleId: "KERNEL-FLAG-02",
+        severity: "error",
+        message: `Flag "--${flagName}" for command "${command.name}" accepts a single value but was given multiple.`,
+        fixHint: `Pass --${flagName} once, or declare the flag as kind "string[]" if multiple values are intended.`,
+      });
+    }
+  }
+
+  return { flags, diagnostics };
+}
+
+/**
+ * Resolve raw argv against a command's declared flag schema (merged with
+ * CLI_UNIVERSAL_FLAGS) — the standalone-CLI counterpart of the kernel's
+ * resolveCommandFlags. Schema-carrying commands (`command.flags` set,
+ * including `{}`) resolve strictly; schema-less commands keep the legacy
+ * heuristic parse. Either way, positional tokens produce KERNEL-ARG-01.
+ */
+export function resolveCliFlags(
+  argv: string[],
+  command: ForgeCommandDefinition,
+): { flags: Record<string, ForgeFlagValue>; diagnostics: Diagnostic[] } {
+  if (command.flags) {
+    return resolveStrict(argv, command);
+  }
+  return parseCliArgs(argv);
+}

package/src/onboarding/agents-generate.ts

@@ -141,10 +141,22 @@ function readRegister(workspaceRoot: string): BehavioralRegister {
   return "business";
 }
 
+/** resolveForgeRoot throws when neither layout exists — routing-table
+ *  extraction is best-effort, so an unresolvable root yields an empty table. */
+function safeResolveForgeRoot(workspaceRoot: string): string | undefined {
+  try {
+    return resolveForgeRoot(workspaceRoot);
+  } catch {
+    return undefined;
+  }
+}
+
 function extractTriggerPhrases(
-  workspaceRoot: string,
+  forgeRoot: string | undefined,
 ): Array<{ name: string; triggerPhrases: string[] }> {
-  const forgeRoot = path.join(workspaceRoot, "packages", "forge");
+  // Consumer packages have no packages/forge — the root must come from the
+  // runtime context (or the installed package), never a hardcoded monorepo path.
+  if (!forgeRoot) return [];
   const result: Array<{ name: string; triggerPhrases: string[] }> = [];
   for (const skill of FORGE_SKILLS) {
     if (skill.category !== "fo") continue;
@@ -187,10 +199,10 @@ function generateTriggersTable(
 }
 
 function generateBehavioralLayer(
-  workspaceRoot: string,
   register: BehavioralRegister,
+  forgeRoot: string | undefined,
 ): string {
-  const triggerPhrases = extractTriggerPhrases(workspaceRoot);
+  const triggerPhrases = extractTriggerPhrases(forgeRoot);
 
   let template: string;
   try {
@@ -355,7 +367,10 @@ export async function runAgentsGenerate(
   }
 
   // Behavioral layer section (RFC-0548)
-  const behavioralLayer = generateBehavioralLayer(workspaceRoot, register);
+  const behavioralLayer = generateBehavioralLayer(
+    register,
+    context.forgeRoot ?? safeResolveForgeRoot(workspaceRoot),
+  );
   dynamicLines.push(behavioralLayer);
   dynamicLines.push("");
 

package/src/tests/agents-generate.test.ts

@@ -10,7 +10,7 @@ routing table, conditional extended layer, markers, and idempotency (RFC-0548, R
 */
 
 import { test, expect, beforeEach, afterEach } from "vitest";
-import { mkdtemp, rm, writeFile, mkdir, readFile } from "node:fs/promises";
+import { mkdtemp, rm, writeFile, mkdir, readFile, symlink } from "node:fs/promises";
 import { existsSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
@@ -108,6 +108,27 @@ test("agents-generate includes intent-to-skill routing table", async () => {
   expect(agentsMd).toContain("fo-");
 });
 
+test("agents-generate populates routing table rows in consumer layout (no packages/forge)", async () => {
+  await makeForgeYaml(tempDir);
+  // Consumer install: the package lives under node_modules — skills ship inside
+  // it. A symlinked node_modules/@warpgogol/forge mimics the npm layout.
+  const consumerPkg = join(tempDir, "node_modules", "@warpgogol", "forge");
+  await mkdir(join(consumerPkg, ".."), { recursive: true });
+  await symlink(FORGE_ROOT, consumerPkg, "junction");
+
+  // forgeRoot undefined → extraction must resolve via the consumer layout.
+  const result = await runAgentsGenerate(
+    { argv: [], flags: {} },
+    { ...makeContext(tempDir), forgeRoot: undefined },
+  );
+  expect(result.exitCode).toBe(0);
+
+  const agentsMd = await readFile(join(tempDir, "AGENTS.md"), "utf8");
+  // A quoted trigger phrase appears only in routing-table rows — the Skills
+  // table contains bare skill names, so this probes extraction end-to-end.
+  expect(agentsMd).toContain('"show RFC and ADR status"');
+});
+
 test("agents-generate includes fixed policy text sections", async () => {
   await makeForgeYaml(tempDir);
   const result = await runAgentsGenerate({ argv: [], flags: {} }, makeContext(tempDir));

package/src/tests/cli-flags.test.ts

@@ -0,0 +1,175 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Unit tests for src/cli-flags.ts — schema-driven argv-to-flags
+resolution for the standalone forge CLI (strict KERNEL-FLAG-01/02/03 and
+KERNEL-ARG-01 diagnostics, legacy heuristic path for schema-less commands).</purpose>
+<non-goals>
+  <item>Do not test bin/cli.ts dispatch — these tests cover pure functions only.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>Initial cli-flags resolution tests — covers the `forge rfc.validate --id` crash regression (value-less declared string flag must produce KERNEL-FLAG-02, not a boolean).</item>
+</CHANGE_SUMMARY>
+*/
+
+import { describe, expect, test } from "vitest";
+import { parseCliArgs, resolveCliFlags } from "../cli-flags.ts";
+import type { ForgeCommandDefinition, ForgeFlagSpec } from "../types.ts";
+
+function command(flags?: Record<string, ForgeFlagSpec>): ForgeCommandDefinition {
+  return {
+    name: "test.command",
+    description: "test command",
+    scope: "workspace",
+    flags,
+    execute: () => {},
+  };
+}
+
+const errorRuleIds = (diagnostics: { ruleId: string; severity: string }[]) =>
+  diagnostics.filter((d) => d.severity === "error").map((d) => d.ruleId);
+
+describe("resolveCliFlags — strict (schema-carrying) path", () => {
+  const rfcValidate = command({
+    id: { kind: "string", description: "Target a single RFC by id." },
+  });
+
+  test("value-less declared string flag errors with KERNEL-FLAG-02 instead of becoming `true`", () => {
+    const { flags, diagnostics } = resolveCliFlags(["--id"], rfcValidate);
+    expect(flags["id"]).toBeUndefined();
+    expect(errorRuleIds(diagnostics)).toEqual(["KERNEL-FLAG-02"]);
+    expect(diagnostics[0]!.message).toContain('Flag "--id"');
+    expect(diagnostics[0]!.message).toContain('"test.command"');
+  });
+
+  test("value-less declared string flag before another flag still errors", () => {
+    const { flags, diagnostics } = resolveCliFlags(["--id", "--json"], rfcValidate);
+    expect(flags["id"]).toBeUndefined();
+    expect(flags["json"]).toBe(true);
+    expect(errorRuleIds(diagnostics)).toEqual(["KERNEL-FLAG-02"]);
+  });
+
+  test("--id <value> and --id=<value> resolve to the string", () => {
+    for (const argv of [["--id", "RFC-0609"], ["--id=RFC-0609"]]) {
+      const { flags, diagnostics } = resolveCliFlags(argv, rfcValidate);
+      expect(flags["id"]).toBe("RFC-0609");
+      expect(errorRuleIds(diagnostics)).toEqual([]);
+    }
+  });
+
+  test("inline value containing = is preserved verbatim", () => {
+    const { flags, diagnostics } = resolveCliFlags(["--id=RFC=0609"], rfcValidate);
+    expect(flags["id"]).toBe("RFC=0609");
+    expect(errorRuleIds(diagnostics)).toEqual([]);
+  });
+
+  test("repeated single-value string flag errors instead of promoting to an array", () => {
+    const { flags, diagnostics } = resolveCliFlags(["--id", "RFC-1", "--id", "RFC-2"], rfcValidate);
+    expect(errorRuleIds(diagnostics)).toEqual(["KERNEL-FLAG-02"]);
+    expect(diagnostics[0]!.message).toContain("single value");
+    expect(flags["id"]).toEqual(["RFC-1", "RFC-2"]);
+  });
+
+  test("unknown flag errors with KERNEL-FLAG-01 listing valid flags", () => {
+    const { diagnostics } = resolveCliFlags(["--idd"], rfcValidate);
+    expect(errorRuleIds(diagnostics)).toEqual(["KERNEL-FLAG-01"]);
+    expect(diagnostics[0]!.message).toContain("id");
+  });
+
+  test("unknown flag followed by a bare token also flags the token as positional", () => {
+    const { diagnostics } = resolveCliFlags(["--idd", "RFC-1"], rfcValidate);
+    expect(errorRuleIds(diagnostics)).toEqual(["KERNEL-FLAG-01", "KERNEL-ARG-01"]);
+  });
+
+  test("required flag missing errors with KERNEL-FLAG-03", () => {
+    const cmd = command({
+      name: { kind: "string", required: true, description: "Required name." },
+    });
+    const { diagnostics } = resolveCliFlags([], cmd);
+    expect(errorRuleIds(diagnostics)).toEqual(["KERNEL-FLAG-03"]);
+  });
+
+  test("declared default applies when flag absent", () => {
+    const cmd = command({
+      mode: { kind: "string", default: "all", description: "Mode." },
+    });
+    const { flags, diagnostics } = resolveCliFlags([], cmd);
+    expect(flags["mode"]).toBe("all");
+    expect(errorRuleIds(diagnostics)).toEqual([]);
+  });
+
+  test("positional token errors with KERNEL-ARG-01", () => {
+    const { diagnostics } = resolveCliFlags(["RFC-0609"], rfcValidate);
+    expect(errorRuleIds(diagnostics)).toEqual(["KERNEL-ARG-01"]);
+  });
+
+  test("tokens after -- are positional errors", () => {
+    const { diagnostics } = resolveCliFlags(["--id", "RFC-1", "--", "extra"], rfcValidate);
+    expect(errorRuleIds(diagnostics)).toEqual(["KERNEL-ARG-01"]);
+  });
+
+  test("universal flags accepted on commands with empty schema", () => {
+    const { flags, diagnostics } = resolveCliFlags(
+      ["--json", "--dry-run", "--help", "--site", "x"],
+      command({}),
+    );
+    expect(flags["json"]).toBe(true);
+    expect(flags["dry-run"]).toBe(true);
+    expect(flags["help"]).toBe(true);
+    expect(flags["site"]).toBe("x");
+    expect(errorRuleIds(diagnostics)).toEqual([]);
+  });
+
+  test("universal boolean does not swallow the next flag's token", () => {
+    const cmd = command({ fix: { kind: "boolean", description: "Fix." } });
+    const { flags, diagnostics } = resolveCliFlags(["--json", "--fix"], cmd);
+    expect(flags["json"]).toBe(true);
+    expect(flags["fix"]).toBe(true);
+    expect(errorRuleIds(diagnostics)).toEqual([]);
+  });
+
+  test("--flag=false on a declared boolean resolves to false", () => {
+    const cmd = command({ fix: { kind: "boolean", description: "Fix." } });
+    const { flags, diagnostics } = resolveCliFlags(["--fix=false"], cmd);
+    expect(flags["fix"]).toBe(false);
+    expect(errorRuleIds(diagnostics)).toEqual([]);
+  });
+
+  test("string[] flag collects repeated values", () => {
+    const cmd = command({
+      files: { kind: "string[]", description: "Files." },
+    });
+    const { flags, diagnostics } = resolveCliFlags(["--files", "a", "--files", "b"], cmd);
+    expect(flags["files"]).toEqual(["a", "b"]);
+    expect(errorRuleIds(diagnostics)).toEqual([]);
+  });
+});
+
+describe("resolveCliFlags — legacy (schema-less) path", () => {
+  const schemaLess = command(undefined);
+
+  test("unknown flags still parse heuristically", () => {
+    const { flags, diagnostics } = resolveCliFlags(["--anything", "v"], schemaLess);
+    expect(flags["anything"]).toBe("v");
+    expect(errorRuleIds(diagnostics)).toEqual([]);
+  });
+
+  test("known boolean switches do not consume the next token", () => {
+    const { flags } = resolveCliFlags(["--json", "v"], schemaLess);
+    expect(flags["json"]).toBe(true);
+  });
+
+  test("positional token errors with KERNEL-ARG-01", () => {
+    const { diagnostics } = resolveCliFlags(["positional"], schemaLess);
+    expect(errorRuleIds(diagnostics)).toEqual(["KERNEL-ARG-01"]);
+  });
+});
+
+describe("parseCliArgs", () => {
+  test("--key=value and --key value forms both resolve", () => {
+    const { flags } = parseCliArgs(["--a=1", "--b", "2", "--json"]);
+    expect(flags["a"]).toBe("1");
+    expect(flags["b"]).toBe("2");
+    expect(flags["json"]).toBe(true);
+  });
+});