@warpgogol/forge 5.1.0 → 5.1.2

package/src/config/forge-config.ts

@@ -197,7 +197,10 @@ export const forgeConfigSchema = z.object({
     })
     .optional(),
   /** RFC-0643: profile id — when present, loadForgeConfig loads the corresponding profiles/<id>.yaml */
-  profile: z.string().optional(),
+  // RFC-1118: accept the corrupted object form (whole StackProfile written by a
+  // previous buggy serialize) so loadForgeConfig can recover the declared id —
+  // a hard schema throw here would deadlock `forge upgrade`, the healing path.
+  profile: z.union([z.string(), z.object({ id: z.string().min(1) }).passthrough()]).optional(),
   /** RFC-0704: packages with autonomous npm versions — ecosystem.commit skips platform bump when all staged files belong to these packages */
   independentVersionPackages: z.array(z.string()).optional(),
 });
@@ -230,6 +233,10 @@ export interface ForgeConfig {
   forge?: { syncedVersion: string | null };
   /** RFC-0643: loaded stack profile — present when forge.yaml has a `profile` field */
   profile?: StackProfile;
+  /** RFC-1118: raw `profile:` id string from forge.yaml — preserved verbatim even when unresolvable */
+  profileDeclaredId?: string;
+  /** RFC-1118: resolution outcome for the declared `profile:` id */
+  profileResolution?: "resolved" | "unknown" | "absent" | "catalog-unavailable";
   /** RFC-0704: packages with autonomous npm versions — ecosystem.commit skips platform bump when all staged files belong to these packages */
   independentVersionPackages?: string[];
 }
@@ -382,21 +389,45 @@ export function loadForgeConfig(workspaceRoot: string, forgeRootOverride?: strin
   }
 
   const rawData = result.data as Record<string, unknown>;
-  const profileId = rawData["profile"] as string | undefined;
+  // RFC-1118: recover the declared id even when a previous buggy serialize wrote
+  // the whole StackProfile object into forge.yaml (object with an `id` field).
+  const rawProfile = rawData["profile"];
+  const profileId =
+    typeof rawProfile === "string"
+      ? rawProfile
+      : rawProfile && typeof rawProfile === "object" && "id" in rawProfile
+        ? String((rawProfile as { id: unknown }).id)
+        : undefined;
 
   // RFC-0643: load stack profile when `profile` field is present in forge.yaml
   let loadedProfile: StackProfile | undefined;
+  let catalogAvailable = false;
   if (profileId) {
     try {
       const forgeRoot = forgeRootOverride ?? resolveForgeRoot(workspaceRoot);
-      const profiles = listStackProfiles(forgeRoot);
-      loadedProfile = profiles.find((p) => p.id === profileId);
+      // RFC-1118: listStackProfiles returns [] on a missing profiles/ dir — an
+      // unreadable catalog (forge not installed, fallback path) must surface as
+      // "catalog-unavailable", not "unknown" (which would fail doctor spuriously).
+      if (fs.existsSync(path.join(forgeRoot, "profiles"))) {
+        const profiles = listStackProfiles(forgeRoot);
+        catalogAvailable = true;
+        loadedProfile = profiles.find((p) => p.id === profileId);
+      }
     } catch {
-      // forge root not resolvable — profile not loaded
+      // forge root not resolvable — catalog unavailable, resolvability undetermined
     }
   }
 
   const config = { ...rawData } as unknown as ForgeConfig;
+  // RFC-1118: preserve the declared id and its resolution status — never silently drop it
+  config.profileDeclaredId = profileId;
+  config.profileResolution = !profileId
+    ? "absent"
+    : loadedProfile
+      ? "resolved"
+      : catalogAvailable
+        ? "unknown"
+        : "catalog-unavailable";
   if (loadedProfile) {
     config.profile = loadedProfile;
   } else {
@@ -406,6 +437,29 @@ export function loadForgeConfig(workspaceRoot: string, forgeRootOverride?: strin
   return config;
 }
 
+// ---------------------------------------------------------------------------
+// Serializer — RFC-1118: forge.yaml stores the declared profile id (string),
+// never the resolved StackProfile object, and never drops a declared id.
+// ---------------------------------------------------------------------------
+
+export function serializeForgeConfig(config: ForgeConfig): Record<string, unknown> {
+  const out = { ...config } as unknown as Record<string, unknown>;
+  // Runtime-only fields must not be persisted
+  delete out["profileDeclaredId"];
+  delete out["profileResolution"];
+  // Prefer the preserved declared id; fall back to a raw string `profile`
+  // (hand-built configs that never went through loadForgeConfig).
+  const declared =
+    config.profileDeclaredId ??
+    (typeof config.profile === "string" ? (config.profile as unknown as string) : undefined);
+  if (declared) {
+    out["profile"] = declared;
+  } else {
+    delete out["profile"];
+  }
+  return out;
+}
+
 // ---------------------------------------------------------------------------
 // Forge root resolver — the single place that decides monorepo vs npm-installed
 // ---------------------------------------------------------------------------
@@ -433,6 +487,30 @@ export function resolveForgeRoot(workspaceRoot: string): string {
   );
 }
 
