@warpgogol/forge 0.3.1

package/dist/src/onboarding/create.js

@@ -0,0 +1,232 @@
+/*
+<MODULE_CONTRACT>
+<purpose>forge.create — single entry point for project scaffolding. Composes forge.scaffold + forge.init + package-manager post-processing into one command.</purpose>
+<non-goals>
+  <item>Do not change forge.init or forge.scaffold contracts — forge.create delegates to them.</item>
+  <item>Do not add interactive prompts — all configuration is via flags and positional args.</item>
+  <item>Do not import from @warpgogol/* — this module is portable.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0544: initial forge.create handler composing scaffold + init.</item>
+  <item>RFC-0544 fix: replace double cast on runInit return with proper InitResult typing.</item>
+  <item>RFC-0548: auto-run forge.agents.generate after init, update nextSteps to remove manual AGENTS.md step.</item>
+  <item>RFC-0550: write NEXT_STEPS.md into project root with creator-facing guidance (greenfield vs transplant via LLM).</item>
+</CHANGE_SUMMARY>
+*/
+import fs from "node:fs";
+import path from "node:path";
+import { stringify as stringifyYaml } from "yaml";
+import { runScaffoldProject } from "./scaffold-project.js";
+import { runInit } from "./init.js";
+import { runAgentsGenerate } from "./agents-generate.js";
+import { loadForgeConfig, resolveForgeRoot, resolvePackageManager, applyCliBindingDefaults, } from "../config/forge-config.js";
+export async function runCreate(input, context) {
+    const { logger, outputFormat } = context;
+    const name = input.args[0];
+    const profile = input.flags["profile"] ?? "forge-shell";
+    const packageManager = input.flags["package-manager"] ?? "pnpm";
+    const errors = [];
+    const passNextSteps = [
+        { action: "Open the project in Windsurf", kind: "required" },
+        { action: "Run /forge-bootstrap to configure the project interactively", kind: "optional" },
+    ];
+    const failNextSteps = [
+        { action: "Fix the errors above and re-run forge.create", kind: "required" },
+    ];
+    // 1. Validate name
+    if (!name) {
+        errors.push("Missing required positional argument: <name>");
+        if (outputFormat === "pretty") {
+            logger.error("Missing required positional argument: <name>");
+        }
+        return {
+            data: { command: "forge.create", status: "fail", projectDir: "", profile, filesCreated: [], errors },
+            nextSteps: failNextSteps,
+            exitCode: 1,
+            summary: "forge.create: failed — missing <name> argument",
+        };
+    }
+    if (!/^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/.test(name)) {
+        const msg = `Project name "${name}" is not kebab-case (expected ^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$)`;
+        errors.push(msg);
+        if (outputFormat === "pretty") {
+            logger.error(msg);
+        }
+        return {
+            data: { command: "forge.create", status: "fail", projectDir: "", profile, filesCreated: [], errors },
+            nextSteps: failNextSteps,
+            exitCode: 1,
+            summary: `forge.create: failed — ${msg}`,
+        };
+    }
+    // 2. Resolve target directory
+    const targetDir = path.resolve(context.workspaceRoot, name);
+    // 3. Refuse if target exists and is non-empty
+    if (fs.existsSync(targetDir)) {
+        const entries = fs.readdirSync(targetDir);
+        if (entries.length > 0) {
+            const msg = `Directory "${name}" already exists and is not empty (contains: ${entries.slice(0, 5).join(", ")}${entries.length > 5 ? "…" : ""})`;
+            errors.push(msg);
+            if (outputFormat === "pretty") {
+                logger.error(msg);
+            }
+            return {
+                data: { command: "forge.create", status: "fail", projectDir: targetDir, profile, filesCreated: [], errors },
+                nextSteps: failNextSteps,
+                exitCode: 1,
+                summary: `forge.create: failed — ${msg}`,
+            };
+        }
+    }
+    // 4. Create target directory
+    fs.mkdirSync(targetDir, { recursive: true });
+    // 4b. Resolve forge root from parent context (the new dir won't have forge installed)
+    let forgeRoot;
+    if (context.forgeRoot) {
+        forgeRoot = context.forgeRoot;
+    }
+    else {
+        try {
+            forgeRoot = resolveForgeRoot(context.workspaceRoot);
+        }
+        catch {
+            forgeRoot = context.workspaceRoot;
+        }
+    }
+    // 5. Build child context with workspaceRoot = targetDir and forgeRoot override
+    const childContext = {
+        ...context,
+        workspaceRoot: targetDir,
+        forgeRoot,
+    };
+    // 6. Run forge.scaffold inside target dir
+    const scaffoldInput = {
+        argv: [],
+        args: [],
+        flags: { profile, name },
+    };
+    const scaffoldResult = await runScaffoldProject(scaffoldInput, childContext);
+    if (scaffoldResult.exitCode !== 0) {
+        const scaffoldErrors = scaffoldResult.data?.errors ?? ["scaffold failed"];
+        return {
+            data: {
+                command: "forge.create",
+                status: "fail",
+                projectDir: targetDir,
+                profile,
+                filesCreated: scaffoldResult.data?.created ?? [],
+                errors: scaffoldErrors,
+            },
+            nextSteps: failNextSteps,
+            exitCode: 1,
+            summary: `forge.create: failed — scaffold step failed`,
+        };
+    }
+    // 7. Run forge.init inside target dir
+    const initInput = {
+        argv: [],
+        args: [],
+        flags: {},
+    };
+    const initResult = runInit(initInput, childContext);
+    if (initResult.status !== "pass") {
+        return {
+            data: {
+                command: "forge.create",
+                status: "fail",
+                projectDir: targetDir,
+                profile,
+                filesCreated: [...(scaffoldResult.data?.created ?? []), ...(initResult.created ?? [])],
+                errors: initResult.errors ?? ["init failed"],
+            },
+            nextSteps: failNextSteps,
+            exitCode: 1,
+            summary: `forge.create: failed — init step failed`,
+        };
+    }
+    // 8. Post-process forge.yaml if --package-manager differs from default
+    if (packageManager !== "pnpm") {
+        const forgeYamlPath = path.join(targetDir, "forge.yaml");
+        if (fs.existsSync(forgeYamlPath)) {
+            try {
+                const config = loadForgeConfig(targetDir);
+                const pm = resolvePackageManager(packageManager);
+                config.project.packageManager = pm;
+                if (config.bindings) {
+                    config.bindings.commands = applyCliBindingDefaults(pm);
+                }
+                fs.writeFileSync(forgeYamlPath, stringifyYaml(config), "utf8");
+            }
+            catch {
+                // Post-processing is best-effort — init already wrote a valid config
+            }
+        }
+    }
+    // 9. Auto-run forge.agents.generate (RFC-0548)
+    try {
+        const agentsInput = {
+            argv: [],
+            args: [],
+            flags: {},
+        };
+        const agentsResult = await runAgentsGenerate(agentsInput, childContext);
+        if (agentsResult.exitCode !== 0 && outputFormat === "pretty") {
+            logger.warn("forge.agents.generate failed — AGENTS.md not generated. Run 'forge agents generate' manually after fixing the issue.");
+        }
+    }
+    catch {
+        if (outputFormat === "pretty") {
+            logger.warn("forge.agents.generate failed — AGENTS.md not generated. Run 'forge agents generate' manually after fixing the issue.");
+        }
+    }
+    // 10. Write NEXT_STEPS.md (RFC-0550)
+    const nextStepsPath = path.join(targetDir, "NEXT_STEPS.md");
+    const nextStepsContent = `# Next Steps
+
+Your Forge project is ready. You have two options — just tell the AI agent what you want, and it will handle the rest.
+
+## Option A: Start creating
+
+Tell the AI agent what you want to build. Describe your idea in your own words — a website, a game, a blog, a tool — and the system will set everything up and start creating with you.
+
+## Option B: Bring your existing project
+
+If you already have a project elsewhere and want to move it into Forge, tell the AI agent:
+
+> I want to bring my existing project into Forge.
+
+The system will guide you through the process — it detects your project type, migrates the code, and preserves your Git history.
+
+---
+
+Whichever path you choose, you don't need to run any commands. Just describe what you want in natural language, and the AI agent takes care of it.
+`;
+    fs.writeFileSync(nextStepsPath, nextStepsContent, "utf8");
+    // 11. Collect filesCreated
+    const filesCreated = [
+        ...(scaffoldResult.data?.created ?? []),
+        ...(initResult.created ?? []),
+        "NEXT_STEPS.md",
+    ];
+    if (outputFormat === "pretty") {
+        logger.success(`Created project "${name}" in ${targetDir}`);
+        for (const f of filesCreated) {
+            logger.info(`  created: ${f}`);
+        }
+    }
+    return {
+        data: {
+            command: "forge.create",
+            status: "pass",
+            projectDir: targetDir,
+            profile,
+            filesCreated,
+            errors: [],
+        },
+        nextSteps: passNextSteps,
+        exitCode: 0,
+        summary: `forge.create: OK — created ${name} with ${filesCreated.length} files`,
+    };
+}
+//# sourceMappingURL=create.js.map

