@warpgogol/forge 5.1.1 → 5.1.3

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
 // ---------------------------------------------------------------------------

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,
@@ -93,6 +94,9 @@ function loadProfileDomainFields(profileId: string, forgeRoot: string): InitDoma
     if (profile.compass) {
       fields.compass = profile.compass;
     }
+    if (profile.nextSteps) {
+      fields.nextSteps = profile.nextSteps;
+    }
     return fields;
   } catch {
     return {};
@@ -348,13 +352,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
       }
@@ -387,9 +387,9 @@ export async function runCreate(
     }
   }
 
-  // 13. Write NEXT_STEPS.md (RFC-0550)
+  // 13. Write NEXT_STEPS.md (RFC-0550); RFC-1125: profile may override via nextSteps field
   const nextStepsPath = path.join(targetDir, "NEXT_STEPS.md");
-  const nextStepsContent = `# Next Steps
+  const nextStepsContent = initDomainFields.nextSteps ?? `# Next Steps
 
 Your Forge project is ready. The next step is mandatory: run \`/forge-bootstrap\` to configure your project interactively.
 

package/src/onboarding/doctor-token-check.test.ts

@@ -0,0 +1,124 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Unit tests for the npm-token probe (RFC-1125, AC-2) — .npmrc parsing, token presence detection, and the fail-fast fixHint contract used by forge create and forge.doctor.</purpose>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-1125: initial npm-token probe tests (AC-2 evidence).</item>
+</CHANGE_SUMMARY>
+*/
+
+import { test, expect, beforeEach, afterEach } from "vitest";
+import { mkdtemp, writeFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  checkNpmToken,
+  readNpmrcTokenStatus,
+  workshopNeedsWarpgogolToken,
+} from "./npm-token-check.ts";
+
+let tempDir: string;
+
+beforeEach(async () => {
+  tempDir = await mkdtemp(join(tmpdir(), "npm-token-check-"));
+});
+
+afterEach(async () => {
+  await rm(tempDir, { recursive: true, force: true });
+});
+
+const NPMRC_WITH_TOKEN = `@warpgogol:registry=https://registry.npmjs.org/
+//registry.npmjs.org/:_authToken=npm_real_token_123
+`;
+
+const NPMRC_PLACEHOLDER = `@warpgogol:registry=https://registry.npmjs.org/
+//registry.npmjs.org/:_authToken=YOUR_NPM_TOKEN
+`;
+
+const NPMRC_ENV_REF = `@warpgogol:registry=https://registry.npmjs.org/
+//registry.npmjs.org/:_authToken=\${NPM_TOKEN}
+`;
+
+// --- readNpmrcTokenStatus ---
+
+test("detects registry and literal token from .npmrc", async () => {
+  await writeFile(join(tempDir, ".npmrc"), NPMRC_WITH_TOKEN);
+  const status = readNpmrcTokenStatus(tempDir, {});
+  expect(status.registry).toBe("https://registry.npmjs.org/");
+  expect(status.tokenPresent).toBe(true);
+});
+
+test("YOUR_NPM_TOKEN placeholder does not count as a token", async () => {
+  await writeFile(join(tempDir, ".npmrc"), NPMRC_PLACEHOLDER);
+  const status = readNpmrcTokenStatus(tempDir, {});
+  expect(status.tokenPresent).toBe(false);
+});
+
+test("NPM_TOKEN env satisfies the probe even with placeholder .npmrc", async () => {
+  await writeFile(join(tempDir, ".npmrc"), NPMRC_PLACEHOLDER);
+  const status = readNpmrcTokenStatus(tempDir, { NPM_TOKEN: "npm_env_token" });
+  expect(status.tokenPresent).toBe(true);
+});
+
+test("${NPM_TOKEN} reference resolves against env", async () => {
+  await writeFile(join(tempDir, ".npmrc"), NPMRC_ENV_REF);
+  expect(readNpmrcTokenStatus(tempDir, { NPM_TOKEN: "x" }).tokenPresent).toBe(true);
+  expect(readNpmrcTokenStatus(tempDir, {}).tokenPresent).toBe(false);
+});
+
+test("missing .npmrc → no registry, no token", () => {
+  const status = readNpmrcTokenStatus(tempDir, {});
+  expect(status.registry).toBeNull();
+  expect(status.tokenPresent).toBe(false);
+});
+
+test("detects _authToken when it is not the last line (scaffolded .npmrc shape)", async () => {
+  // Regression: scaffolded .npmrc appends dangerously-allow-all-builds and
+  // ignore-workspace-root-check AFTER the token line — the regex must match mid-file.
+  await writeFile(
+    join(tempDir, ".npmrc"),
+    `@warpgogol:registry=https://registry.npmjs.org/\n//registry.npmjs.org/:_authToken=npm_real_token\ndangerously-allow-all-builds=true\nignore-workspace-root-check=true\n`,
+  );
+  const status = readNpmrcTokenStatus(tempDir, {});
+  expect(status.tokenPresent).toBe(true);
+});
+
+// --- workshopNeedsWarpgogolToken ---
+
+test("needs token when .npmrc declares @warpgogol scope", async () => {
+  await writeFile(join(tempDir, ".npmrc"), NPMRC_PLACEHOLDER);
+  expect(workshopNeedsWarpgogolToken(tempDir, [])).toBe(true);
+});
+
+test("needs token when install pulls @warpgogol packages", () => {
+  expect(workshopNeedsWarpgogolToken(tempDir, ["pnpm add -wD @warpgogol/forge"])).toBe(true);
+});
+
+test("skips probe when no @warpgogol usage", () => {
+  expect(workshopNeedsWarpgogolToken(tempDir, ["pnpm add -wD prettier"])).toBe(false);
+});
+
+// --- checkNpmToken ---
+
+test("canFetch=true → fixHint is null", async () => {
+  await writeFile(join(tempDir, ".npmrc"), NPMRC_WITH_TOKEN);
+  const result = await checkNpmToken(tempDir, { fetchVersion: () => true, env: {} });
+  expect(result.canFetch).toBe(true);
+  expect(result.fixHint).toBeNull();
+});
+
+test("canFetch=false with token → fixHint mentions expiry/revocation", async () => {
+  await writeFile(join(tempDir, ".npmrc"), NPMRC_WITH_TOKEN);
+  const result = await checkNpmToken(tempDir, { fetchVersion: () => false, env: {} });
+  expect(result.canFetch).toBe(false);
+  expect(result.fixHint).toContain("expired or revoked");
+});
+
+test("canFetch=false without token → fixHint names NPM_TOKEN and .npmrc", async () => {
+  await writeFile(join(tempDir, ".npmrc"), NPMRC_PLACEHOLDER);
+  const result = await checkNpmToken(tempDir, { fetchVersion: () => false, env: {} });
+  expect(result.canFetch).toBe(false);
+  // AC-2: the fixHint must be actionable — name the exact remediation path
+  expect(result.fixHint).toContain("NPM_TOKEN");
+  expect(result.fixHint).toContain(".npmrc");
+});

