@geraldmaron/construct 1.4.2 → 1.5.0

package/lib/queue/pg-queue.mjs

@@ -0,0 +1,395 @@
+/**
+ * lib/queue/pg-queue.mjs — optional Postgres kind:'queue' provider.
+ *
+ * Claiming uses a single UPDATE fed by SELECT ... FOR UPDATE SKIP LOCKED so
+ * parallel workers contend inside Postgres instead of racing in process memory.
+ */
+
+import crypto from 'node:crypto';
+
+import { applyMigrations } from '../db/migrate.mjs';
+
+export const PG_QUEUE_DEFAULT_NAME = 'intake';
+export const PG_QUEUE_DEFAULT_LEASE_SECONDS = 120;
+export const PG_QUEUE_DEFAULT_MAX_ATTEMPTS = 3;
+
+export function newQueueId(prefix = 'pkt') {
+  return `${prefix}-${Date.now().toString(36)}-${crypto.randomBytes(4).toString('hex')}`;
+}
+
+function nowIso() {
+  return new Date().toISOString();
+}
+
+function normalizeEntry(entry, id) {
+  return {
+    ...entry,
+    id,
+    status: entry?.status || 'pending',
+    createdAt: entry?.createdAt || nowIso(),
+  };
+}
+
+function rowToEntry(row) {
+  return row?.payload || null;
+}
+
+function leaseInterval(sql, seconds) {
+  return sql`${Number(seconds)} * interval '1 second'`;
+}
+
+function backoffInterval(sql, seconds) {
+  return sql`${Math.max(0, Number(seconds) || 0)} * interval '1 second'`;
+}
+
+export class PostgresIntakeQueue {
+  constructor({
+    sql,
+    project,
+    tenantId = 'local',
+    queueName = PG_QUEUE_DEFAULT_NAME,
+    leaseSeconds = PG_QUEUE_DEFAULT_LEASE_SECONDS,
+  } = {}) {
+    if (!sql) throw new Error('PostgresIntakeQueue: sql client is required');
+    if (!project) throw new Error('PostgresIntakeQueue: project is required');
+    this.sql = sql;
+    this.project = project;
+    this.tenantId = tenantId;
+    this.queueName = queueName;
+    this.leaseSeconds = Number(leaseSeconds) || PG_QUEUE_DEFAULT_LEASE_SECONDS;
+    this._ensured = null;
+  }
+
+  async ensureSchema() {
+    if (!this._ensured) this._ensured = applyMigrations(this.sql);
+    return this._ensured;
+  }
+
+  async enqueue(entry) {
+    if (!entry?.intake?.sourcePath) throw new Error('enqueue: entry.intake.sourcePath is required');
+    await this.ensureSchema();
+    const id = entry.id || newQueueId();
+    const payload = normalizeEntry(entry, id);
+    await this.sql`
+      INSERT INTO construct_queue_items (
+        project, tenant_id, queue_name, item_id, status, payload, created_at, updated_at, max_attempts
+      ) VALUES (
+        ${this.project}, ${this.tenantId}, ${this.queueName}, ${id}, 'pending',
+        ${this.sql.json(payload)}, ${payload.createdAt}, now(),
+        ${Number(entry.maxAttempts) > 0 ? Math.floor(Number(entry.maxAttempts)) : PG_QUEUE_DEFAULT_MAX_ATTEMPTS}
+      )
+      ON CONFLICT (project, tenant_id, queue_name, item_id) DO UPDATE SET
+        payload = EXCLUDED.payload,
+        status = EXCLUDED.status,
+        max_attempts = EXCLUDED.max_attempts,
+        updated_at = now()
+    `;
+    return { id };
+  }
+
+  async listPending() {
+    await this.ensureSchema();
+    const rows = await this.sql`
+      SELECT payload FROM construct_queue_items
+      WHERE project = ${this.project}
+        AND tenant_id = ${this.tenantId}
+        AND queue_name = ${this.queueName}
+        AND status = 'pending'
+      ORDER BY created_at ASC, item_id ASC
+    `;
+    return rows.map(rowToEntry);
+  }
+
+  async count() {
+    await this.ensureSchema();
+    const rows = await this.sql`
+      SELECT COUNT(*)::int AS count FROM construct_queue_items
+      WHERE project = ${this.project}
+        AND tenant_id = ${this.tenantId}
+        AND queue_name = ${this.queueName}
+        AND status = 'pending'
+    `;
+    return Number(rows[0]?.count || 0);
+  }
+
+  async read(id) {
+    if (!id) return null;
+    await this.ensureSchema();
+    const rows = await this.sql`
+      SELECT payload FROM construct_queue_items
+      WHERE project = ${this.project}
+        AND tenant_id = ${this.tenantId}
+        AND queue_name = ${this.queueName}
+        AND item_id = ${id}
+      LIMIT 1
+    `;
+    return rowToEntry(rows[0]);
+  }
+
+  async claim({ claimedBy, leaseSeconds = this.leaseSeconds } = {}) {
+    if (!claimedBy) throw new Error('claim: claimedBy is required');
+    await this.ensureSchema();
+    const claimId = newQueueId('claim');
+    const rows = await this.sql`
+      WITH candidate AS (
+        SELECT item_id
+        FROM construct_queue_items
+        WHERE project = ${this.project}
+          AND tenant_id = ${this.tenantId}
+          AND queue_name = ${this.queueName}
+          AND available_at <= now()
+          AND (
+            status = 'pending'
+            OR (status = 'claimed' AND lease_expires_at <= now() AND attempt < max_attempts)
+          )
+        ORDER BY created_at ASC, item_id ASC
+        FOR UPDATE SKIP LOCKED
+        LIMIT 1
+      ),
+      updated AS (
+        UPDATE construct_queue_items q
+        SET status = 'claimed',
+            attempt = q.attempt + 1,
+            claimed_by = ${claimedBy},
+            lease_expires_at = now() + ${leaseInterval(this.sql, leaseSeconds)},
+            updated_at = now(),
+            payload = jsonb_set(
+              jsonb_set(
+                jsonb_set(q.payload, '{status}', to_jsonb('claimed'::text), true),
+                '{claimedBy}', to_jsonb(${claimedBy}::text), true
+              ),
+              '{claimedAt}', to_jsonb(now()::text), true
+            )
+        FROM candidate
+        WHERE q.project = ${this.project}
+          AND q.tenant_id = ${this.tenantId}
+          AND q.queue_name = ${this.queueName}
+          AND q.item_id = candidate.item_id
+        RETURNING q.item_id, q.attempt, q.lease_expires_at, q.payload
+      )
+      INSERT INTO construct_queue_claims (
+        claim_id, project, tenant_id, queue_name, item_id, worker_id, attempt, lease_expires_at
+      )
+      SELECT ${claimId}, ${this.project}, ${this.tenantId}, ${this.queueName},
+             item_id, ${claimedBy}, attempt, lease_expires_at
+      FROM updated
+      RETURNING item_id, attempt, lease_expires_at,
+        (SELECT payload FROM updated WHERE updated.item_id = construct_queue_claims.item_id) AS payload
+    `;
+    const row = rows[0];
+    if (!row) return null;
+    return {
+      ...row.payload,
+      id: row.payload?.id || row.item_id,
+      status: 'claimed',
+      claimedBy,
+      attempt: row.attempt,
+      leaseExpiresAt: row.lease_expires_at,
+      claimId,
+    };
+  }
+
+  async heartbeat(id, { workerId, leaseSeconds = this.leaseSeconds } = {}) {
+    if (!id) throw new Error('heartbeat: id is required');
+    if (!workerId) throw new Error('heartbeat: workerId is required');
+    await this.ensureSchema();
+    const rows = await this.sql`
+      UPDATE construct_queue_items
+      SET lease_expires_at = now() + ${leaseInterval(this.sql, leaseSeconds)},
+          updated_at = now()
+      WHERE project = ${this.project}
+        AND tenant_id = ${this.tenantId}
+        AND queue_name = ${this.queueName}
+        AND item_id = ${id}
+        AND status = 'claimed'
+        AND claimed_by = ${workerId}
+        AND lease_expires_at > now()
+        AND COALESCE((payload->>'cancelRequested')::boolean, false) = false
+      RETURNING item_id, lease_expires_at
+    `;
+    if (!rows[0]) {
+      const current = await this.read(id);
+      if (current?.cancelRequested) return { id, renewed: false, cancelled: true, reason: current.cancellationReason || null };
+      return { id, renewed: false };
+    }
+    return { id, renewed: true, leaseExpiresAt: rows[0].lease_expires_at };
+  }
+
+  async fail(id, { workerId, reason, backoffSeconds = 0 } = {}) {
+    if (!id) throw new Error('fail: id is required');
+    await this.ensureSchema();
+    const rows = await this.sql`
+      UPDATE construct_queue_items
+      SET status = CASE WHEN attempt >= max_attempts THEN 'dead_letter' ELSE 'pending' END,
+          available_at = CASE WHEN attempt >= max_attempts THEN available_at ELSE now() + ${backoffInterval(this.sql, backoffSeconds)} END,
+          terminal_reason = ${reason || null},
+          claimed_by = NULL,
+          lease_expires_at = NULL,
+          updated_at = now(),
+          payload = jsonb_set(
+            jsonb_set(
+              jsonb_set(payload, '{status}', to_jsonb(CASE WHEN attempt >= max_attempts THEN 'dead_letter'::text ELSE 'pending'::text END), true),
+              '{lastFailureReason}', to_jsonb(${reason || ''}::text), true
+            ),
+            '{failedBy}', to_jsonb(${workerId || ''}::text), true
+          )
+      WHERE project = ${this.project}
+        AND tenant_id = ${this.tenantId}
+        AND queue_name = ${this.queueName}
+        AND item_id = ${id}
+        AND status = 'claimed'
+        AND (${workerId || null} IS NULL OR claimed_by = ${workerId || null})
+      RETURNING item_id, status, attempt, max_attempts, available_at
+    `;
+    if (!rows[0]) return null;
+    return {
+      id,
+      status: rows[0].status,
+      attempt: rows[0].attempt,
+      maxAttempts: rows[0].max_attempts,
+      deadLettered: rows[0].status === 'dead_letter',
+      availableAt: rows[0].available_at,
+    };
+  }
+
+  async requestCancellation(id, { requestedBy, reason } = {}) {
+    if (!id) throw new Error('requestCancellation: id is required');
+    await this.ensureSchema();
+    const rows = await this.sql`
+      UPDATE construct_queue_items
+      SET terminal_reason = ${reason || null},
+          updated_at = now(),
+          payload = jsonb_set(
+            jsonb_set(
+              jsonb_set(payload, '{cancelRequested}', 'true'::jsonb, true),
+              '{cancellationReason}', to_jsonb(${reason || ''}::text), true
+            ),
+            '{cancelRequestedBy}', to_jsonb(${requestedBy || ''}::text), true
+          )
+      WHERE project = ${this.project}
+        AND tenant_id = ${this.tenantId}
+        AND queue_name = ${this.queueName}
+        AND item_id = ${id}
+        AND status IN ('pending', 'claimed', 'awaiting_approval')
+      RETURNING item_id
+    `;
+    return rows[0] ? { id, cancellationRequested: true } : null;
+  }
+
+  async markProcessed(id, { processedBy, notes, executionKey } = {}) {
+    if (!id) throw new Error('markProcessed: id is required');
+    await this.ensureSchema();
+    if (executionKey) {
+      const current = await this.read(id);
+      if (current?.status === 'processed' && current.executionKey === executionKey) {
+        return { id, idempotent: true };
+      }
+    }
+    const rows = await this.sql`
+      UPDATE construct_queue_items
+      SET status = 'processed',
+          processed_at = now(),
+          processed_by = ${processedBy || null},
+          terminal_reason = ${notes || null},
+          claimed_by = NULL,
+          lease_expires_at = NULL,
+          updated_at = now(),
+          payload = jsonb_set(
+            jsonb_set(
+              jsonb_set(payload, '{status}', to_jsonb('processed'::text), true),
+              '{processedAt}', to_jsonb(now()::text), true
+            ),
+            '{executionKey}', to_jsonb(${executionKey || ''}::text), true
+          )
+      WHERE project = ${this.project}
+        AND tenant_id = ${this.tenantId}
+        AND queue_name = ${this.queueName}
+        AND item_id = ${id}
+        AND status <> 'processed'
+      RETURNING item_id
+    `;
+    return rows[0] ? { id } : null;
+  }
+
+  async markSkipped(id, { skippedBy, reason } = {}) {
+    if (!id) throw new Error('markSkipped: id is required');
+    await this.ensureSchema();
+    const rows = await this.sql`
+      UPDATE construct_queue_items
+      SET status = 'skipped',
+          skipped_at = now(),
+          skipped_by = ${skippedBy || null},
+          terminal_reason = ${reason || null},
+          claimed_by = NULL,
+          lease_expires_at = NULL,
+          updated_at = now(),
+          payload = jsonb_set(
+            jsonb_set(payload, '{status}', to_jsonb('skipped'::text), true),
+            '{skippedAt}', to_jsonb(now()::text), true
+          )
+      WHERE project = ${this.project}
+        AND tenant_id = ${this.tenantId}
+        AND queue_name = ${this.queueName}
+        AND item_id = ${id}
+      RETURNING item_id
+    `;
+    return rows[0] ? { id } : null;
+  }
+
+  async reopen(id) {
+    if (!id) throw new Error('reopen: id is required');
+    await this.ensureSchema();
+    const rows = await this.sql`
+      UPDATE construct_queue_items
+      SET status = 'pending',
+          claimed_by = NULL,
+          lease_expires_at = NULL,
+          processed_at = NULL,
+          processed_by = NULL,
+          skipped_at = NULL,
+          skipped_by = NULL,
+          terminal_reason = NULL,
+          updated_at = now(),
+          payload = jsonb_set(payload, '{status}', to_jsonb('pending'::text), true)
+      WHERE project = ${this.project}
+        AND tenant_id = ${this.tenantId}
+        AND queue_name = ${this.queueName}
+        AND item_id = ${id}
+      RETURNING item_id
+    `;
+    return rows[0] ? { id, from: 'postgres' } : null;
+  }
+
+  async queueStats() {
+    await this.ensureSchema();
+    const rows = await this.sql`
+      SELECT status, COUNT(*)::int AS count
+      FROM construct_queue_items
+      WHERE project = ${this.project}
+        AND tenant_id = ${this.tenantId}
+        AND queue_name = ${this.queueName}
+      GROUP BY status
+    `;
+    const byStatus = {
+      pending: 0,
+      claimed: 0,
+      processed: 0,
+      skipped: 0,
+      awaiting_approval: 0,
+      dead_letter: 0,
+    };
+    for (const row of rows) {
+      if (Object.hasOwn(byStatus, row.status)) byStatus[row.status] = Number(row.count || 0);
+    }
+    return {
+      project: this.project,
+      tenantId: this.tenantId,
+      queueName: this.queueName,
+      byStatus,
+      pending: byStatus.pending,
+      claimed: byStatus.claimed,
+      deadLetter: byStatus.dead_letter,
+      total: Object.values(byStatus).reduce((sum, n) => sum + n, 0),
+    };
+  }
+}