package/dist/src/onboarding/create.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"create.js","sourceRoot":"","sources":["../../../src/onboarding/create.ts"],"names":[],"mappings":"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"}

package/dist/src/onboarding/doctor.d.ts

@@ -0,0 +1,30 @@
+import type { ForgeCommandInput, ForgeCommandResult, ForgeRuntimeContext } from "../types.ts";
+interface DoctorCheck {
+    name: string;
+    status: "pass" | "fail" | "warn";
+    message: string;
+}
+interface ForbiddenImport {
+    file: string;
+    specifier: string;
+}
+interface BindingValidation {
+    resolved: string[];
+    absent: string[];
+    invalid: string[];
+    notices: BindingNotice[];
+}
+interface BindingNotice {
+    key: string;
+    rule: string;
+    suggestion: string;
+}
+export declare function runDoctor(_input: ForgeCommandInput, context: ForgeRuntimeContext): Promise<ForgeCommandResult<{
+    command: string;
+    checks: DoctorCheck[];
+    allPass: boolean;
+    forbiddenImports: ForbiddenImport[];
+    bindings: BindingValidation;
+}>>;
+export {};
+//# sourceMappingURL=doctor.d.ts.map

package/dist/src/onboarding/doctor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../../../src/onboarding/doctor.ts"],"names":[],"mappings":"AAqBA,OAAO,KAAK,EACV,iBAAiB,EACjB,kBAAkB,EAClB,mBAAmB,EACpB,MAAM,aAAa,CAAC;AAIrB,UAAU,WAAW;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC;IACjC,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,UAAU,eAAe;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,UAAU,iBAAiB;IACzB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,OAAO,EAAE,aAAa,EAAE,CAAC;CAC1B;AAED,UAAU,aAAa;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;CACpB;AA4RD,wBAAsB,SAAS,CAC7B,MAAM,EAAE,iBAAiB,EACzB,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC,kBAAkB,CAAC;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,WAAW,EAAE,CAAC;IAAC,OAAO,EAAE,OAAO,CAAC;IAAC,gBAAgB,EAAE,eAAe,EAAE,CAAC;IAAC,QAAQ,EAAE,iBAAiB,CAAA;CAAE,CAAC,CAAC,CA8H7J"}