package/src/onboarding/doctor.ts

@@ -49,7 +49,9 @@ import type { DuplicatePair } from "../knowledge/index.ts";
 import { checkMemoryLayerHealth } from "./memory-scaffold.ts";
 import { checkInvariants } from "./invariant-engine.ts";
 import type { InvariantViolation } from "./invariant-engine.ts";
+import { checkNpmToken, workshopNeedsWarpgogolToken } from "./npm-token-check.ts";
 import { execSync } from "node:child_process";
+import fs from "node:fs";
 import type { ProfilePrerequisite } from "../profiles/profile-schema.ts";
 
 interface DoctorCheck {
@@ -1023,6 +1025,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);
@@ -1205,6 +1273,22 @@ export async function runDoctor(
       : "docs/adrs/ directory not found — run 'forge create' to create ADR directory",
   });
 
+  // RFC-1125: re-verify the @warpgogol npm token post-install when the workshop
+  // uses the private scope (.npmrc declares it or package.json has @warpgogol deps)
+  const pkgJsonPath = join(workspaceRoot, "package.json");
+  const pkgHasWarpgogol =
+    fs.existsSync(pkgJsonPath) && fs.readFileSync(pkgJsonPath, "utf8").includes("@warpgogol/");
+  if (workshopNeedsWarpgogolToken(workspaceRoot, []) || pkgHasWarpgogol) {
+    const tokenCheck = await checkNpmToken(workspaceRoot);
+    checks.push({
+      name: "npm-token (@warpgogol)",
+      status: tokenCheck.canFetch ? "pass" : "fail",
+      message: tokenCheck.canFetch
+        ? `npm token fetches @warpgogol/werkstatt-engine (${tokenCheck.registry ?? "default registry"})`
+        : tokenCheck.fixHint!,
+    });
+  }
+
   // Check git branch is 'main' (not 'master')
   checks.push(checkGitBranch(workspaceRoot));
 
