first-tree 0.0.2 → 0.0.4

package/skills/first-tree/engine/runtime/asset-loader.ts

@@ -0,0 +1,141 @@
+import { existsSync, statSync } from "node:fs";
+import { join } from "node:path";
+
+export const SKILL_NAME = "first-tree";
+export const SKILL_ROOT = join("skills", SKILL_NAME);
+export const SKILL_AGENTS_DIR = join(SKILL_ROOT, "agents");
+export const SKILL_REFERENCES_DIR = join(SKILL_ROOT, "references");
+export const FRAMEWORK_ASSET_ROOT = join(SKILL_ROOT, "assets", "framework");
+export const FRAMEWORK_MANIFEST = join(FRAMEWORK_ASSET_ROOT, "manifest.json");
+export const FRAMEWORK_VERSION = join(FRAMEWORK_ASSET_ROOT, "VERSION");
+export const FRAMEWORK_TEMPLATES_DIR = join(FRAMEWORK_ASSET_ROOT, "templates");
+export const FRAMEWORK_WORKFLOWS_DIR = join(FRAMEWORK_ASSET_ROOT, "workflows");
+export const FRAMEWORK_PROMPTS_DIR = join(FRAMEWORK_ASSET_ROOT, "prompts");
+export const FRAMEWORK_EXAMPLES_DIR = join(FRAMEWORK_ASSET_ROOT, "examples");
+export const FRAMEWORK_HELPERS_DIR = join(FRAMEWORK_ASSET_ROOT, "helpers");
+export const INSTALLED_PROGRESS = join(SKILL_ROOT, "progress.md");
+export const AGENT_INSTRUCTIONS_FILE = "AGENTS.md";
+export const LEGACY_AGENT_INSTRUCTIONS_FILE = "AGENT.md";
+export const AGENT_INSTRUCTIONS_TEMPLATE = "agents.md.template";
+
+export const LEGACY_SKILL_NAME = "first-tree-cli-framework";
+export const LEGACY_SKILL_ROOT = join("skills", LEGACY_SKILL_NAME);
+export const LEGACY_SKILL_ASSET_ROOT = join(
+  LEGACY_SKILL_ROOT,
+  "assets",
+  "framework",
+);
+export const LEGACY_SKILL_VERSION = join(LEGACY_SKILL_ASSET_ROOT, "VERSION");
+export const LEGACY_SKILL_TEMPLATES_DIR = join(
+  LEGACY_SKILL_ASSET_ROOT,
+  "templates",
+);
+export const LEGACY_SKILL_WORKFLOWS_DIR = join(
+  LEGACY_SKILL_ASSET_ROOT,
+  "workflows",
+);
+export const LEGACY_SKILL_PROMPTS_DIR = join(
+  LEGACY_SKILL_ASSET_ROOT,
+  "prompts",
+);
+export const LEGACY_SKILL_EXAMPLES_DIR = join(
+  LEGACY_SKILL_ASSET_ROOT,
+  "examples",
+);
+export const LEGACY_SKILL_PROGRESS = join(LEGACY_SKILL_ROOT, "progress.md");
+
+export const LEGACY_FRAMEWORK_ROOT = ".context-tree";
+export const LEGACY_VERSION = join(LEGACY_FRAMEWORK_ROOT, "VERSION");
+export const LEGACY_PROGRESS = join(LEGACY_FRAMEWORK_ROOT, "progress.md");
+export const LEGACY_TEMPLATES_DIR = join(LEGACY_FRAMEWORK_ROOT, "templates");
+export const LEGACY_WORKFLOWS_DIR = join(LEGACY_FRAMEWORK_ROOT, "workflows");
+export const LEGACY_PROMPTS_DIR = join(LEGACY_FRAMEWORK_ROOT, "prompts");
+export const LEGACY_EXAMPLES_DIR = join(LEGACY_FRAMEWORK_ROOT, "examples");
+
+export type FrameworkLayout = "skill" | "legacy-skill" | "legacy";
+
+function pathExists(root: string, relPath: string): boolean {
+  const fullPath = join(root, relPath);
+  try {
+    return existsSync(fullPath);
+  } catch {
+    return false;
+  }
+}
+
+export function frameworkVersionCandidates(): string[] {
+  return [FRAMEWORK_VERSION, LEGACY_SKILL_VERSION, LEGACY_VERSION];
+}
+
+export function progressFileCandidates(): string[] {
+  return [INSTALLED_PROGRESS, LEGACY_SKILL_PROGRESS, LEGACY_PROGRESS];
+}
+
+export function agentInstructionsFileCandidates(): string[] {
+  return [AGENT_INSTRUCTIONS_FILE, LEGACY_AGENT_INSTRUCTIONS_FILE];
+}
+
+export function frameworkTemplateDirCandidates(): string[] {
+  return [
+    FRAMEWORK_TEMPLATES_DIR,
+    LEGACY_SKILL_TEMPLATES_DIR,
+    LEGACY_TEMPLATES_DIR,
+  ];
+}
+
+export function frameworkWorkflowDirCandidates(): string[] {
+  return [
+    FRAMEWORK_WORKFLOWS_DIR,
+    LEGACY_SKILL_WORKFLOWS_DIR,
+    LEGACY_WORKFLOWS_DIR,
+  ];
+}
+
+export function frameworkPromptDirCandidates(): string[] {
+  return [
+    FRAMEWORK_PROMPTS_DIR,
+    LEGACY_SKILL_PROMPTS_DIR,
+    LEGACY_PROMPTS_DIR,
+  ];
+}
+
+export function frameworkExampleDirCandidates(): string[] {
+  return [
+    FRAMEWORK_EXAMPLES_DIR,
+    LEGACY_SKILL_EXAMPLES_DIR,
+    LEGACY_EXAMPLES_DIR,
+  ];
+}
+
+export function resolveFirstExistingPath(
+  root: string,
+  candidates: string[],
+): string | null {
+  for (const candidate of candidates) {
+    if (pathExists(root, candidate)) {
+      return candidate;
+    }
+  }
+  return null;
+}
+
+export function detectFrameworkLayout(root: string): FrameworkLayout | null {
+  if (pathExists(root, FRAMEWORK_VERSION)) {
+    return "skill";
+  }
+  if (pathExists(root, LEGACY_SKILL_VERSION)) {
+    return "legacy-skill";
+  }
+  if (pathExists(root, LEGACY_VERSION)) {
+    return "legacy";
+  }
+  return null;
+}
+
+export function isDirectory(root: string, relPath: string): boolean {
+  try {
+    return statSync(join(root, relPath)).isDirectory();
+  } catch {
+    return false;
+  }
+}