+/**
+ * Resolve the forge package root from inside the package's own modules.
+ * Handles both source layout (`src/<dir>/` → package root is two levels up)
+ * and compiled layout (`dist/src/<dir>/` → package root is three levels up)
+ * by walking up from `startDir` until a `package.json` is found.
+ *
+ * Use this for resolving package-shipped assets (templates, profiles) —
+ * `src/` and `profiles/` are both listed in package.json `files`, so they
+ * exist at the package root in the published tarball even though `tsc`
+ * never copies them into `dist/`.
+ */
+export function resolveForgePackageRoot(startDir: string): string {
+  let dir = startDir;
+  for (let i = 0; i < 6; i += 1) {
+    if (fs.existsSync(path.join(dir, "package.json"))) {
+      return dir;
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return startDir;
+}
+
 // ---------------------------------------------------------------------------
 // Binding resolver — RFC-0393
 // ---------------------------------------------------------------------------

package/src/onboarding/agents-generate.ts

@@ -23,7 +23,7 @@ Sweep batch 2: real KEY_DECISIONS on 10 files, expanded purposes (CONTRACT-02/PU
 import fs from "node:fs";
 import path from "node:path";
 import { parse as parseYaml } from "yaml";
-import { loadForgeConfig, resolveBinding, resolveForgeRoot } from "../config/forge-config.ts";
+import { loadForgeConfig, resolveBinding, resolveForgePackageRoot, resolveForgeRoot } from "../config/forge-config.ts";
 import { resolveAllTerminology } from "../profiles/terminology-utils.ts";
 import { FORGE_SKILLS } from "../registry.ts";
 import { buildGeneratedHeader, hasGeneratedMarker, writeFileIfChanged } from "../utils/index.ts";
@@ -58,13 +58,22 @@ export interface TemplateContext {
   workspaceType?: string;
 }
 
-// RFC-0643: Root template paths
-const BUSINESS_ROOT_TEMPLATE = path.join(import.meta.dirname, "templates", "root-agents-business.md");
-const CREATIVE_ROOT_TEMPLATE = path.join(import.meta.dirname, "templates", "root-agents-creative.md");
+// RFC-0643: Root template paths.
+// Templates ship in the tarball under src/onboarding/templates/ but tsc never
+// copies .md files into dist/ — resolve via the package root so both the source
+// layout (src/onboarding/) and compiled layout (dist/src/onboarding/) work.
+const TEMPLATES_DIR = path.join(
+  resolveForgePackageRoot(import.meta.dirname),
+  "src",
+  "onboarding",
+  "templates",
+);
+const BUSINESS_ROOT_TEMPLATE = path.join(TEMPLATES_DIR, "root-agents-business.md");
+const CREATIVE_ROOT_TEMPLATE = path.join(TEMPLATES_DIR, "root-agents-creative.md");
 
 // Behavioral layer template paths
-const BEHAVIORAL_LAYER_CORE_TEMPLATE = path.join(import.meta.dirname, "templates", "behavioral-layer-core.md");
-const BEHAVIORAL_LAYER_EXTENDED_TEMPLATE = path.join(import.meta.dirname, "templates", "behavioral-layer-extended.md");
+const BEHAVIORAL_LAYER_CORE_TEMPLATE = path.join(TEMPLATES_DIR, "behavioral-layer-core.md");
+const BEHAVIORAL_LAYER_EXTENDED_TEMPLATE = path.join(TEMPLATES_DIR, "behavioral-layer-extended.md");
 
 export function selectRootTemplate(
   register: BehavioralRegister,
@@ -75,7 +84,7 @@ export function selectRootTemplate(
     const templateRel = profile.rootAgentsMdTemplate;
     // Path traversal guard: reject absolute paths and ..
     if (!path.isAbsolute(templateRel) && !templateRel.includes("..")) {
-      const forgeRoot = path.resolve(import.meta.dirname, "..", "..");
+      const forgeRoot = resolveForgePackageRoot(import.meta.dirname);
       const profilesDir = path.join(forgeRoot, "profiles");
       const templatePath = path.resolve(profilesDir, templateRel);
       // Ensure resolved path is within profiles directory

package/src/onboarding/create.ts

@@ -32,6 +32,7 @@ import { runAgentsGenerate } from "./agents-generate.ts";
 import { scaffoldMemoryLayer } from "./memory-scaffold.ts";
 import {
   loadForgeConfig,
+  serializeForgeConfig,
   resolveForgeRoot,
   resolvePackageManager,
   applyCliBindingDefaults,
@@ -348,13 +349,9 @@ export async function runCreate(
         if (config.bindings) {
           config.bindings.commands = applyCliBindingDefaults(pm);
         }
-        // RFC-0643: strip loaded profile object before serializing — forge.yaml stores profile id (string), not the full profile
-        const configToSerialize = { ...config } as unknown as Record<string, unknown>;
-        if (typeof configToSerialize["profile"] === "object") {
-          const profileObj = configToSerialize["profile"] as { id?: string };
-          configToSerialize["profile"] = profileObj.id ?? configToSerialize["profile"];
-        }
-        fs.writeFileSync(forgeYamlPath, stringifyYaml(configToSerialize), "utf8");
+        // RFC-1118: serializeForgeConfig writes the declared profile id verbatim —
+        // never the resolved StackProfile object, never drops an unresolvable id.
+        fs.writeFileSync(forgeYamlPath, stringifyYaml(serializeForgeConfig(config)), "utf8");
       } catch {
         // Post-processing is best-effort — init already wrote a valid config
       }

package/src/onboarding/doctor.ts

@@ -50,6 +50,7 @@ import { checkMemoryLayerHealth } from "./memory-scaffold.ts";
 import { checkInvariants } from "./invariant-engine.ts";
 import type { InvariantViolation } from "./invariant-engine.ts";
 import { execSync } from "node:child_process";
+import fs from "node:fs";
 import type { ProfilePrerequisite } from "../profiles/profile-schema.ts";
 
 interface DoctorCheck {
@@ -1023,6 +1024,72 @@ function checkDomainInfo(domainReport: DomainReport): DoctorCheck {
   };
 }
 
+// RFC-1118: fail-closed diagnostic for an unresolvable `profile:` id.
+// A declared id absent from the installed catalog is a hard failure —
+// never silently dropped. An unreadable catalog is a warning, not a fail.
+function checkProfileIdKnown(workspaceRoot: string, forgeRoot: string): DoctorCheck {
+  const forgeYamlPath = join(workspaceRoot, "forge.yaml");
+  if (!fs.existsSync(forgeYamlPath)) {
+    return {
+      name: "profile-id-known",
+      status: "pass",
+      message: "no forge.yaml — nothing to resolve",
+    };
+  }
+  let config: ReturnType<typeof loadForgeConfig>;
+  try {
+    config = loadForgeConfig(workspaceRoot, forgeRoot);
+  } catch (err) {
+    // forge.yaml exists but is unreadable/schema-invalid — a real defect, fail-closed
+    return {
+      name: "profile-id-known",
+      status: "fail",
+      message: `forge.yaml unreadable: ${(err as Error).message.split("\n")[0]}`,
+    };
+  }
+
+  switch (config.profileResolution) {
+    case "unknown": {
+      let version = "unknown";
+      try {
+        const pkg = JSON.parse(fs.readFileSync(join(forgeRoot, "package.json"), "utf8")) as {
+          version?: string;
+        };
+        version = pkg.version ?? "unknown";
+      } catch {
+        // version unreadable — message still names the declared id
+      }
+      return {
+        name: "profile-id-known",
+        status: "fail",
+        message:
+          `profile "${config.profileDeclaredId}" not in installed @warpgogol/forge v${version} catalog — ` +
+          `renamed/removed id or forge upgrade required`,
+      };
+    }
+    case "catalog-unavailable":
+      return {
+        name: "profile-id-known",
+        status: "warn",
+        message:
+          `profile "${config.profileDeclaredId}" declared but the installed profile catalog cannot be read ` +
+          `(forge root unresolvable) — resolvability undetermined`,
+      };
+    case "resolved":
+      return {
+        name: "profile-id-known",
+        status: "pass",
+        message: `profile "${config.profileDeclaredId}" resolved`,
+      };
+    default:
+      return {
+        name: "profile-id-known",
+        status: "pass",
+        message: "no profile declared",
+      };
+  }
+}
+
 // RFC-0664: Memory layer health check
 function checkMemoryLayer(workspaceRoot: string): DoctorCheck {
   const health = checkMemoryLayerHealth(workspaceRoot);
@@ -1222,6 +1289,9 @@ export async function runDoctor(
   // RFC-0640: Domain info check
   checks.push(checkDomainInfo(domainReport));
 
+  // RFC-1118: profile identity check — fail-closed on unresolvable declared id
+  checks.push(checkProfileIdKnown(workspaceRoot, forgeRoot));
+
   // RFC-0675: Enforce invariants using the invariant engine
   if (domainReport.invariants.length > 0) {
     const profiles = listStackProfiles(forgeRoot);

package/src/onboarding/init.ts

@@ -60,7 +60,11 @@ export function runInit(
   context: unknown,
   domainFields?: InitDomainFields,
 ): InitResult {
-  const ctx = context as { workspaceRoot?: string; forgeRoot?: string };
+  const ctx = context as {
+    workspaceRoot?: string;
+    forgeRoot?: string;
+    logger?: { warn?: (msg: string) => void };
+  };
   const workspaceRoot = ctx?.workspaceRoot ?? process.cwd();
   const contextForgeRoot = ctx?.forgeRoot;
 
@@ -115,6 +119,20 @@ export function runInit(
     } catch {
       config = defaultForgeConfig(path.basename(workspaceRoot));
     }
+    // RFC-1118: a declared `profile:` is never overwritten by re-detection.
+    // If --from detection disagrees with the declared id, surface a warning —
+    // the declared id stays verbatim in forge.yaml.
+    if (
+      detection?.profile &&
+      config.profileDeclaredId &&
+      detection.profile !== config.profileDeclaredId
+    ) {
+      const msg =
+        `profile: declared id "${config.profileDeclaredId}" preserved — ` +
+        `detected "${detection.profile}" not written (forge.yaml already exists)`;
+      skipped.push(msg);
+      ctx?.logger?.warn?.(msg);
+    }
   } else {
     const projectName = path.basename(workspaceRoot);
     config = defaultForgeConfig(projectName);

package/src/onboarding/nested-agents-templates.ts

@@ -20,6 +20,7 @@ Sweep batch 4: 73 Compass headers on headerless engine files (certification, com
 */
 
 import { buildGeneratedHeader } from "../utils/index.ts";
+import { resolveForgePackageRoot } from "../config/forge-config.ts";
 import type { ForgeConfig } from "../config/forge-config.ts";
 import type { WorkspaceDir, WorkspaceType } from "./workspace-discovery.ts";
 import type { ProfileWorkspaceType } from "../profiles/profile-schema.ts";
@@ -151,8 +152,10 @@ export function selectNestedTemplate(
     return fallback;
   }
 
-  // Resolve relative to profiles/ directory (where profile YAMLs live)
-  const forgeRoot = path.resolve(import.meta.dirname, "..", "..");
+  // Resolve relative to profiles/ directory (where profile YAMLs live).
+  // import.meta.dirname points at dist/src/onboarding/ in the compiled package —
+  // resolve the package root so profiles/ is found in both src and dist layouts.
+  const forgeRoot = resolveForgePackageRoot(import.meta.dirname);
   const profilesDir = path.join(forgeRoot, "profiles");
   const templatePath = path.resolve(profilesDir, templateRel);
 

package/src/onboarding/upgrade.ts

@@ -32,6 +32,7 @@ import {
   FORGE_CLI_BINDING_DEFAULTS,
   resolveForgeRoot,
   loadForgeConfig,
+  serializeForgeConfig,
   resolvePmRunner,
   resolvePmInstall,
   type ForgeConfig,
@@ -311,8 +312,10 @@ function updateSyncedVersion(
   config.forge = { syncedVersion: version };
 
   // Write the full config back to forge.yaml
+  // RFC-1118: serializeForgeConfig writes the declared profile id verbatim —
+  // never the resolved StackProfile object, never drops an unresolvable id.
   const forgeYamlPath = path.join(workspaceRoot, "forge.yaml");
-  fs.writeFileSync(forgeYamlPath, stringifyYaml(config), "utf8");
+  fs.writeFileSync(forgeYamlPath, stringifyYaml(serializeForgeConfig(config)), "utf8");
 }
 
 export async function runUpgrade(

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

@@ -147,7 +147,7 @@ test("creative template contains {{dynamicSections}} marker", () => {
 
 test("selectRootTemplate with profile rootAgentsMdTemplate loads profile template", () => {
   const profile = {
-    id: "godot-csharp",
+    id: "godot-game",
     rootAgentsMdTemplate: "root-agents-godot.md",
   } as StackProfile;
   const content = selectRootTemplate("creative", profile);
@@ -301,8 +301,8 @@ test("agents-generate with creative register uses creative template", async () =
   expect(rootDetail?.register).toBe("creative");
 });
 
-test("agents-generate with godot-csharp profile generates Godot-specific AGENTS.md", async () => {
-  await makeForgeYaml(tempDir, "profile: godot-csharp");
+test("agents-generate with godot-game profile generates Godot-specific AGENTS.md", async () => {
+  await makeForgeYaml(tempDir, "profile: godot-game");
   const ctx = makeContext(tempDir);
   ctx.dryRun = true;
 

package/src/tests/create.test.ts

@@ -290,9 +290,9 @@ test("forge create --in-place derives name from folder name when --name omitted"
   expect(pkgJson.name).toBe("my-derived-project");
 }, 120000);
 
-test("forge create --profile godot-csharp writes compass.fileExtensions into forge.yaml", async () => {
+test("forge create --profile godot-game writes compass.fileExtensions into forge.yaml", async () => {
   const result = await runCreate(
-    { argv: [], flags: { "in-place": true, profile: "godot-csharp", name: "my-game" } },
+    { argv: [], flags: { "in-place": true, profile: "godot-game", name: "my-game" } },
     makeContext(tempDir),
   );
   expect(result.exitCode).toBe(0);
@@ -346,9 +346,9 @@ test("forge create --in-place pins pre-user-prompt-wrapper.mjs in pinned.yaml (R
   expect(pinnedYaml).toContain("pre-user-prompt-wrapper.mjs");
 }, 120000);
 
-test("forge create --profile phaser-turborepo writes compass.fileExtensions into forge.yaml", async () => {
+test("forge create --profile phaser-game writes compass.fileExtensions into forge.yaml", async () => {
   const result = await runCreate(
-    { argv: [], flags: { "in-place": true, profile: "phaser-turborepo", name: "my-phaser-game" } },
+    { argv: [], flags: { "in-place": true, profile: "phaser-game", name: "my-phaser-game" } },
     makeContext(tempDir),
   );
   expect(result.exitCode).toBe(0);

package/src/tests/doctor-profile-id-known.test.ts

@@ -0,0 +1,237 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Unit tests for RFC-1118 fail-closed handling of unresolvable forge.yaml profile id — profile-id-known doctor check, declared-id preservation, serializeForgeConfig, init re-detect guard.</purpose>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-1118: initial tests — AC-1..AC-8 plus corrupted-object recovery.</item>
+</CHANGE_SUMMARY>
+*/
+
+import { test, expect, beforeEach, afterEach } from "vitest";
+import { mkdtemp, rm, mkdir, writeFile, readFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { parse as parseYaml } from "yaml";
+import { runDoctor } from "../onboarding/doctor.ts";
+import { runUpgrade } from "../onboarding/upgrade.ts";
+import { runInit } from "../onboarding/init.ts";
+import { loadForgeConfig, serializeForgeConfig } from "../config/forge-config.ts";
+import type { ForgeCommandInput, ForgeRuntimeContext } from "../types.ts";
+
+let tempDir: string;
+
+beforeEach(async () => {
+  tempDir = await mkdtemp(join(tmpdir(), "doctor-profile-id-known-"));
+});
+
+afterEach(async () => {
+  await rm(tempDir, { recursive: true, force: true });
+});
+
+function makeContext(): ForgeRuntimeContext {
+  return {
+    workspaceRoot: tempDir,
+    logger: {
+      section: () => {},
+      success: () => {},
+      warn: () => {},
+      error: () => {},
+      info: () => {},
+    },
+    dryRun: false,
+    outputFormat: "json",
+  };
+}
+
+const FORGE_YAML_BASE = `schema: "forge/config@1"
+project:
+  name: test-project
+  stack: []
+  packageManager: pnpm
+paths:
+  rfcsDir: docs/rfcs
+  adrsDir: docs/adrs
+  plansDir: docs/plans
+  auditsDir: docs/audits
+  specsDir: docs/specs
+  skillsDir: .agents/skills
+  sessionsDir: docs/sessions
+`;
+
+async function writeForgeYaml(extra = ""): Promise<void> {
+  await writeFile(join(tempDir, "forge.yaml"), FORGE_YAML_BASE + extra, "utf8");
+}
+
+function minimalProfile(id: string, marker: string): string {
+  return `schema: forge/stack-profile@1
+id: ${id}
+displayName: ${id} profile
+detect:
+  anyOf:
+    - ${marker}
+workspace:
+  dirs:
+    - docs
+  files: []
+`;
+}
+
+// A fake installed forge: packages/forge/package.json + profiles/<id>.yaml.
+// resolveForgeRoot(workspaceRoot) picks it up via the monorepo path.
+async function writeFakeForgeRoot(
+  version: string,
+  profiles: Array<{ id: string; marker: string }>,
+): Promise<string> {
+  const forgeRoot = join(tempDir, "packages", "forge");
+  await mkdir(join(forgeRoot, "profiles"), { recursive: true });
+  await writeFile(
+    join(forgeRoot, "package.json"),
+    JSON.stringify({ name: "@warpgogol/forge", version }) + "\n",
+    "utf8",
+  );
+  for (const p of profiles) {
+    await writeFile(
+      join(forgeRoot, "profiles", `${p.id}.yaml`),
+      minimalProfile(p.id, p.marker),
+      "utf8",
+    );
+  }
+  return forgeRoot;
+}
+
+function findCheck(result: Awaited<ReturnType<typeof runDoctor>>, name: string) {
+  return result.data?.checks.find((c) => c.name === name);
+}
+
+// AC-1: unresolvable declared id → profile-id-known fails, names id + version
+test("doctor fails profile-id-known when declared profile id is absent from installed catalog", async () => {
+  await writeFakeForgeRoot("9.9.9", [{ id: "known-profile", marker: "marker-known.txt" }]);
+  await writeForgeYaml(`profile: bogus-id\n`);
+
+  const input: ForgeCommandInput = { argv: [], flags: {} };
+  const result = await runDoctor(input, makeContext());
+
+  const check = findCheck(result, "profile-id-known");
+  expect(check, "profile-id-known check must exist in doctor output").toBeDefined();
+  expect(check!.status).toBe("fail");
+  expect(check!.message).toContain("bogus-id");
+  expect(check!.message).toContain("9.9.9");
+  expect(result.exitCode).toBe(1);
+});
+
+// AC-2: ForgeConfig exposes profileDeclaredId + profileResolution
+test("loadForgeConfig exposes profileDeclaredId and profileResolution", async () => {
+  await writeFakeForgeRoot("9.9.9", [{ id: "known-profile", marker: "marker-known.txt" }]);
+  await writeForgeYaml(`profile: bogus-id\n`);
+
+  const config = loadForgeConfig(tempDir);
+  expect(config.profileDeclaredId).toBe("bogus-id");
+  expect(config.profileResolution).toBe("unknown");
+  expect(config.profile).toBeUndefined();
+});
+
+// AC-3: no profile field → pass
+test("doctor passes profile-id-known when no profile is declared", async () => {
+  await writeFakeForgeRoot("9.9.9", [{ id: "known-profile", marker: "marker-known.txt" }]);
+  await writeForgeYaml();
+
+  const input: ForgeCommandInput = { argv: [], flags: {} };
+  const result = await runDoctor(input, makeContext());
+
+  const check = findCheck(result, "profile-id-known");
+  expect(check!.status).toBe("pass");
+});
+
+// AC-4: unresolvable id survives re-serialization verbatim
+test("forge upgrade preserves an unresolvable declared profile id verbatim", async () => {
+  const forgeRoot = await writeFakeForgeRoot("9.9.9", [
+    { id: "known-profile", marker: "marker-known.txt" },
+  ]);
+  await writeForgeYaml(`profile: bogus-id\nforge:\n  syncedVersion: "0.0.0"\n`);
+
+  const input: ForgeCommandInput = { argv: [], flags: {} };
+  const ctx = { ...makeContext(), forgeRoot };
+  const result = await runUpgrade(input, ctx);
+  expect(result.exitCode).toBe(0);
+
+  const written = parseYaml(await readFile(join(tempDir, "forge.yaml"), "utf8")) as Record<
+    string,
+    unknown
+  >;
+  expect(
+    written["profile"],
+    "re-serialized forge.yaml must retain the declared id string, not drop it",
+  ).toBe("bogus-id");
+});
+
+// AC-6: resolvable id serializes as the id string, not the StackProfile object
+test("forge upgrade writes the profile id string, not the resolved object", async () => {
+  const forgeRoot = await writeFakeForgeRoot("9.9.9", [
+    { id: "known-profile", marker: "marker-known.txt" },
+  ]);
+  await writeForgeYaml(`profile: known-profile\nforge:\n  syncedVersion: "0.0.0"\n`);
+
+  const input: ForgeCommandInput = { argv: [], flags: {} };
+  const ctx = { ...makeContext(), forgeRoot };
+  const result = await runUpgrade(input, ctx);
+  expect(result.exitCode).toBe(0);
+
+  const written = parseYaml(await readFile(join(tempDir, "forge.yaml"), "utf8")) as Record<
+    string,
+    unknown
+  >;
+  expect(
+    typeof written["profile"],
+    "profile must serialize as the declared id string, not the StackProfile object",
+  ).toBe("string");
+  expect(written["profile"]).toBe("known-profile");
+});
+
+// AC-7: unreadable catalog → warn, not fail
+test("doctor warns (not fails) when the profile catalog cannot be read", async () => {
+  // No fake forge root — resolveForgeRoot falls back to a nonexistent path.
+  await writeForgeYaml(`profile: bogus-id\n`);
+
+  const input: ForgeCommandInput = { argv: [], flags: {} };
+  const result = await runDoctor(input, makeContext());
+
+  const check = findCheck(result, "profile-id-known");
+  expect(check!.status).toBe("warn");
+  expect(check!.message).toContain("bogus-id");
+});
+
+// AC-8: init --from never overwrites a declared profile id
+test("forge init preserves a declared profile id against conflicting detection", async () => {
+  const forgeRoot = await writeFakeForgeRoot("9.9.9", [
+    { id: "detected-y", marker: "marker-y.txt" },
+  ]);
+  await writeForgeYaml(`profile: declared-x\n`);
+
+  // --from directory that detects as "detected-y"
+  const fromDir = join(tempDir, "from-src");
+  await mkdir(fromDir, { recursive: true });
+  await writeFile(join(fromDir, "marker-y.txt"), "x", "utf8");
+
+  const result = runInit({ flags: { from: fromDir } }, { workspaceRoot: tempDir, forgeRoot });
+
+  const written = await readFile(join(tempDir, "forge.yaml"), "utf8");
+  expect(written).toContain("profile: declared-x");
+  expect(
+    result.skipped.some((s) => s.includes("declared-x") && s.includes("detected-y")),
+    "init must surface a warning that the declared id was preserved over the detection result",
+  ).toBe(true);
+});
+
+// Corrupted state recovery: object-form profile (written by the old bug) heals to the declared id
+test("loadForgeConfig recovers profileDeclaredId from a corrupted object-form profile", async () => {
+  await writeFakeForgeRoot("9.9.9", [{ id: "known-profile", marker: "marker-known.txt" }]);
+  await writeForgeYaml(`profile:\n  id: known-profile\n  displayName: known-profile profile\n`);
+
+  const config = loadForgeConfig(tempDir);
+  expect(config.profileDeclaredId).toBe("known-profile");
+  expect(config.profileResolution).toBe("resolved");
+
+  // Re-serialization heals the field back to the id string
+  const serialized = serializeForgeConfig(config);
+  expect(serialized["profile"]).toBe("known-profile");
+});