@@ -1222,6 +1306,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

@@ -49,6 +49,7 @@ export interface InitDomainFields {
   terminology?: Record<string, string>;
   semanticBindings?: Record<string, string | null>;
   profileId?: string;
+  nextSteps?: string;
   compass?: {
     fileExtensions?: string[];
     testPatterns?: string[];
@@ -60,7 +61,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 +120,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/npm-token-check.ts

@@ -0,0 +1,140 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Non-interactive npm-token probe for the private @warpgogol registry scope (RFC-1125) — parses .npmrc for the @warpgogol scope registry and auth token presence, probes the registry via `npm view @warpgogol/werkstatt-engine version` (injectable for tests) before pnpm install runs in forge create, re-verifies post-install in forge.doctor, and returns a structured NpmTokenCheck with an actionable fixHint on failure.</purpose>
+<non-goals>
+  <item>Do not prompt the operator — the probe is non-interactive (create.ts forbids prompts).</item>
+  <item>Do not accept tokens via CLI flags — tokens must not appear in argv/history.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-1125: initial npm-token probe — checkNpmToken + readNpmrcTokenStatus, wired into scaffold-project (pre-install fail-fast) and doctor (post-install re-verify).</item>
+</CHANGE_SUMMARY>
+*/
+
+import { execSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+
+/** Result of the npm-token probe (RFC-1125). */
+export interface NpmTokenCheck {
+  /** Registry URL from `.npmrc` `@warpgogol:registry=` (null when undeclared). */
+  registry: string | null;
+  /** A usable token is configured — NPM_TOKEN env or a real _authToken value. */
+  tokenPresent: boolean;
+  /** `npm view @warpgogol/werkstatt-engine version` succeeded from workspaceRoot. */
+  canFetch: boolean;
+  /** Actionable remediation when canFetch is false; null on success. */
+  fixHint: string | null;
+}
+
+/** Injectable dependencies for testing. */
+export interface NpmTokenProbeDeps {
+  /** Override the registry probe — return true when the fetch succeeds. */
+  fetchVersion?: (cwd: string) => boolean;
+  /** Override the environment (defaults to process.env). */
+  env?: Record<string, string | undefined>;
+}
+
+const WARPGOGOL_SCOPE = "@warpgogol";
+const PROBE_PACKAGE = "@warpgogol/werkstatt-engine";
+const PROBE_TIMEOUT_MS = 15_000;
+const PLACEHOLDER_TOKENS = new Set(["YOUR_NPM_TOKEN", ""]);
+
+/**
+ * Parse the workspace `.npmrc` for the @warpgogol scope: registry URL and
+ * whether a usable auth token is configured. A token counts as present when
+ * NPM_TOKEN is set in the env, or when `_authToken` holds a real value
+ * (not the YOUR_NPM_TOKEN placeholder, not an unset ${VAR} reference).
+ */
+export function readNpmrcTokenStatus(
+  workspaceRoot: string,
+  env: Record<string, string | undefined> = process.env,
+): { registry: string | null; tokenPresent: boolean } {
+  const npmrcPath = path.join(workspaceRoot, ".npmrc");
+  const npmrc = fs.existsSync(npmrcPath) ? fs.readFileSync(npmrcPath, "utf8") : "";
+
+  const registryMatch = npmrc.match(/^@warpgogol:registry=(\S+)\s*$/m);
+  const registry = registryMatch?.[1] ?? null;
+
+  // Token sources, in precedence order:
+  // 1. NPM_TOKEN env (agent-driven installs; also satisfies ${NPM_TOKEN} refs)
+  if (env.NPM_TOKEN && env.NPM_TOKEN.trim().length > 0) {
+    return { registry, tokenPresent: true };
+  }
+
+  // 2. Literal _authToken in .npmrc for the scope's registry host.
+  // `m` flag required — the token line is never last in a scaffolded .npmrc
+  // (dangerously-allow-all-builds + appended ignore-workspace-root-check follow it).
+  const tokenMatch = npmrc.match(/_authToken=(\S+)[ \t]*$/m);
+  if (tokenMatch) {
+    const value = tokenMatch[1];
+    // ${VAR} references resolve at install time — count as present only when set
+    const varRef = value.match(/^\$\{(\w+)\}$/);
+    if (varRef) {
+      const envValue = env[varRef[1]];
+      return { registry, tokenPresent: !!envValue && envValue.trim().length > 0 };
+    }
+    return { registry, tokenPresent: !PLACEHOLDER_TOKENS.has(value) };
+  }
+
+  return { registry, tokenPresent: false };
+}
+
+/**
+ * Whether the workspace needs the @warpgogol token at all — true when `.npmrc`
+ * declares the scope or any install command pulls `@warpgogol/` packages.
+ * Profiles without @warpgogol deps skip the probe entirely.
+ */
+export function workshopNeedsWarpgogolToken(workspaceRoot: string, installCmds: string[]): boolean {
+  const npmrcPath = path.join(workspaceRoot, ".npmrc");
+  if (fs.existsSync(npmrcPath)) {
+    const npmrc = fs.readFileSync(npmrcPath, "utf8");
+    if (npmrc.includes(`${WARPGOGOL_SCOPE}:registry`) || npmrc.includes(`${WARPGOGOL_SCOPE}/`)) {
+      return true;
+    }
+  }
+  return installCmds.some((cmd) => cmd.includes(`${WARPGOGOL_SCOPE}/`));
+}
+
+function defaultFetchVersion(cwd: string): boolean {
+  try {
+    execSync(`npm view ${PROBE_PACKAGE} version`, {
+      cwd,
+      stdio: "pipe",
+      timeout: PROBE_TIMEOUT_MS,
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function buildFixHint(tokenPresent: boolean): string {
+  const base =
+    `npm token for the @warpgogol scope cannot fetch ${PROBE_PACKAGE}. ` +
+    `Set NPM_TOKEN env or replace YOUR_NPM_TOKEN in .npmrc with a valid npm read token ` +
+    `(issued at workshop provisioning — see NEXT_STEPS.md §Token lifecycle).`;
+  return tokenPresent
+    ? `${base} A token is configured but was rejected — it may be expired or revoked; request a fresh one.`
+    : base;
+}
+
+/**
+ * Run the npm-token probe: parse `.npmrc`, then verify the registry actually
+ * serves the package. Non-interactive — never prompts, never reads argv.
+ */
+export async function checkNpmToken(
+  workspaceRoot: string,
+  deps: NpmTokenProbeDeps = {},
+): Promise<NpmTokenCheck> {
+  const env = deps.env ?? process.env;
+  const fetchVersion = deps.fetchVersion ?? defaultFetchVersion;
+  const { registry, tokenPresent } = readNpmrcTokenStatus(workspaceRoot, env);
+  const canFetch = fetchVersion(workspaceRoot);
+  return {
+    registry,
+    tokenPresent,
+    canFetch,
+    fixHint: canFetch ? null : buildFixHint(tokenPresent),
+  };
+}

package/src/onboarding/scaffold-project.ts

@@ -22,6 +22,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { execSync } from "node:child_process";
 import { listStackProfiles, type StackProfile } from "../profiles/stack-profile.ts";
+import { checkNpmToken, workshopNeedsWarpgogolToken } from "./npm-token-check.ts";
 import { resolveForgeRoot } from "../config/forge-config.ts";
 import type {
   ForgeCommandInput,
@@ -166,6 +167,16 @@ export async function runScaffoldProject(
     }
   }
 
+  // RFC-1125: non-interactive npm-token probe — fail fast before pnpm install when
+  // the @warpgogol scope is needed but the token cannot fetch @warpgogol/werkstatt-engine.
+  // Runs after .npmrc is materialized so the probe sees the final token state.
+  if (profile.install.length > 0 && workshopNeedsWarpgogolToken(workspaceRoot, profile.install)) {
+    const tokenCheck = await checkNpmToken(workspaceRoot);
+    if (!tokenCheck.canFetch) {
+      return fail("forge.scaffold", profileId, tokenCheck.fixHint!, errors, outputFormat, logger);
+    }
+  }
+
   // Run ALL install commands AFTER all files are created (atomicity: no partial state if install fails)
   // Root workspace install commands
   if (outputFormat === "pretty" && profile.install.length > 0) {