package/dist/src/onboarding/doctor.js

@@ -0,0 +1,380 @@
+/*
+<MODULE_CONTRACT>
+<purpose>forge.doctor — diagnoses forge state in an existing project.
+Checks for forge.yaml, AGENTS.md, PREFERENCES.md, .agents/skills/, docs/rfcs/,
+@warpgogol/* import autonomy guard, and bindings contract (RFC-0393).</purpose>
+<non-goals>
+  <item>Do not modify files — doctor is read-only diagnostics.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>Initial forge.doctor handler for autonomy refactor.</item>
+  <item>RFC-0391: added @warpgogol/* forbidden-imports autonomy guard.</item>
+  <item>RFC-0393: added bindings validation — resolved/absent/invalid reporting.</item>
+  <item>RFC-0524: added stale knowledge file detection — compares source and .agents/ copies.</item>
+  <item>RFC-0539: extended knowledge file check to iterate pack skills via discoverPackSkills. Added pack-skills check for stale/missing copies and skillPacks config validation.</item>
+  <item>RFC-0540: added defaultable-binding-null notices for forge-CLI-backed bindings.</item>
+</CHANGE_SUMMARY>
+*/
+import { readFile, readdir, stat } from "node:fs/promises";
+import { join, relative, dirname } from "node:path";
+import { resolveForgeRoot, loadForgeConfig, resolveBinding, FORGE_CLI_BINDING_DEFAULTS, resolvePmRunner } from "../config/forge-config.js";
+import { FORGE_SKILLS, discoverPackSkills } from "../registry.js";
+async function pathExists(target) {
+    try {
+        await stat(target);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+const FORBIDDEN_IMPORT_PATTERN = /(?:^|\n)\s*(?:import\s+[^;]+?\s+from\s+|require\s*\(\s*)["'`](@warpgogol\/[^"'`]+)["'`]/g;
+async function scanForForbiddenImports(dir, workspaceRoot) {
+    const violations = [];
+    const entries = await readdir(dir, { withFileTypes: true }).catch(() => []);
+    for (const entry of entries) {
+        const fullPath = join(dir, entry.name);
+        if (entry.isDirectory()) {
+            if (entry.name === "node_modules" || entry.name === "tests")
+                continue;
+            const sub = await scanForForbiddenImports(fullPath, workspaceRoot);
+            violations.push(...sub);
+        }
+        else if (entry.name.endsWith(".ts")) {
+            const content = await readFile(fullPath, "utf8").catch(() => "");
+            let match;
+            const pattern = new RegExp(FORBIDDEN_IMPORT_PATTERN.source, "g");
+            while ((match = pattern.exec(content)) !== null) {
+                violations.push({
+                    file: relative(workspaceRoot, fullPath),
+                    specifier: match[1],
+                });
+            }
+        }
+    }
+    return violations;
+}
+// ---------------------------------------------------------------------------
+// Bindings validation (RFC-0393)
+// ---------------------------------------------------------------------------
+const BINDING_PATH_KEYS = [
+    "paths.invariantsFile",
+    "paths.reviewsDir",
+    "paths.handoffsDir",
+    "paths.sessionsDir",
+];
+const BINDING_COMMAND_KEYS = [
+    "commands.validateRfc",
+    "commands.validateAdr",
+    "commands.implementStamp",
+    "commands.typecheck",
+    "commands.test",
+    "commands.scopedBuild",
+    "commands.specValidate",
+];
+async function validateBindings(workspaceRoot) {
+    const result = { resolved: [], absent: [], invalid: [], notices: [] };
+    let config;
+    try {
+        config = loadForgeConfig(workspaceRoot);
+    }
+    catch {
+        return result;
+    }
+    if (!config.bindings) {
+        return result;
+    }
+    for (const key of BINDING_PATH_KEYS) {
+        const value = resolveBinding(config, key);
+        if (value === null) {
+            result.absent.push(key);
+        }
+        else if (typeof value === "string") {
+            const exists = await pathExists(join(workspaceRoot, value));
+            if (exists) {
+                result.resolved.push(key);
+            }
+            else {
+                result.invalid.push(`${key} (path not found: ${value})`);
+            }
+        }
+    }
+    const compassDocs = resolveBinding(config, "paths.compassDocs");
+    if (Array.isArray(compassDocs) && compassDocs.length > 0) {
+        for (const docPath of compassDocs) {
+            const exists = await pathExists(join(workspaceRoot, docPath));
+            if (exists) {
+                result.resolved.push(`paths.compassDocs[${docPath}]`);
+            }
+            else {
+                result.invalid.push(`paths.compassDocs[${docPath}] (path not found)`);
+            }
+        }
+    }
+    else {
+        result.absent.push("paths.compassDocs");
+    }
+    for (const key of BINDING_COMMAND_KEYS) {
+        const value = resolveBinding(config, key);
+        if (value === null) {
+            result.absent.push(key);
+        }
+        else if (typeof value === "string") {
+            result.resolved.push(key);
+        }
+    }
+    // RFC-0540: Emit defaultable-binding-null notices for forge-CLI-backed bindings
+    const pm = config.project.packageManager;
+    const runner = resolvePmRunner(pm);
+    for (const entry of FORGE_CLI_BINDING_DEFAULTS) {
+        const value = resolveBinding(config, entry.key);
+        if (value === null) {
+            result.notices.push({
+                key: entry.key,
+                rule: "defaultable-binding-null",
+                suggestion: `${runner} ${entry.template}`,
+            });
+        }
+    }
+    return result;
+}
+// ---------------------------------------------------------------------------
+// Stale knowledge file detection (RFC-0524)
+// ---------------------------------------------------------------------------
+async function checkStaleKnowledgeFiles(workspaceRoot, forgeRoot) {
+    const stale = [];
+    let config;
+    try {
+        config = loadForgeConfig(workspaceRoot);
+    }
+    catch {
+        return { name: "knowledge-files", status: "pass", message: "No forge.yaml — knowledge file check skipped" };
+    }
+    const agentsSkillsDir = join(workspaceRoot, config.paths.skillsDir);
+    for (const skill of FORGE_SKILLS) {
+        if (!skill.knowledge || skill.knowledge.length === 0)
+            continue;
+        const skillSrcDir = dirname(join(forgeRoot, skill.path));
+        for (const kf of skill.knowledge) {
+            const srcPath = join(skillSrcDir, kf);
+            const destPath = join(agentsSkillsDir, skill.name, kf);
+            const srcExists = await pathExists(srcPath);
+            const destExists = await pathExists(destPath);
+            if (srcExists && destExists) {
+                const srcContent = await readFile(srcPath, "utf8").catch(() => "");
+                const destContent = await readFile(destPath, "utf8").catch(() => "");
+                if (srcContent !== destContent) {
+                    stale.push(`${skill.name}/${kf}`);
+                }
+            }
+            // If source exists but dest doesn't, skip — expected on first install
+            // If source doesn't exist, SKILL-13 in forge.skill.validate catches it
+        }
+    }
+    // RFC-0539: Check pack skill knowledge files
+    const packSkills = discoverPackSkills(workspaceRoot, config);
+    for (const skill of packSkills) {
+        if (!skill.knowledge || skill.knowledge.length === 0)
+            continue;
+        const skillSrcDir = dirname(join(workspaceRoot, skill.dir, skill.path));
+        for (const kf of skill.knowledge) {
+            const srcPath = join(skillSrcDir, kf);
+            const destPath = join(agentsSkillsDir, skill.name, kf);
+            const srcExists = await pathExists(srcPath);
+            const destExists = await pathExists(destPath);
+            if (srcExists && destExists) {
+                const srcContent = await readFile(srcPath, "utf8").catch(() => "");
+                const destContent = await readFile(destPath, "utf8").catch(() => "");
+                if (srcContent !== destContent) {
+                    stale.push(`${skill.name}/${kf}`);
+                }
+            }
+        }
+    }
+    return {
+        name: "knowledge-files",
+        status: stale.length === 0 ? "pass" : "warn",
+        message: stale.length === 0
+            ? "All knowledge files in sync"
+            : `${stale.length} stale knowledge file(s): ${stale.join(", ")} — run 'forge create' to sync`,
+    };
+}
+// ---------------------------------------------------------------------------
+// Pack skill diagnostics (RFC-0539)
+// ---------------------------------------------------------------------------
+async function checkPackSkills(workspaceRoot) {
+    let config;
+    try {
+        config = loadForgeConfig(workspaceRoot);
+    }
+    catch {
+        return { name: "pack-skills", status: "pass", message: "No forge.yaml — pack skill check skipped" };
+    }
+    if (!config.skillPacks || config.skillPacks.length === 0) {
+        return { name: "pack-skills", status: "pass", message: "No skill packs declared" };
+    }
+    const issues = [];
+    // Validate skillPacks config: unique prefixes, unique dirs, no 'fo' prefix, dir exists
+    const prefixes = new Set();
+    const dirs = new Set();
+    for (const pack of config.skillPacks) {
+        if (prefixes.has(pack.prefix)) {
+            issues.push(`duplicate prefix '${pack.prefix}'`);
+        }
+        prefixes.add(pack.prefix);
+        if (pack.prefix === "fo") {
+            issues.push(`prefix 'fo' is reserved for forge`);
+        }
+        if (dirs.has(pack.dir)) {
+            issues.push(`duplicate dir '${pack.dir}'`);
+        }
+        dirs.add(pack.dir);
+        const packDirExists = await pathExists(join(workspaceRoot, pack.dir));
+        if (!packDirExists) {
+            issues.push(`pack dir '${pack.dir}' does not exist`);
+        }
+    }
+    // Check for stale/missing pack skill copies
+    const packSkills = discoverPackSkills(workspaceRoot, config);
+    const agentsSkillsDir = join(workspaceRoot, config.paths.skillsDir);
+    for (const skill of packSkills) {
+        const srcPath = join(workspaceRoot, skill.dir, skill.path);
+        const destPath = join(agentsSkillsDir, skill.name, "SKILL.md");
+        const srcExists = await pathExists(srcPath);
+        const destExists = await pathExists(destPath);
+        if (srcExists && destExists) {
+            const srcContent = await readFile(srcPath, "utf8").catch(() => "");
+            const destContent = await readFile(destPath, "utf8").catch(() => "");
+            if (srcContent !== destContent) {
+                issues.push(`stale copy of '${skill.name}'`);
+            }
+        }
+        else if (srcExists && !destExists) {
+            issues.push(`missing copy of '${skill.name}'`);
+        }
+    }
+    return {
+        name: "pack-skills",
+        status: issues.length === 0 ? "pass" : "warn",
+        message: issues.length === 0
+            ? `${packSkills.length} pack skill(s) in sync`
+            : `${issues.length} issue(s): ${issues.join(", ")} — run 'forge create' to sync`,
+    };
+}
+export async function runDoctor(_input, context) {
+    const { workspaceRoot, logger, outputFormat } = context;
+    const checks = [];
+    // Check forge.yaml
+    const forgeYamlExists = await pathExists(join(workspaceRoot, "forge.yaml"));
+    checks.push({
+        name: "forge.yaml",
+        status: forgeYamlExists ? "pass" : "warn",
+        message: forgeYamlExists
+            ? "forge.yaml found"
+            : "forge.yaml not found — run 'forge create' to create project configuration",
+    });
+    // Check AGENTS.md
+    const agentsMdExists = await pathExists(join(workspaceRoot, "AGENTS.md"));
+    checks.push({
+        name: "AGENTS.md",
+        status: agentsMdExists ? "pass" : "warn",
+        message: agentsMdExists
+            ? "AGENTS.md found"
+            : "AGENTS.md not found — run 'forge create' to deploy agent instructions",
+    });
+    // Check PREFERENCES.md
+    const preferencesExists = await pathExists(join(workspaceRoot, "PREFERENCES.md"));
+    checks.push({
+        name: "PREFERENCES.md",
+        status: preferencesExists ? "pass" : "warn",
+        message: preferencesExists
+            ? "PREFERENCES.md found"
+            : "PREFERENCES.md not found — run 'forge create' to create preferences file",
+    });
+    // Check .agents/skills/
+    const skillsDirExists = await pathExists(join(workspaceRoot, ".agents", "skills"));
+    checks.push({
+        name: ".agents/skills/",
+        status: skillsDirExists ? "pass" : "fail",
+        message: skillsDirExists
+            ? ".agents/skills/ directory found"
+            : ".agents/skills/ directory not found — run 'forge create' to deploy skills",
+    });
+    // Check docs/rfcs/
+    const rfcsDirExists = await pathExists(join(workspaceRoot, "docs", "rfcs"));
+    checks.push({
+        name: "docs/rfcs/",
+        status: rfcsDirExists ? "pass" : "warn",
+        message: rfcsDirExists
+            ? "docs/rfcs/ directory found"
+            : "docs/rfcs/ directory not found — run 'forge create' to create RFC directory",
+    });
+    // Check docs/adrs/
+    const adrsDirExists = await pathExists(join(workspaceRoot, "docs", "adrs"));
+    checks.push({
+        name: "docs/adrs/",
+        status: adrsDirExists ? "pass" : "warn",
+        message: adrsDirExists
+            ? "docs/adrs/ directory found"
+            : "docs/adrs/ directory not found — run 'forge create' to create ADR directory",
+    });
+    // Check @warpgogol/* forbidden imports (autonomy guard)
+    let forgeRoot;
+    try {
+        forgeRoot = resolveForgeRoot(workspaceRoot);
+    }
+    catch {
+        forgeRoot = join(workspaceRoot, "packages", "forge");
+    }
+    const forbiddenImports = await scanForForbiddenImports(forgeRoot, workspaceRoot);
+    checks.push({
+        name: "autonomy-guard",
+        status: forbiddenImports.length === 0 ? "pass" : "fail",
+        message: forbiddenImports.length === 0
+            ? "No @warpgogol/* imports in forge source"
+            : `${forbiddenImports.length} @warpgogol/* import(s) found in forge source — remove them`,
+    });
+    // Check bindings contract (RFC-0393)
+    const bindingsResult = await validateBindings(workspaceRoot);
+    checks.push({
+        name: "bindings",
+        status: bindingsResult.invalid.length === 0 ? "pass" : "fail",
+        message: bindingsResult.invalid.length === 0
+            ? `Bindings: ${bindingsResult.resolved.length} resolved, ${bindingsResult.absent.length} absent`
+            : `Bindings: ${bindingsResult.invalid.length} invalid — ${bindingsResult.invalid.join(", ")}`,
+    });
+    // Check stale knowledge files (RFC-0524, RFC-0539)
+    const staleCheck = await checkStaleKnowledgeFiles(workspaceRoot, forgeRoot);
+    checks.push(staleCheck);
+    // RFC-0539: Check pack skills — stale/missing copies and config validation
+    const packCheck = await checkPackSkills(workspaceRoot);
+    checks.push(packCheck);
+    const allPass = checks.every((c) => c.status === "pass");
+    const hasFails = checks.some((c) => c.status === "fail");
+    if (outputFormat === "pretty") {
+        logger.section(`Forge Doctor — ${workspaceRoot}`);
+        for (const check of checks) {
+            const icon = check.status === "pass" ? "✓" : check.status === "warn" ? "⚠" : "✖";
+            const fn = check.status === "pass" ? logger.success : check.status === "warn" ? logger.warn : logger.error;
+            fn(`${icon} ${check.name}: ${check.message}`);
+        }
+        if (allPass) {
+            logger.success("All checks passed — forge is properly configured.");
+        }
+        else if (hasFails) {
+            logger.error("Some checks failed — run 'forge create' to fix.");
+        }
+        else {
+            logger.warn("Some checks warn — review above.");
+        }
+    }
+    return {
+        data: { command: "forge.doctor", checks, allPass, forbiddenImports, bindings: bindingsResult },
+        exitCode: hasFails ? 1 : 0,
+        summary: allPass
+            ? "forge.doctor: all checks passed"
+            : `forge.doctor: ${checks.filter((c) => c.status === "fail").length} fail(s), ${checks.filter((c) => c.status === "warn").length} warn(s)`,
+    };
+}
+//# sourceMappingURL=doctor.js.map