package/skills/first-tree/engine/runtime/installer.ts

@@ -0,0 +1,82 @@
+import { copyFileSync, cpSync, existsSync, mkdirSync, rmSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+  FRAMEWORK_ASSET_ROOT,
+  LEGACY_SKILL_ROOT,
+  SKILL_ROOT,
+} from "#skill/engine/runtime/asset-loader.js";
+
+export function resolveBundledPackageRoot(startUrl = import.meta.url): string {
+  let dir = dirname(fileURLToPath(startUrl));
+  while (true) {
+    if (
+      existsSync(join(dir, "package.json")) &&
+      existsSync(join(dir, SKILL_ROOT, "SKILL.md"))
+    ) {
+      return dir;
+    }
+
+    const parent = dirname(dir);
+    if (parent === dir) {
+      break;
+    }
+    dir = parent;
+  }
+
+  throw new Error(
+    "Could not locate the bundled `first-tree` package root. Reinstall the package and try again.",
+  );
+}
+
+export function resolveCanonicalSkillRoot(sourceRoot: string): string {
+  const directSkillRoot = sourceRoot;
+  if (
+    existsSync(join(directSkillRoot, "SKILL.md")) &&
+    existsSync(join(directSkillRoot, "assets", "framework", "VERSION"))
+  ) {
+    return directSkillRoot;
+  }
+
+  const nestedSkillRoot = join(sourceRoot, SKILL_ROOT);
+  if (
+    existsSync(join(nestedSkillRoot, "SKILL.md")) &&
+    existsSync(join(nestedSkillRoot, "assets", "framework", "VERSION"))
+  ) {
+    return nestedSkillRoot;
+  }
+
+  throw new Error(
+    `Canonical skill not found under ${sourceRoot}. Reinstall the \`first-tree\` package and try again.`,
+  );
+}
+
+export function copyCanonicalSkill(sourceRoot: string, targetRoot: string): void {
+  const src = resolveCanonicalSkillRoot(sourceRoot);
+  const dst = join(targetRoot, SKILL_ROOT);
+  const legacyDst = join(targetRoot, LEGACY_SKILL_ROOT);
+  if (existsSync(dst)) {
+    rmSync(dst, { recursive: true, force: true });
+  }
+  if (legacyDst !== dst && existsSync(legacyDst)) {
+    rmSync(legacyDst, { recursive: true, force: true });
+  }
+  mkdirSync(dirname(dst), { recursive: true });
+  cpSync(src, dst, { recursive: true });
+}
+
+export function renderTemplateFile(
+  frameworkRoot: string,
+  templateName: string,
+  targetRoot: string,
+  targetPath: string,
+): boolean {
+  const src = join(frameworkRoot, "templates", templateName);
+  const dst = join(targetRoot, targetPath);
+  if (existsSync(dst) || !existsSync(src)) {
+    return false;
+  }
+  mkdirSync(dirname(dst), { recursive: true });
+  copyFileSync(src, dst);
+  return true;
+}