package/lib/reflect.mjs

@@ -14,6 +14,7 @@ import { KNOWLEDGE_ROOT, KNOWLEDGE_SUBDIRS, inferKnowledgeTarget } from './knowl
 import { extractSessionObservation } from './reflect/extractor.mjs';
 import { readContextState, contextSummaryLine } from './context-state.mjs';
 import { configDir } from './config/xdg.mjs';
+import { isMainModule } from './roots.mjs';
 
 const HOME = process.env.HOME || process.env.USERPROFILE;
 const USER_ENV_PATH = join(configDir(HOME), 'config.env');
@@ -253,7 +254,7 @@ function parseTranscript(path) {
 /**
  * CLI entry point for direct execution.
  */
-if (import.meta.url === `file://${process.argv[1]}`) {
+if (isMainModule(import.meta.url)) {
   const args = process.argv.slice(2);
   runReflectCli(args).catch((err) => {
     console.error(`Error: ${err.message}`);

package/lib/registry/assemble.mjs

@@ -1,12 +1,21 @@
 /**
  * lib/registry/assemble.mjs — Runtime merge of modular org files into registry v3.
  *
- * Walks specialists/org/{groups,teams,specialists,contracts,policies}, merges
- * .cx/org overlay fragments, and returns the assembled object for validation.
+ * Walks specialists/org/{groups,teams,specialists,contracts,policies}, then
+ * merges two user/project extension tiers on top, builtin -> user -> project
+ * (ADR-0052's precedence model, applied here to the org registry): a home-level
+ * custom org tree (~/.construct/org/**, construct-rf26.13 — a user's personal
+ * custom specialists/teams shared across all their projects), then the existing
+ * .cx/org project overlay (highest precedence). Later tiers win on id collision.
  */
 
 import fs from 'node:fs';
 import path from 'node:path';
+import { homeDir } from '../paths.mjs';
+
+function customOrgRoot() {
+  return path.join(homeDir(), '.construct', 'org');
+}
 
 function readJsonDir(dir) {
   const out = {};
@@ -66,6 +75,8 @@ export function orgDirMtime(rootDir) {
     }
   };
   walk(orgRoot);
+  const homeOrg = customOrgRoot();
+  if (fs.existsSync(homeOrg)) walk(homeOrg);
   const overlay = path.join(rootDir, '.cx', 'org');
   if (fs.existsSync(overlay)) walk(overlay);
   return max;
@@ -85,6 +96,21 @@ export function assembleRegistry(rootDir) {
   const contracts = readJsonDir(path.join(orgRoot, 'contracts'));
   const policies = readJsonDir(path.join(orgRoot, 'policies'));
 
+  const homeOrgRoot = customOrgRoot();
+  if (fs.existsSync(homeOrgRoot)) {
+    for (const [id, val] of Object.entries(readJsonDir(path.join(homeOrgRoot, 'groups')))) {
+      groups[id] = { ...groups[id], ...val };
+    }
+    for (const [id, val] of Object.entries(readJsonDir(path.join(homeOrgRoot, 'teams')))) {
+      squads[id] = { ...squads[id], ...val };
+    }
+    for (const [id, val] of Object.entries(readJsonDir(path.join(homeOrgRoot, 'specialists')))) {
+      specialists[id] = { ...specialists[id], ...val };
+    }
+    mergeOverlaySection(contracts, readJsonDir(path.join(homeOrgRoot, 'contracts')));
+    mergeOverlaySection(policies, readJsonDir(path.join(homeOrgRoot, 'policies')));
+  }
+
   if (fs.existsSync(overlayRoot)) {
     for (const [id, val] of Object.entries(readJsonDir(path.join(overlayRoot, 'groups')))) {
       groups[id] = { ...groups[id], ...val };

package/lib/registry/consolidation.mjs

@@ -9,6 +9,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { loadRegistry } from '../registry/loader.mjs';
+import { bindingForSpecialist } from '../roles/flavor-bindings.mjs';
 
 const MODULE_DIR = path.dirname(fileURLToPath(import.meta.url));
 const REPO_ROOT = path.resolve(MODULE_DIR, '..', '..');
@@ -81,12 +82,18 @@ export function triageBoundOrphans({ rootDir = REPO_ROOT } = {}) {
     } else if (base && profileRoles.has(base)) {
       category = 'B-composer';
       recommendation = `Profile role "${base}" — may load via profile overlay; verify before merge`;
+    } else if (base && bindingForSpecialist(base)?.specialistId) {
+      // Base name doesn't match a specialist's own name, but
+      // lib/roles/flavor-bindings.mjs still routes it onto a live anchor —
+      // reachable via prompt-composer under that anchor's identity.
+      category = 'B-composer';
+      recommendation = `Role flavor bound to ${bindingForSpecialist(base).specialistId} via lib/roles/flavor-bindings.mjs — reachable via prompt-composer; document in registry or bind explicitly`;
     } else if (skill.startsWith('roles/')) {
       category = 'C-merge';
       recommendation = 'Consider merging into parent roles/<base>.md or binding to specialist';
     } else if (skill.startsWith('docs/')) {
       category = 'A-bind';
-      recommendation = 'Bind to cx-docs-keeper or domain owner specialist';
+      recommendation = 'Bind to cx-operations or domain owner specialist';
     }
 
     items.push({ skill, category, recommendation });

package/lib/registry/custom-scaffold.mjs

@@ -0,0 +1,200 @@
+/**
+ * lib/registry/custom-scaffold.mjs — CLI-facing scaffolding for user-authored
+ * custom specialists and teams (construct-rf26.13).
+ *
+ * Writes into one of two extension tiers, both read back by
+ * lib/registry/assemble.mjs at the same precedence ADR-0052 establishes for
+ * provider manifests (builtin -> user -> project):
+ *   - "user"    ~/.construct/org/**   — usable across every project on the machine
+ *   - "project" <rootDir>/.cx/org/**  — git-tracked, highest precedence, scoped
+ *                                       to one project (the existing overlay
+ *                                       introduced by ADR-0046)
+ *
+ * Refuses to overwrite an existing file unless { force: true }, mirroring
+ * lib/specialists/scaffold.mjs's createSpecialistDraft convention. Validates
+ * with lib/registry/custom-schema.mjs before writing anything, so a scaffolded
+ * record is guaranteed registry-loadable the moment it lands on disk.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { homeDir } from '../paths.mjs';
+import { assembleRegistry } from './assemble.mjs';
+import { validateCustomSpecialist, validateCustomTeam } from './custom-schema.mjs';
+
+const ID_RE = /^[a-z][a-z0-9-]*$/;
+
+export function customOrgDir(scope, { rootDir = process.cwd() } = {}) {
+  if (scope === 'user') return path.join(homeDir(), '.construct', 'org');
+  return path.join(rootDir, '.cx', 'org');
+}
+
+function existingTeamIds(rootDir) {
+  try {
+    return Object.keys(assembleRegistry(rootDir).teams);
+  } catch {
+    return null;
+  }
+}
+
+function renderPromptStub({ id, role, description }) {
+  return [
+    `# cx-${id}`,
+    '',
+    `Role: ${role}`,
+    '',
+    description || 'TODO: describe this specialist\'s perspective and output format.',
+    '',
+    '## Anti-fabrication contract',
+    '',
+    'Every load-bearing claim cites a source the reader can re-verify. When a fact is not in the source, write `unknown` or `[unverified]`. See `rules/common/no-fabrication.md`.',
+    '',
+  ].join('\n');
+}
+
+/**
+ * Scaffold a custom specialist JSON record (+ a minimal prompt stub) into the
+ * requested tier. Throws with actionable, field-named errors on any failure.
+ * @returns {{ path: string, relPath: string, promptPath: string, record: object, scope: string }}
+ */
+export function createCustomSpecialist({
+  rootDir = process.cwd(),
+  scope = 'project',
+  id,
+  role,
+  description,
+  modelTier = 'standard',
+  reasoningEffort,
+  skills = [],
+  fence,
+  team,
+  teamId,
+  handoffCandidates = [],
+  claudeTools = 'Read,Grep,Glob,LS',
+  displayName,
+  force = false,
+} = {}) {
+  if (!id || !ID_RE.test(id)) {
+    throw new Error(`invalid specialist id "${id}" — use lowercase kebab-case (e.g. "widget-specialist")`);
+  }
+  if (scope !== 'user' && scope !== 'project') {
+    throw new Error(`invalid scope "${scope}" — use "user" or "project"`);
+  }
+
+  const orgDir = customOrgDir(scope, { rootDir });
+  const specialistsDir = path.join(orgDir, 'specialists');
+  const filePath = path.join(specialistsDir, `cx-${id}.json`);
+  if (fs.existsSync(filePath) && !force) {
+    throw new Error(`${filePath} already exists — pass force to overwrite`);
+  }
+
+  const resolvedTeam = team || teamId;
+  const knownTeams = existingTeamIds(rootDir);
+  if (resolvedTeam && knownTeams && !knownTeams.includes(resolvedTeam)) {
+    throw new Error(
+      `team "${resolvedTeam}" does not exist — create it first with \`construct team create ${resolvedTeam} --owner=${role || id}\`, ` +
+      `or reference one of: ${knownTeams.slice(0, 10).join(', ')}${knownTeams.length > 10 ? ', …' : ''}`,
+    );
+  }
+
+  const promptRelPath = path.posix.join(
+    path.relative(rootDir, orgDir).split(path.sep).join('/'),
+    'prompts',
+    `cx-${id}.md`,
+  );
+
+  const record = {
+    name: id,
+    displayName: displayName || description,
+    description,
+    role: role || id,
+    modelTier,
+    ...(reasoningEffort ? { reasoningEffort } : {}),
+    skills,
+    fence: fence || { allowedPaths: [] },
+    claudeTools,
+    promptFile: promptRelPath,
+    handoffCandidates,
+    team: resolvedTeam,
+    teamId: resolvedTeam,
+    internal: true,
+    custom: true,
+  };
+
+  const errors = validateCustomSpecialist(record, { rootDir, checkPromptFileExists: false });
+  if (errors.length) {
+    throw new Error(`custom specialist "${id}" failed validation:\n  ${errors.join('\n  ')}`);
+  }
+
+  const promptDir = path.join(orgDir, 'prompts');
+  const promptPath = path.join(rootDir, promptRelPath);
+  fs.mkdirSync(promptDir, { recursive: true });
+  if (!fs.existsSync(promptPath) || force) {
+    fs.writeFileSync(promptPath, renderPromptStub({ id, role: record.role, description }));
+  }
+
+  fs.mkdirSync(specialistsDir, { recursive: true });
+  fs.writeFileSync(filePath, JSON.stringify(record, null, 2) + '\n');
+
+  return { path: filePath, relPath: path.relative(rootDir, filePath), promptPath, record, scope };
+}
+
+/**
+ * Scaffold a custom team JSON record into the requested tier. Throws with
+ * actionable, field-named errors on any failure.
+ * @returns {{ path: string, relPath: string, record: object, scope: string }}
+ */
+export function createCustomTeam({
+  rootDir = process.cwd(),
+  scope = 'project',
+  id,
+  name,
+  owner,
+  roles,
+  specialists = [],
+  charter,
+  decisionRights = [],
+  forbiddenDecisions = [],
+  escalationPath,
+  contact = {},
+  groupId,
+  force = false,
+} = {}) {
+  if (!id || !ID_RE.test(id)) {
+    throw new Error(`invalid team id "${id}" — use lowercase kebab-case (e.g. "widget-team")`);
+  }
+  if (scope !== 'user' && scope !== 'project') {
+    throw new Error(`invalid scope "${scope}" — use "user" or "project"`);
+  }
+
+  const orgDir = customOrgDir(scope, { rootDir });
+  const teamsDir = path.join(orgDir, 'teams');
+  const filePath = path.join(teamsDir, `${id}.json`);
+  if (fs.existsSync(filePath) && !force) {
+    throw new Error(`${filePath} already exists — pass force to overwrite`);
+  }
+
+  const resolvedRoles = roles && roles.length ? roles : (owner ? [owner] : []);
+  const record = {
+    name: name || id,
+    owner,
+    roles: resolvedRoles,
+    specialists,
+    decisionRights,
+    forbiddenDecisions,
+    escalationPath: escalationPath && escalationPath.length ? escalationPath : [owner, 'orchestrator'].filter(Boolean),
+    charter,
+    contact,
+    ...(groupId ? { groupId } : {}),
+  };
+
+  const errors = validateCustomTeam({ id, ...record });
+  if (errors.length) {
+    throw new Error(`custom team "${id}" failed validation:\n  ${errors.join('\n  ')}`);
+  }
+
+  fs.mkdirSync(teamsDir, { recursive: true });
+  fs.writeFileSync(filePath, JSON.stringify(record, null, 2) + '\n');
+
+  return { path: filePath, relPath: path.relative(rootDir, filePath), record, scope };
+}