@geminix/gxpm 0.1.0

package/scripts/install-hooks.ts

@@ -0,0 +1,128 @@
+import { execSync } from "node:child_process";
+import { copyFileSync, existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+
+interface HookSpec {
+  gxpmFile: string;
+  topLevelFile: string;
+  argsForwarding: string;
+}
+
+const HOOK_SPECS: HookSpec[] = [
+  { gxpmFile: "gxpm-pre-commit", topLevelFile: "pre-commit", argsForwarding: "" },
+  { gxpmFile: "gxpm-commit-msg", topLevelFile: "commit-msg", argsForwarding: ' "$1"' },
+  { gxpmFile: "gxpm-pre-push", topLevelFile: "pre-push", argsForwarding: ' "$@"' },
+  { gxpmFile: "gxpm-post-merge", topLevelFile: "post-merge", argsForwarding: ' "$@"' },
+  { gxpmFile: "gxpm-post-checkout", topLevelFile: "post-checkout", argsForwarding: ' "$@"' },
+];
+
+function dispatcherScript(gxpmFile: string, argsForwarding: string): string {
+  return `#!/bin/bash
+# gxpm dispatcher (installed by gxpm-init --install-hooks)
+# Calls the gxpm-specific hook if present; harmless otherwise.
+set -e
+HOOK_DIR="$(cd "$(dirname "$0")" && pwd)"
+if [ -x "$HOOK_DIR/${gxpmFile}" ]; then
+  "$HOOK_DIR/${gxpmFile}"${argsForwarding}
+fi
+`;
+}
+
+interface InstallOptions {
+  target: string;
+}
+
+function parseArgs(argv: string[]): InstallOptions {
+  const dashTarget = argv.indexOf("--target");
+  const target = dashTarget >= 0 ? argv[dashTarget + 1] : process.cwd();
+  return { target: resolve(target) };
+}
+
+function isGitRepo(dir: string): boolean {
+  const gitDir = join(dir, ".git");
+  if (!existsSync(gitDir)) return false;
+  try {
+    return statSync(gitDir).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+function main(argv: string[]) {
+  const { target } = parseArgs(argv);
+
+  if (!isGitRepo(target)) {
+    console.error(`Not a git repository: ${target}`);
+    process.exit(1);
+  }
+
+  const templatesDir = resolve(import.meta.dir, "..", "templates", "hooks");
+  const hooksDir = join(target, ".githooks");
+  mkdirSync(hooksDir, { recursive: true });
+
+  const skipped: string[] = [];
+
+  for (const spec of HOOK_SPECS) {
+    const src = join(templatesDir, spec.gxpmFile);
+    const dst = join(hooksDir, spec.gxpmFile);
+    copyFileSync(src, dst);
+    execSync(`chmod +x "${dst}"`);
+    console.log(`installed: .githooks/${spec.gxpmFile}`);
+
+    const topLevelPath = join(hooksDir, spec.topLevelFile);
+    if (!existsSync(topLevelPath)) {
+      writeFileSync(topLevelPath, dispatcherScript(spec.gxpmFile, spec.argsForwarding));
+      execSync(`chmod +x "${topLevelPath}"`);
+      console.log(`created dispatcher: .githooks/${spec.topLevelFile}`);
+    } else {
+      skipped.push(spec.topLevelFile);
+    }
+  }
+
+  const absoluteHooksPath = join(resolve(target), ".githooks");
+  let currentHooksPath = "";
+  try {
+    currentHooksPath = execSync("git config core.hooksPath", { cwd: target }).toString().trim();
+  } catch {
+    // unset
+  }
+  if (currentHooksPath !== absoluteHooksPath) {
+    execSync(`git config core.hooksPath "${absoluteHooksPath}"`, { cwd: target });
+    console.log(`set git config core.hooksPath = ${absoluteHooksPath}`);
+  } else {
+    console.log(`core.hooksPath already = ${absoluteHooksPath}`);
+  }
+
+  if (skipped.length > 0) {
+    console.log("");
+    console.log("Existing top-level hooks were NOT overwritten:");
+    for (const name of skipped) {
+      console.log(`  .githooks/${name}`);
+    }
+    console.log("To wire gxpm into them, append:");
+    console.log('  [ -x .githooks/gxpm-<hook-name> ] && .githooks/gxpm-<hook-name> "$@"');
+  }
+
+  const gxpmRoot = resolve(import.meta.dir, "..");
+  installAgentsFragment(target, gxpmRoot);
+}
+
+function installAgentsFragment(target: string, _gxpmRoot: string): void {
+  const agentsPath = join(target, "AGENTS.md");
+  if (!existsSync(agentsPath)) {
+    return;
+  }
+
+  const MARKER_START = "<!-- GXPM:CODE-REVIEW-GRAPH:START -->";
+  const MARKER_END = "<!-- GXPM:CODE-REVIEW-GRAPH:END -->";
+
+  let content = readFileSync(agentsPath, "utf8");
+  if (content.includes(MARKER_START) && content.includes(MARKER_END)) {
+    const regex = new RegExp(`${MARKER_START}[\\s\\S]*?${MARKER_END}\\n?`, "g");
+    content = content.replace(regex, "");
+    writeFileSync(agentsPath, content);
+    console.log(`cleaned legacy graph marker from: ${agentsPath}`);
+  }
+}
+
+main(Bun.argv.slice(2));

package/scripts/install-kimi-hooks.ts

@@ -0,0 +1,92 @@
+/**
+ * Install Kimi CLI hooks that call the unified `gxpm hook` entry point.
+ *
+ * Appends/updates a `[[hooks]]` block in `~/.kimi/config.toml`.
+ * Kimi hooks are user-scoped only (no repo-level hooks.json equivalent).
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+interface InstallKimiHooksOptions {
+  home?: string;
+}
+
+interface InstallResult {
+  configTomlPath: string;
+  rootDir: string;
+}
+
+const GXPM_HOOKS_START = "# gxpm hooks (managed by gxpm init) — do not edit manually";
+const GXPM_HOOKS_END = "# end gxpm hooks";
+
+const HOOKS_TOML = `[[hooks]]
+event = "SessionStart"
+command = "gxpm hook SessionStart --host kimi"
+matcher = "startup|clear|compact"
+timeout = 30
+
+[[hooks]]
+event = "UserPromptSubmit"
+command = "gxpm hook UserPromptSubmit --host kimi"
+matcher = ""
+timeout = 30
+
+[[hooks]]
+event = "PreToolUse"
+command = "gxpm hook PreToolUse --host kimi"
+matcher = "edit_file|write_file"
+timeout = 10`;
+
+export function installKimiHooks(options: InstallKimiHooksOptions = {}): InstallResult {
+  const home = options.home ?? homedir();
+  const rootDir = join(home, ".kimi");
+  mkdirSync(rootDir, { recursive: true });
+
+  const configTomlPath = join(rootDir, "config.toml");
+
+  let content = existsSync(configTomlPath) ? readFileSync(configTomlPath, "utf8") : "";
+  content = replaceGxpmBlock(content, HOOKS_TOML);
+  writeFileSync(configTomlPath, content);
+
+  return { configTomlPath, rootDir };
+}
+
+function replaceGxpmBlock(content: string, block: string): string {
+  const startIdx = content.indexOf(GXPM_HOOKS_START);
+  const endIdx = content.indexOf(GXPM_HOOKS_END);
+
+  if (startIdx >= 0 && endIdx >= 0 && endIdx > startIdx) {
+    // Replace existing block
+    const before = content.slice(0, startIdx);
+    const after = content.slice(endIdx + GXPM_HOOKS_END.length);
+    return `${before.trimEnd()}\n\n${GXPM_HOOKS_START}\n${block}\n${GXPM_HOOKS_END}\n${after.trimStart()}`;
+  }
+
+  // Append new block
+  const trimmed = content.trimEnd();
+  const separator = trimmed.length > 0 ? "\n\n" : "";
+  return `${trimmed}${separator}${GXPM_HOOKS_START}\n${block}\n${GXPM_HOOKS_END}\n`;
+}
+
+function parseArgs(argv: string[]): InstallKimiHooksOptions {
+  const opts: InstallKimiHooksOptions = {};
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i];
+    if (a === "--home") opts.home = argv[++i];
+    else throw new Error(`Unknown argument: ${a}`);
+  }
+  return opts;
+}
+
+if (import.meta.main) {
+  try {
+    const result = installKimiHooks(parseArgs(Bun.argv.slice(2)));
+    console.log(`wrote: ${result.configTomlPath}`);
+    console.log("Restart Kimi CLI to activate hooks.");
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exit(1);
+  }
+}

package/scripts/install-skill.ts

@@ -0,0 +1,184 @@
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { ALL_HOST_CONFIGS, getHostConfig } from "../hosts";
+import { discoverTemplates } from "./discover-skills";
+import { renderSkillContentForHost } from "./gen-skill-docs";
+import { SkillParser, HostConverter, SkillWriter } from "../core/converters";
+import type { HostConfig } from "../core/contracts/host";
+
+interface InstallSkillOptions {
+  /** @deprecated use `hosts` instead */
+  hostName?: string; // "codex" | "claude" | "all"
+  /** Explicit list of host names to install to. Overrides `hostName`. */
+  hosts?: string[];
+  root?: string; // gxpm repo root (default: cwd)
+  home?: string; // override for testing (default: homedir())
+}
+
+// Default root is the gxpm repo itself (the parent of scripts/), not cwd —
+// install-skill must read templates from gxpm regardless of where it's invoked.
+const DEFAULT_GXPM_ROOT = resolve(import.meta.dir, "..");
+
+function resolveSkillInstallPath(skillName: string, host: HostConfig, home: string): string {
+  // For gxpm main skill, preserve backward-compatible path using host.globalRoot
+  if (skillName === "gxpm") {
+    return join(home, host.globalRoot, "SKILL.md");
+  }
+  // For other skills, install into host-specific skill directory
+  if (host.name === "codex") {
+    return join(home, ".codex", "skills", skillName, "SKILL.md");
+  }
+  if (host.name === "claude") {
+    return join(home, ".claude", "skills", skillName, "SKILL.md");
+  }
+  // Fallback to host.globalRoot parent + skill name
+  return join(home, dirname(host.globalRoot), skillName, "SKILL.md");
+}
+
+function renderOrReadSkill(root: string, host: HostConfig, template: ReturnType<typeof discoverTemplates>[number]): string {
+  if (template.tmpl.endsWith(".tmpl")) {
+    return renderSkillContentForHost(root, host, template.tmpl, template.references);
+  }
+
+  // Static file: use the new AST pipeline for multi-platform conversion
+  const source = readFileSync(join(root, template.tmpl), "utf8");
+  const parser = new SkillParser();
+  const converter = new HostConverter();
+  const writer = new SkillWriter();
+  const doc = parser.parse(source);
+  const converted = converter.convert(doc, { hostName: host.name });
+  return writer.write(converted);
+}
+
+export function installSkill(options: InstallSkillOptions = {}): string[] {
+  const root = options.root ?? DEFAULT_GXPM_ROOT;
+  const home = options.home ?? homedir();
+  const targets = resolveTargets(options.hostName, options.hosts);
+
+  const installed: string[] = [];
+
+  for (const template of discoverTemplates(root)) {
+    for (const host of targets) {
+      const content = renderOrReadSkill(root, host, template);
+      // For .tmpl files, frontmatter is not yet filtered; apply host-specific filtering.
+      // For static files, the new pipeline already filtered frontmatter.
+      const transformed = template.tmpl.endsWith(".tmpl") ? applyFrontmatter(content, host) : content;
+      const installPath = resolveSkillInstallPath(template.name, host, home);
+      mkdirSync(dirname(installPath), { recursive: true });
+      writeFileSync(installPath, transformed);
+      installed.push(installPath);
+
+      // Install references
+      if (template.references) {
+        const skillInstallDir = dirname(installPath);
+        const refsInstallDir = join(skillInstallDir, "references");
+        for (const refPath of template.references) {
+          const refContent = readFileSync(join(root, refPath), "utf8");
+          const refName = refPath.replace(/^.*\//, "");
+          const refInstallPath = join(refsInstallDir, refName);
+          mkdirSync(refsInstallDir, { recursive: true });
+          writeFileSync(refInstallPath, refContent);
+          installed.push(refInstallPath);
+        }
+      }
+
+      // Install scripts
+      if (template.scripts) {
+        const skillInstallDir = dirname(installPath);
+        const scriptsInstallDir = join(skillInstallDir, "scripts");
+        for (const scriptPath of template.scripts) {
+          const scriptContent = readFileSync(join(root, scriptPath), "utf8");
+          const scriptName = scriptPath.replace(/^.*\//, "");
+          const scriptInstallPath = join(scriptsInstallDir, scriptName);
+          mkdirSync(scriptsInstallDir, { recursive: true });
+          writeFileSync(scriptInstallPath, scriptContent);
+          installed.push(scriptInstallPath);
+        }
+      }
+    }
+  }
+
+  return installed;
+}
+
+function resolveTargets(name: string | undefined, hosts: string[] | undefined): readonly HostConfig[] {
+  if (hosts && hosts.length > 0) {
+    return hosts.map((n) => getHostConfig(n));
+  }
+  if (!name || name === "all") {
+    return ALL_HOST_CONFIGS;
+  }
+  return [getHostConfig(name)];
+}
+
+function applyFrontmatter(content: string, host: HostConfig): string {
+  if (host.frontmatter.mode === "preserve") {
+    return content;
+  }
+
+  const match = content.match(/^---\n([\s\S]*?)\n---\n?/);
+  if (!match) {
+    return content;
+  }
+
+  const body = content.slice(match[0].length);
+  const allowed = new Set(host.frontmatter.keys);
+  const filteredFrontmatter = match[1]
+    .split("\n")
+    .filter((line) => {
+      if (!line.trim() || line.startsWith("#")) return true;
+      const colonIndex = line.indexOf(":");
+      if (colonIndex < 0) return true;
+      const key = line.slice(0, colonIndex).trim();
+      return allowed.has(key);
+    })
+    .join("\n");
+
+  return `---\n${filteredFrontmatter}\n---\n${body}`;
+}
+
+interface ParsedArgs {
+  hostName?: string;
+  hosts?: string[];
+  root?: string;
+  home?: string;
+}
+
+function parseArgs(argv: string[]): ParsedArgs {
+  const options: ParsedArgs = {};
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === "--host") {
+      options.hostName = argv[++index];
+    } else if (arg === "--hosts") {
+      const raw = argv[++index];
+      options.hosts = raw ? raw.split(",").map((s) => s.trim()).filter(Boolean) : [];
+    } else if (arg === "--root") {
+      options.root = argv[++index];
+    } else if (arg === "--home") {
+      options.home = argv[++index];
+    } else {
+      throw new Error(`Unknown argument: ${arg}`);
+    }
+  }
+  return options;
+}
+
+if (import.meta.main) {
+  try {
+    const args = parseArgs(Bun.argv.slice(2));
+    const installed = installSkill({
+      hostName: args.hostName,
+      hosts: args.hosts,
+      root: args.root ? resolve(args.root) : undefined,
+      home: args.home ? resolve(args.home) : undefined,
+    });
+    for (const path of installed) {
+      console.log(`installed: ${path}`);
+    }
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exit(1);
+  }
+}

package/scripts/phase-artifact-commands.ts

@@ -0,0 +1,100 @@
+import { initializeAcceptanceCheck } from "../core/ac-check";
+import { type ArtifactType } from "../core/artifacts";
+import { initializeDispatch } from "../core/dispatch";
+import { initializeLocalVerify } from "../core/implement";
+import { initializeLandFindings } from "../core/land";
+import { PHASE_GATE_RULES } from "../core/phase-gates";
+import { initializePlan } from "../core/plan";
+import { initializePrCheck } from "../core/pr-check";
+import { initializeQaFindings } from "../core/qa";
+import { initializeSelfReview } from "../core/self-review";
+import { initializeShipReadiness } from "../core/ship";
+import { initializeCleanup } from "../core/cleanup";
+import { initializeSpecify } from "../core/specify";
+import { initializeTriage } from "../core/triage";
+import { initializeVerifyFindings } from "../core/verify";
+
+interface PhaseArtifactCommand {
+  artifactType: ArtifactType;
+  command: string;
+  initialize: (input: { issueId: string }) => unknown;
+  successMessage: (issueId: string) => string;
+}
+
+const PHASE_ARTIFACT_HANDLERS: Partial<Record<
+  ArtifactType,
+  Pick<PhaseArtifactCommand, "initialize" | "successMessage">
+>> = {
+  "acceptance-contract": {
+    initialize: initializeTriage,
+    successMessage: (issueId) => `initialized triage artifacts for ${issueId}`,
+  },
+  "implementation-plan": {
+    initialize: initializePlan,
+    successMessage: (issueId) => `initialized plan artifact for ${issueId}`,
+  },
+  "dispatch-handoff": {
+    initialize: initializeDispatch,
+    successMessage: (issueId) => `initialized dispatch handoff for ${issueId}`,
+  },
+  "behavior-spec": {
+    initialize: initializeSpecify,
+    successMessage: (issueId) => `initialized behavior-spec artifact for ${issueId}`,
+  },
+  "local-verify": {
+    initialize: initializeLocalVerify,
+    successMessage: (issueId) => `initialized local verify artifact for ${issueId}`,
+  },
+  "acceptance-check": {
+    initialize: initializeAcceptanceCheck,
+    successMessage: (issueId) => `initialized acceptance check artifact for ${issueId}`,
+  },
+  "self-review": {
+    initialize: (input) => initializeSelfReview({ ...input, army: process.argv.includes("--army") }),
+    successMessage: (issueId) => `initialized self review artifact for ${issueId}`,
+  },
+  "cleanup-report": {
+    initialize: initializeCleanup,
+    successMessage: (issueId) => `initialized cleanup report for ${issueId}`,
+  },
+  "ship-readiness": {
+    initialize: (input) => initializeShipReadiness({ ...input, army: process.argv.includes("--army") }),
+    successMessage: (issueId) => `initialized ship readiness artifact for ${issueId}`,
+  },
+  "pr-check": {
+    initialize: initializePrCheck,
+    successMessage: (issueId) => `initialized pr check artifact for ${issueId}`,
+  },
+  "verify-findings": {
+    initialize: initializeVerifyFindings,
+    successMessage: (issueId) => `initialized verify findings artifact for ${issueId}`,
+  },
+  "qa-findings": {
+    initialize: initializeQaFindings,
+    successMessage: (issueId) => `initialized QA findings artifact for ${issueId}`,
+  },
+  "land-findings": {
+    initialize: initializeLandFindings,
+    successMessage: (issueId) => `initialized land findings artifact for ${issueId}`,
+  },
+};
+
+export const PHASE_ARTIFACT_COMMANDS: PhaseArtifactCommand[] = PHASE_GATE_RULES.map((rule) => {
+  const handler = PHASE_ARTIFACT_HANDLERS[rule.requiredArtifact];
+  if (!handler) {
+    throw new Error(`Missing phase artifact handler for ${rule.requiredArtifact}`);
+  }
+
+  return {
+    artifactType: rule.requiredArtifact,
+    command: rule.command,
+    ...handler,
+  };
+});
+
+export function findPhaseArtifactCommand(command: string, subcommand: string | undefined) {
+  return PHASE_ARTIFACT_COMMANDS.find((item) => {
+    const [, registeredCommand, registeredSubcommand] = item.command.split(" ");
+    return registeredCommand === command && registeredSubcommand === subcommand;
+  });
+}

package/scripts/post-land-sync.ts

@@ -0,0 +1,46 @@
+import { join, resolve } from "node:path";
+
+interface PostLandSkillSyncOptions {
+  root?: string;
+  env?: NodeJS.ProcessEnv;
+}
+
+interface PostLandSkillSyncResult {
+  ok: boolean;
+  message: string;
+}
+
+const DEFAULT_GXPM_ROOT = resolve(import.meta.dir, "..");
+
+export function runPostLandSkillSync(options: PostLandSkillSyncOptions = {}): PostLandSkillSyncResult {
+  const root = options.root ?? DEFAULT_GXPM_ROOT;
+  const env = options.env ?? process.env;
+  if (env.GXPM_SKIP_POST_LAND_SYNC === "1") {
+    return { ok: true, message: "post-land skill install skipped" };
+  }
+  const gxpmInit = env.GXPM_INIT_BIN || join(root, "bin", "gxpm-init");
+
+  try {
+    const result = Bun.spawnSync({
+      cmd: [gxpmInit, "--install-skill", "--host", "all"],
+      cwd: root,
+      stdout: "pipe",
+      stderr: "pipe",
+      env,
+    });
+
+    if (result.exitCode === 0) {
+      return { ok: true, message: "skill install sync completed" };
+    }
+
+    const stderr = result.stderr.toString().trim();
+    const stdout = result.stdout.toString().trim();
+    const detail = stderr || stdout || `exit code ${result.exitCode}`;
+    return { ok: false, message: `post-land skill install failed: ${detail}` };
+  } catch (error) {
+    return {
+      ok: false,
+      message: `post-land skill install failed: ${error instanceof Error ? error.message : String(error)}`,
+    };
+  }
+}

package/scripts/scaffold-check.ts

@@ -0,0 +1,85 @@
+import { resolve } from "node:path";
+import { ARTIFACT_TYPES, type ArtifactType } from "../core/artifacts";
+import { CAPABILITY_REGISTRY } from "../core/capabilities";
+import { listValidatedArtifactTypes } from "../core/artifact-validator";
+import { PHASE_GATE_RULES } from "../core/phase-gates";
+import { ALL_HOST_CONFIGS } from "../hosts";
+import { generateSkillDocs } from "./gen-skill-docs";
+import { validateGovernanceDocs } from "./governance-check";
+import { validateAllConfigs } from "./host-config";
+import { validateSkillNaming } from "./skill-naming-check";
+import { validateVersionTruth } from "./version";
+import { validateSkillsLock } from "./skills-lock-check";
+import { validateSkillStructure, formatSkillStructureErrors } from "./skill-structure-check";
+
+// Default to the gxpm repo itself (parent of scripts/) so the check is
+// meaningful regardless of the cwd the CLI was invoked from.
+const DEFAULT_GXPM_ROOT = resolve(import.meta.dir, "..");
+
+export interface RunScaffoldCheckOptions {
+  root?: string;
+}
+
+export function validateLayeredWorkflowContracts(): string[] {
+  const errors: string[] = [];
+  const artifactTypes = new Set<ArtifactType>(ARTIFACT_TYPES);
+  const validatedArtifactTypes = new Set<ArtifactType>(listValidatedArtifactTypes());
+  const capabilityArtifacts = new Set<ArtifactType>(
+    CAPABILITY_REGISTRY.flatMap((capability) => capability.outputContract.artifacts),
+  );
+
+  for (const rule of PHASE_GATE_RULES) {
+    if (!capabilityArtifacts.has(rule.requiredArtifact)) {
+      errors.push(
+        `phase gate ${rule.fromPhase}->${rule.nextPhase} requires ${rule.requiredArtifact}, but no capability outputs it`,
+      );
+    }
+  }
+
+  for (const artifactType of ARTIFACT_TYPES) {
+    if (!validatedArtifactTypes.has(artifactType)) {
+      errors.push(`artifact ${artifactType} is not covered by artifact-validator`);
+    }
+  }
+
+  for (const artifactType of capabilityArtifacts) {
+    if (!artifactTypes.has(artifactType)) {
+      errors.push(`capability outputs unknown artifact ${artifactType}`);
+    }
+  }
+
+  return errors;
+}
+
+export function runScaffoldCheck(options: RunScaffoldCheckOptions = {}) {
+  const root = options.root ?? DEFAULT_GXPM_ROOT;
+
+  const hostErrors = validateAllConfigs(ALL_HOST_CONFIGS);
+  const governanceErrors = validateGovernanceDocs({ root });
+  const versionErrors = validateVersionTruth({ root });
+  const skillNamingErrors = validateSkillNaming({ root });
+  const skillsLockErrors = validateSkillsLock({ root });
+  const layeredWorkflowErrors = validateLayeredWorkflowContracts();
+  const skillStructureViolations = validateSkillStructure(root);
+  const { errors: skillStructureErrors, warnings: skillStructureWarnings } = formatSkillStructureErrors(skillStructureViolations);
+  const errors = [
+    ...hostErrors.map((error) => `host config: ${error}`),
+    ...governanceErrors.map((error) => `governance: ${error}`),
+    ...versionErrors.map((error) => `version: ${error}`),
+    ...skillNamingErrors.map((error) => `skill-naming: ${error}`),
+    ...skillsLockErrors.map((error) => `skills-lock: ${error}`),
+    ...layeredWorkflowErrors.map((error) => `layered-workflow: ${error}`),
+    ...skillStructureErrors,
+  ];
+
+  if (skillStructureWarnings.length > 0) {
+    console.warn(skillStructureWarnings.join("\n"));
+  }
+
+  if (errors.length > 0) {
+    throw new Error(errors.join("\n"));
+  }
+
+  generateSkillDocs({ root, dryRun: true });
+  return `gxpm scaffold check passed (${ALL_HOST_CONFIGS.length} hosts)`;
+}