package/skills/first-tree/engine/runtime/upgrader.ts

@@ -0,0 +1,23 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { resolveCanonicalSkillRoot } from "#skill/engine/runtime/installer.js";
+
+export function compareFrameworkVersions(left: string, right: string): number {
+  const result = left.localeCompare(right, undefined, {
+    numeric: true,
+    sensitivity: "base",
+  });
+  if (result < 0) return -1;
+  if (result > 0) return 1;
+  return 0;
+}
+
+export function readSourceVersion(sourceRoot: string): string | null {
+  const skillRoot = resolveCanonicalSkillRoot(sourceRoot);
+  const versionPath = join(skillRoot, "assets", "framework", "VERSION");
+  try {
+    return readFileSync(versionPath, "utf-8").trim();
+  } catch {
+    return null;
+  }
+}

package/skills/first-tree/engine/upgrade.ts

@@ -0,0 +1,233 @@
+import { mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { Repo } from "#skill/engine/repo.js";
+import {
+  AGENT_INSTRUCTIONS_FILE,
+  AGENT_INSTRUCTIONS_TEMPLATE,
+  FRAMEWORK_WORKFLOWS_DIR,
+  FRAMEWORK_TEMPLATES_DIR,
+  FRAMEWORK_VERSION,
+  INSTALLED_PROGRESS,
+  LEGACY_AGENT_INSTRUCTIONS_FILE,
+  LEGACY_FRAMEWORK_ROOT,
+  LEGACY_SKILL_ROOT,
+  SKILL_ROOT,
+  type FrameworkLayout,
+} from "#skill/engine/runtime/asset-loader.js";
+import {
+  copyCanonicalSkill,
+  resolveBundledPackageRoot,
+} from "#skill/engine/runtime/installer.js";
+import {
+  compareFrameworkVersions,
+  readSourceVersion,
+} from "#skill/engine/runtime/upgrader.js";
+
+export const UPGRADE_USAGE = `usage: context-tree upgrade [--tree-path PATH]
+
+Options:
+  --tree-path PATH   Upgrade a tree repo from another working directory
+  --help             Show this help message
+`;
+
+function writeProgress(repo: Repo, content: string): void {
+  const progressPath = join(repo.root, repo.preferredProgressPath());
+  mkdirSync(dirname(progressPath), { recursive: true });
+  writeFileSync(progressPath, content);
+}
+
+function formatUpgradeTaskList(
+  repo: Repo,
+  localVersion: string,
+  packagedVersion: string,
+  layout: FrameworkLayout,
+): string {
+  const lines: string[] = [
+    `# Context Tree Upgrade — v${localVersion} -> v${packagedVersion}\n`,
+    "## Installed Skill",
+    `- [ ] Review local customizations under \`${SKILL_ROOT}/\` and reapply them if needed`,
+    `- [ ] Re-copy any workflow updates you want from \`${FRAMEWORK_WORKFLOWS_DIR}/\` into \`.github/workflows/\``,
+    `- [ ] Re-check any local agent setup that references \`${SKILL_ROOT}/assets/framework/examples/\` or \`${SKILL_ROOT}/assets/framework/helpers/\``,
+    "",
+  ];
+
+  const migrationTasks: string[] = [];
+  if (layout === "legacy") {
+    migrationTasks.push(
+      "- [ ] Remove any stale `.context-tree/` references from repo-specific docs, scripts, or workflow files",
+    );
+  }
+
+  if (layout === "legacy-skill") {
+    migrationTasks.push(
+      `- [ ] Remove any stale \`${LEGACY_SKILL_ROOT}/\` references from repo-specific docs, scripts, workflow files, or agent config`,
+    );
+  }
+
+  if (repo.hasCanonicalAgentInstructionsFile() && repo.hasLegacyAgentInstructionsFile()) {
+    migrationTasks.push(
+      `- [ ] Merge any remaining user-authored content from \`${LEGACY_AGENT_INSTRUCTIONS_FILE}\` into \`${AGENT_INSTRUCTIONS_FILE}\`, then delete the legacy file`,
+    );
+  } else if (repo.hasLegacyAgentInstructionsFile()) {
+    migrationTasks.push(
+      `- [ ] Rename \`${LEGACY_AGENT_INSTRUCTIONS_FILE}\` to \`${AGENT_INSTRUCTIONS_FILE}\` to use the canonical agent instructions filename`,
+    );
+  }
+
+  if (migrationTasks.length > 0) {
+    lines.push("## Migration", ...migrationTasks, "");
+  }
+
+  if (repo.hasAgentInstructionsMarkers()) {
+    lines.push(
+      "## Agent Instructions",
+      `- [ ] Compare the framework section in \`${AGENT_INSTRUCTIONS_FILE}\` with \`${FRAMEWORK_TEMPLATES_DIR}/${AGENT_INSTRUCTIONS_TEMPLATE}\` and update the content between the markers if needed`,
+      "",
+    );
+  }
+
+  lines.push(
+    "## Verification",
+    `- [ ] \`${FRAMEWORK_VERSION}\` reads \`${packagedVersion}\``,
+    "- [ ] `context-tree verify` passes",
+    "",
+    "---",
+    "",
+    "**Important:** As you complete each task, check it off in" +
+      ` \`${INSTALLED_PROGRESS}\` by changing \`- [ ]\` to \`- [x]\`.` +
+      " Run `context-tree verify` when done — it will fail if any" +
+      " items remain unchecked.",
+    "",
+  );
+
+  return lines.join("\n");
+}
+
+export interface UpgradeOptions {
+  sourceRoot?: string;
+}
+
+export function runUpgrade(repo?: Repo, options?: UpgradeOptions): number {
+  const workingRepo = repo ?? new Repo();
+
+  if (workingRepo.isLikelySourceRepo() && !workingRepo.looksLikeTreeRepo()) {
+    console.error(
+      "Error: no installed framework skill found here. This looks like a source/workspace repo. Run `context-tree init` to create a dedicated tree repo, or pass `--tree-path` to upgrade an existing tree repo.",
+    );
+    return 1;
+  }
+
+  if (!workingRepo.hasFramework()) {
+    console.error(
+      "Error: no installed framework skill found. Run `context-tree init` first.",
+    );
+    return 1;
+  }
+
+  const layout = workingRepo.frameworkLayout();
+  if (layout === null) {
+    console.error(
+      "Error: no installed framework skill found. Run `context-tree init` first.",
+    );
+    return 1;
+  }
+  const localVersion = workingRepo.readVersion() ?? "unknown";
+  console.log(`Local framework version: ${localVersion}\n`);
+
+  console.log(
+    "Checking the framework skill bundled with this first-tree package...",
+  );
+
+  let sourceRoot: string;
+  try {
+    sourceRoot = options?.sourceRoot ?? resolveBundledPackageRoot();
+  } catch (err) {
+    const message = err instanceof Error ? err.message : "unknown error";
+    console.error(`Error: ${message}`);
+    return 1;
+  }
+
+  const packagedVersion = readSourceVersion(sourceRoot);
+  if (packagedVersion === null) {
+    console.log(
+      "Could not read the bundled framework version. Reinstall or update `first-tree` and try again.",
+    );
+    return 1;
+  }
+
+  if (
+    localVersion !== "unknown" &&
+    compareFrameworkVersions(localVersion, packagedVersion) > 0
+  ) {
+    console.log(
+      "The installed framework is newer than the skill bundled with this `first-tree` package. Install a newer package version before running `context-tree upgrade`.",
+    );
+    return 1;
+  }
+
+  if (layout === "skill" && packagedVersion === localVersion) {
+    console.log(
+      `Already up to date with the bundled skill (${FRAMEWORK_VERSION} = ${localVersion}).`,
+    );
+    return 0;
+  }
+
+  copyCanonicalSkill(sourceRoot, workingRepo.root);
+  if (layout === "legacy") {
+    rmSync(join(workingRepo.root, LEGACY_FRAMEWORK_ROOT), {
+      recursive: true,
+      force: true,
+    });
+    console.log(
+      "Migrated legacy .context-tree/ layout to skills/first-tree/.",
+    );
+  } else if (layout === "legacy-skill") {
+    console.log(
+      "Migrated skills/first-tree-cli-framework/ to skills/first-tree/.",
+    );
+  } else {
+    console.log(
+      "Refreshed skills/first-tree/ from the bundled first-tree package.",
+    );
+  }
+
+  const output = formatUpgradeTaskList(
+    workingRepo,
+    localVersion,
+    packagedVersion,
+    layout,
+  );
+  console.log(`\n${output}`);
+  writeProgress(workingRepo, output);
+  console.log(`Progress file written to ${workingRepo.preferredProgressPath()}`);
+  return 0;
+}
+
+export function runUpgradeCli(args: string[] = []): number {
+  if (args.includes("--help") || args.includes("-h")) {
+    console.log(UPGRADE_USAGE);
+    return 0;
+  }
+
+  let treePath: string | undefined;
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === "--tree-path") {
+      const value = args[index + 1];
+      if (!value) {
+        console.error("Missing value for --tree-path");
+        console.log(UPGRADE_USAGE);
+        return 1;
+      }
+      treePath = value;
+      index += 1;
+      continue;
+    }
+
+    console.error(`Unknown upgrade option: ${arg}`);
+    console.log(UPGRADE_USAGE);
+    return 1;
+  }
+
+  return runUpgrade(treePath ? new Repo(resolve(process.cwd(), treePath)) : undefined);
+}

package/skills/first-tree/engine/validators/members.ts

@@ -0,0 +1,215 @@
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { basename, join, relative } from "node:path";
+
+const FRONTMATTER_RE = /^---\s*\n(.*?)\n---/s;
+const VALID_TYPES = new Set(["human", "personal_assistant", "autonomous_agent"]);
+
+function rel(path: string, root: string): string {
+  return relative(root, path);
+}
+
+function parseFrontmatter(path: string): string | null {
+  try {
+    const text = readFileSync(path, "utf-8");
+    const m = text.match(FRONTMATTER_RE);
+    return m ? m[1] : null;
+  } catch {
+    return null;
+  }
+}
+
+export function extractScalar(fm: string, key: string): string | null {
+  const re = new RegExp(`^${key}:\\s*"?([^"\\n]+?)"?\\s*$`, "m");
+  const m = fm.match(re);
+  return m ? m[1].trim() : null;
+}
+
+export function extractList(fm: string, key: string): string[] | null {
+  // Inline: key: [a, b]
+  const inlineRe = new RegExp(`^${key}:\\s*\\[([^\\]]*)\\]`, "m");
+  let m = fm.match(inlineRe);
+  if (m) {
+    const raw = m[1].trim();
+    if (!raw) return [];
+    return raw
+      .split(",")
+      .map((s) => s.trim().replace(/^['"]|['"]$/g, ""))
+      .filter(Boolean);
+  }
+
+  // Block: key:\n  - a\n  - b
+  const blockRe = new RegExp(`^${key}:\\s*\\n((?:\\s+-\\s+.+\\n?)+)`, "m");
+  m = fm.match(blockRe);
+  if (m) {
+    return m[1]
+      .trim()
+      .split("\n")
+      .filter((line) => line.trim())
+      .map((line) =>
+        line
+          .trim()
+          .replace(/^-\s*/, "")
+          .trim()
+          .replace(/^['"]|['"]$/g, ""),
+      );
+  }
+
+  return null;
+}
+
+export function validateMember(
+  nodePath: string,
+  treeRoot: string,
+): string[] {
+  const errors: string[] = [];
+  const loc = rel(nodePath, treeRoot);
+
+  const fm = parseFrontmatter(nodePath);
+  if (fm === null) return [`${loc}: no frontmatter found`];
+
+  // title
+  const title = extractScalar(fm, "title");
+  if (!title) errors.push(`${loc}: missing or empty 'title' field`);
+
+  // owners
+  const owners = extractList(fm, "owners");
+  if (owners === null) errors.push(`${loc}: missing 'owners' field`);
+
+  // type
+  const memberType = extractScalar(fm, "type");
+  if (!memberType) {
+    errors.push(`${loc}: missing 'type' field`);
+  } else if (!VALID_TYPES.has(memberType)) {
+    errors.push(
+      `${loc}: invalid type '${memberType}' — must be one of: ${[...VALID_TYPES].sort().join(", ")}`,
+    );
+  }
+
+  // role
+  const role = extractScalar(fm, "role");
+  if (!role) errors.push(`${loc}: missing or empty 'role' field`);
+
+  // domains
+  const domains = extractList(fm, "domains");
+  if (domains === null) {
+    errors.push(`${loc}: missing 'domains' field`);
+  } else if (domains.length === 0) {
+    errors.push(`${loc}: 'domains' must contain at least one entry`);
+  }
+
+  return errors;
+}
+
+/** Info collected per member for cross-validation. */
+type MemberInfo = {
+  name: string;
+  relPath: string;
+  type: string | null;
+  delegateMention: string | null;
+};
+
+export function runValidateMembers(treeRoot: string): {
+  exitCode: number;
+  errors: string[];
+} {
+  const membersDir = join(treeRoot, "members");
+  if (!existsSync(membersDir) || !statSync(membersDir).isDirectory()) {
+    console.log(`Members directory not found: ${membersDir}`);
+    return { exitCode: 1, errors: [] };
+  }
+
+  const allErrors: string[] = [];
+  let memberCount = 0;
+
+  // Collected for cross-validation (name uniqueness + delegate_mention)
+  const nameOccurrences = new Map<string, string[]>();
+  const members: MemberInfo[] = [];
+
+  function walk(dir: string): void {
+    for (const child of readdirSync(dir).sort()) {
+      const childPath = join(dir, child);
+
+      // Reject stray .md files
+      try {
+        const stat = statSync(childPath);
+        if (stat.isFile() && child.endsWith(".md") && child !== "NODE.md") {
+          allErrors.push(
+            `${rel(childPath, treeRoot)}: member must be a directory with NODE.md, not a standalone file — use ${rel(dir, treeRoot)}/${child.replace(/\.md$/, "")}/NODE.md instead`,
+          );
+          continue;
+        }
+        if (!stat.isDirectory()) continue;
+      } catch {
+        continue;
+      }
+
+      // Track directory name occurrences for uniqueness check
+      const relPath = relative(membersDir, childPath);
+      const occurrences = nameOccurrences.get(child) ?? [];
+      occurrences.push(relPath);
+      nameOccurrences.set(child, occurrences);
+
+      const nodePath = join(childPath, "NODE.md");
+      if (!existsSync(nodePath)) {
+        allErrors.push(`${rel(childPath, treeRoot)}/: directory exists but missing NODE.md`);
+        walk(childPath);
+        continue;
+      }
+
+      memberCount++;
+      allErrors.push(...validateMember(nodePath, treeRoot));
+
+      // Collect info for cross-validation
+      const fm = parseFrontmatter(nodePath);
+      if (fm) {
+        members.push({
+          name: child,
+          relPath,
+          type: extractScalar(fm, "type"),
+          delegateMention: extractScalar(fm, "delegate_mention"),
+        });
+      }
+
+      // Recurse into subdirectories
+      walk(childPath);
+    }
+  }
+
+  walk(membersDir);
+
+  // Cross-validation: directory name uniqueness
+  for (const [name, paths] of nameOccurrences) {
+    if (paths.length > 1) {
+      allErrors.push(
+        `Duplicate member directory name '${name}' found at: ${paths.map((p) => `members/${p}`).join(", ")} — directory names must be unique across all levels under members/`,
+      );
+    }
+  }
+
+  // Cross-validation: delegate_mention references
+  const memberByName = new Map(members.map((m) => [m.name, m]));
+  for (const member of members) {
+    if (!member.delegateMention) continue;
+    const target = memberByName.get(member.delegateMention);
+    if (!target) {
+      allErrors.push(
+        `members/${member.relPath}/NODE.md: delegate_mention '${member.delegateMention}' references non-existent member — the target must be a directory under members/`,
+      );
+    } else if (target.type !== "personal_assistant") {
+      allErrors.push(
+        `members/${member.relPath}/NODE.md: delegate_mention '${member.delegateMention}' must reference a member with type 'personal_assistant', but '${target.name}' has type '${target.type}'`,
+      );
+    }
+  }
+
+  if (allErrors.length > 0) {
+    console.log(`Found ${allErrors.length} member validation error(s):\n`);
+    for (const err of allErrors) {
+      console.log(`  \u2717 ${err}`);
+    }
+    return { exitCode: 1, errors: allErrors };
+  }
+
+  console.log(`All ${memberCount} member(s) passed validation.`);
+  return { exitCode: 0, errors: allErrors };
+}