@geraldmaron/construct 1.4.2 → 1.5.0

package/lib/packs/cli.mjs

@@ -0,0 +1,144 @@
+/**
+ * lib/packs/cli.mjs — `construct pack` command surface (LMCP-E3).
+ *
+ * Subcommands:
+ *   list             Every pack discovered across builtin/user/project tiers
+ *                     (loader.mjs precedence merge), each annotated with its
+ *                     durable enabled state (enablement.mjs).
+ *   enable <id>      Validate the pack's on-disk manifest and record it as
+ *                     enabled in .cx/packs.json. Refuses — naming the exact
+ *                     validation error — on an incompatible compatVersion or
+ *                     any other manifest defect.
+ *   disable <id>     Remove the pack's enabled entry. Idempotent. Refuses to
+ *                     disable the core pack.
+ *   info <id>        Full manifest plus enabled state for one pack.
+ *
+ * `--json` on every subcommand emits a machine-readable payload; the text
+ * form is the human-readable default.
+ */
+
+import { loadAllPacks } from './loader.mjs';
+import { readEnablementState, isEnabled, enablePack, disablePack } from './enablement.mjs';
+
+function annotatedPacks({ rootDir, homeDir, packageRoot, env, deploymentMode }) {
+  const { packs, errors } = loadAllPacks({ rootDir, homeDir, packageRoot, env, deploymentMode });
+  const state = readEnablementState(rootDir);
+  const annotated = packs.map((p) => ({
+    id: p.id,
+    version: p.version,
+    tier: p._tier,
+    enabled: isEnabled(p.id, state, { packageRoot }),
+    manifestPath: p._manifestPath || p._packDir || null,
+  }));
+  return { packs: annotated, errors, state };
+}
+
+function runList({ rootDir, packageRoot, json }) {
+  const { packs, errors } = annotatedPacks({ rootDir, packageRoot });
+  if (json) {
+    process.stdout.write(JSON.stringify({ packs, errors }, null, 2) + '\n');
+    return 0;
+  }
+  process.stdout.write(`Packs (${packs.length}):\n`);
+  for (const p of packs) {
+    process.stdout.write(`  ${p.enabled ? '●' : '○'} ${p.id}@${p.version} [${p.tier}]${p.enabled ? ' (enabled)' : ''}\n`);
+  }
+  for (const e of errors) process.stdout.write(`  ! ${e}\n`);
+  return 0;
+}
+
+/**
+ * Splits a `<pack-id>[@version]` spec on the last '@', so a scoped id like
+ * '@fixture/sample' (no version) stays intact while '@fixture/sample@2.0.0'
+ * splits into id '@fixture/sample' and version '2.0.0'.
+ */
+function parsePackSpec(spec) {
+  const at = spec.lastIndexOf('@');
+  if (at <= 0) return { packId: spec, requestedVersion: undefined };
+  return { packId: spec.slice(0, at), requestedVersion: spec.slice(at + 1) };
+}
+
+function runEnable(args, { rootDir, packageRoot, json }) {
+  const id = args.find((a) => !a.startsWith('--'));
+  if (!id) {
+    process.stderr.write('Usage: construct pack enable <pack-id>[@version] [--json]\n');
+    return 1;
+  }
+  const { packId, requestedVersion } = parsePackSpec(id);
+
+  const result = enablePack(packId, { rootDir, packageRoot, requestedVersion });
+  if (json) {
+    process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+    return result.ok ? 0 : 1;
+  }
+  if (!result.ok) {
+    process.stderr.write(`✖ ${result.error}\n`);
+    return 1;
+  }
+  process.stdout.write(result.alreadyCore ? `✓ ${packId} is the core pack (always enabled)\n` : `✓ enabled ${packId}@${result.pack.version} [${result.tier}]\n`);
+  return 0;
+}
+
+function runDisable(args, { rootDir, packageRoot, json }) {
+  const id = args.find((a) => !a.startsWith('--'));
+  if (!id) {
+    process.stderr.write('Usage: construct pack disable <pack-id> [--json]\n');
+    return 1;
+  }
+  const result = disablePack(id, { rootDir, packageRoot });
+  if (json) {
+    process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+    return result.ok ? 0 : 1;
+  }
+  if (!result.ok) {
+    process.stderr.write(`✖ ${result.error}\n`);
+    return 1;
+  }
+  process.stdout.write(result.wasEnabled ? `✓ disabled ${id}\n` : `${id} was not enabled (no-op)\n`);
+  return 0;
+}
+
+function runInfo(args, { rootDir, packageRoot, json }) {
+  const id = args.find((a) => !a.startsWith('--'));
+  if (!id) {
+    process.stderr.write('Usage: construct pack info <pack-id> [--json]\n');
+    return 1;
+  }
+  const { packs: rawPacks } = loadAllPacks({ rootDir, packageRoot });
+  const pack = rawPacks.find((p) => p.id === id);
+  if (!pack) {
+    process.stderr.write(`pack not found: ${id}\n`);
+    return 1;
+  }
+  const state = readEnablementState(rootDir);
+  const enabled = isEnabled(id, state, { packageRoot });
+  const result = { ...pack, enabled, enabledDetail: state.enabled[id] || null };
+  if (json) {
+    process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+    return 0;
+  }
+  process.stdout.write(`${pack.id}@${pack.version} [${pack._tier}] ${enabled ? '(enabled)' : '(disabled)'}\n`);
+  if (pack.specialists) process.stdout.write(`  specialists: ${Object.keys(pack.specialists).length}\n`);
+  if (pack.prompts) process.stdout.write(`  prompts: ${Object.keys(pack.prompts).length}\n`);
+  if (pack.frameworks) process.stdout.write(`  frameworks: ${Object.keys(pack.frameworks).length}\n`);
+  return 0;
+}
+
+/**
+ * @param {string[]} args
+ * @param {{ rootDir: string, packageRoot?: string }} ctx
+ * @returns {number} exit code
+ */
+export function runPackCli(args, { rootDir, packageRoot } = {}) {
+  const sub = args[0];
+  const rest = args.slice(1);
+  const json = args.includes('--json');
+
+  if (sub === 'list') return runList({ rootDir, packageRoot, json });
+  if (sub === 'enable') return runEnable(rest, { rootDir, packageRoot, json });
+  if (sub === 'disable') return runDisable(rest, { rootDir, packageRoot, json });
+  if (sub === 'info') return runInfo(rest, { rootDir, packageRoot, json });
+
+  process.stderr.write(`Unknown pack subcommand: ${sub}. Available: list, enable, disable, info\n`);
+  return 1;
+}

package/lib/packs/core-pack.mjs

@@ -0,0 +1,112 @@
+/**
+ * lib/packs/core-pack.mjs — programmatic builtin core pack loader.
+ *
+ * Reads specialists/org/ directory structure and wraps it as the
+ * @construct/core pack. This is the builtin tier pack that provides
+ * all default specialists, teams, prompts, and reasoning frameworks
+ * (ADR-0062) shipped with Construct.
+ *
+ * `embedBindings` (LMCP-E4) ships default per-specialist provider read/
+ * search grants and write-proposal grants for the built-in specialists most
+ * likely to run embedded: cx-product-manager, cx-operations, cx-engineer.
+ * These are defaults only — a project may override them via a project-tier
+ * pack (.cx/packs) under the same specialist id.
+ */
+
+import { readFileSync, readdirSync, existsSync } from 'node:fs';
+import { join, dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import yaml from 'js-yaml';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const PACKAGE_ROOT = resolve(__dirname, '..', '..');
+
+const FRONTMATTER_RE = /^---\n([\s\S]*?)\n---\n?/;
+
+// Default per-specialist embed bindings (LMCP-E4). Read/search only — no
+// specialist gets an autonomous write; `proposals` names the write kinds a
+// specialist may propose, and every proposal still passes through
+// AuthorityGuard's approval-queued path before anything executes.
+const DEFAULT_EMBED_BINDINGS = Object.freeze({
+  'cx-product-manager': {
+    providers: [
+      { id: 'atlassian-jira', capabilities: ['read', 'search'] },
+      { id: 'atlassian-confluence', capabilities: ['read', 'search'] },
+    ],
+    proposals: ['atlassian-jira.createIssue'],
+  },
+  'cx-operations': {
+    providers: [
+      { id: 'atlassian-jira', capabilities: ['read', 'search'] },
+      { id: 'atlassian-confluence', capabilities: ['read', 'search'] },
+      { id: 'slack', capabilities: ['read', 'search'] },
+    ],
+    proposals: ['atlassian-jira.createIssue', 'slack.postMessage'],
+  },
+  'cx-engineer': {
+    providers: [
+      { id: 'github', capabilities: ['read', 'search'] },
+      { id: 'atlassian-jira', capabilities: ['read', 'search'] },
+    ],
+    proposals: ['github.createIssue'],
+  },
+});
+
+export function loadCorePack(rootDir = PACKAGE_ROOT) {
+  const orgDir = join(rootDir, 'specialists', 'org');
+  const specialistDir = join(orgDir, 'specialists');
+  const teamDir = join(orgDir, 'teams');
+  const frameworkDir = join(orgDir, 'frameworks');
+
+  const specialists = existsSync(specialistDir)
+    ? readdirSync(specialistDir).filter(f => f.endsWith('.json')).map(f => f.replace(/\.json$/, ''))
+    : [];
+
+  const teams = existsSync(teamDir)
+    ? readdirSync(teamDir).filter(f => f.endsWith('.json')).map(f => f.replace(/\.json$/, ''))
+    : [];
+
+  const prompts = {};
+  for (const specId of specialists) {
+    try {
+      const spec = JSON.parse(readFileSync(join(specialistDir, `${specId}.json`), 'utf8'));
+      if (spec.promptFile) prompts[specId] = spec.promptFile;
+    } catch {}
+  }
+
+  // frameworks map keys by frontmatter `id` (not filename) so a project-tier
+  // override in .cx/packs can declare the same id from a differently named
+  // file and still win under mergePackTiers/resolveFramework precedence.
+  const frameworks = {};
+  if (existsSync(frameworkDir)) {
+    for (const file of readdirSync(frameworkDir).filter(f => f.endsWith('.md'))) {
+      try {
+        const raw = readFileSync(join(frameworkDir, file), 'utf8');
+        const match = raw.match(FRONTMATTER_RE);
+        const fm = match ? yaml.load(match[1]) : null;
+        if (fm?.id) frameworks[fm.id] = join('specialists', 'org', 'frameworks', file);
+      } catch {}
+    }
+  }
+
+  // Only bind specialists actually present on disk — a stripped-down or
+  // customized org directory should not surface bindings for personas it
+  // doesn't ship.
+  const embedBindings = {};
+  for (const [specId, binding] of Object.entries(DEFAULT_EMBED_BINDINGS)) {
+    if (specialists.includes(specId)) embedBindings[specId] = binding;
+  }
+
+  return {
+    id: '@construct/core',
+    version: '0.0.0',
+    compatVersion: 1,
+    teams,
+    specialists,
+    prompts,
+    embedBindings,
+    frameworks,
+    _tier: 'builtin',
+    _sourceDir: orgDir,
+  };
+}

package/lib/packs/enablement.mjs

@@ -0,0 +1,187 @@
+/**
+ * lib/packs/enablement.mjs — durable pack enable/disable lifecycle (LMCP-E3).
+ *
+ * `loadAllPacks` (loader.mjs) merges every pack it finds on disk across the
+ * builtin/user/project tiers unconditionally — correct for authoring-time
+ * precedence resolution, but it means dropping a pack manifest into
+ * `.cx/packs/` makes it "configured" and already influencing prompt/framework
+ * resolution with no explicit operator action (the OTel lesson this bead is
+ * named for: configured is not enabled). This module adds an explicit,
+ * durable enablement layer on top without changing loadAllPacks' own
+ * semantics — existing callers merging all discovered packs (precedence
+ * tests, `construct doctor`) are unaffected; a caller that wants
+ * enablement-gated packs calls `loadEnabledPacks` instead.
+ *
+ * State lives at `<rootDir>/.cx/packs.json`:
+ *   { "version": 1, "enabled": { "<packId>": { "version": "1.0.0", "enabledAt": "<ISO>", "tier": "project" } } }
+ *
+ * `@construct/core` (the programmatically-injected builtin foundation pack,
+ * see core-pack.mjs) is always enabled — it is not optional and carries no
+ * manifest file to enable/disable.
+ *
+ * `enablePack` refuses to enable a pack whose manifest fails validation —
+ * including a compatVersion that exceeds this runtime's PACK_COMPAT_VERSION —
+ * naming the exact validation error rather than half-enabling it.
+ */
+
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+
+import { loadAllPacks, resolvePackDirs } from './loader.mjs';
+import { validatePackManifest } from './validate.mjs';
+import { loadCorePack } from './core-pack.mjs';
+
+const STATE_VERSION = 1;
+
+export function resolveEnablementStatePath(rootDir = process.cwd()) {
+  return join(rootDir, '.cx', 'packs.json');
+}
+
+/**
+ * @param {string} [rootDir]
+ * @returns {{ version: number, enabled: Record<string, {version: string, enabledAt: string, tier: string}> }}
+ */
+export function readEnablementState(rootDir = process.cwd()) {
+  const statePath = resolveEnablementStatePath(rootDir);
+  if (!existsSync(statePath)) {
+    return { version: STATE_VERSION, enabled: {} };
+  }
+  try {
+    const parsed = JSON.parse(readFileSync(statePath, 'utf8'));
+    if (!parsed || typeof parsed !== 'object' || typeof parsed.enabled !== 'object' || parsed.enabled === null) {
+      return { version: STATE_VERSION, enabled: {} };
+    }
+    return { version: parsed.version || STATE_VERSION, enabled: parsed.enabled };
+  } catch {
+    return { version: STATE_VERSION, enabled: {} };
+  }
+}
+
+export function writeEnablementState(rootDir, state) {
+  const statePath = resolveEnablementStatePath(rootDir);
+  mkdirSync(dirname(statePath), { recursive: true });
+  writeFileSync(statePath, JSON.stringify({ version: state.version || STATE_VERSION, enabled: state.enabled || {} }, null, 2) + '\n', 'utf8');
+}
+
+/**
+ * The core pack ships with Construct and is always enabled — it has no
+ * manifest file on disk to toggle and every specialist/framework/prompt it
+ * carries is the foundation every deployment mode depends on.
+ */
+export function isCorePackId(packId, packageRoot) {
+  return packId === loadCorePack(packageRoot).id;
+}
+
+export function isEnabled(packId, state, { packageRoot } = {}) {
+  if (isCorePackId(packId, packageRoot)) return true;
+  return Boolean(state?.enabled?.[packId]);
+}
+
+/**
+ * Scans the three tier directories (project, user, builtin — highest
+ * precedence first) for a `pack.manifest.json` whose parsed `id` matches.
+ * Returns the parsed manifest alongside its tier/path even when validation
+ * would reject it, so `enablePack` can name the exact validation failure
+ * instead of reporting a generic "not found".
+ *
+ * @returns {{ tier: string, packDir: string, manifestPath: string, parsed: object } | null}
+ */
+function findPackManifest(packId, { rootDir, homeDir } = {}) {
+  const dirs = resolvePackDirs({ rootDir, homeDir });
+  const tiers = [
+    { tier: 'project', dir: dirs.project },
+    { tier: 'user', dir: dirs.user },
+    { tier: 'builtin', dir: dirs.builtin },
+  ];
+
+  for (const { tier, dir } of tiers) {
+    if (!existsSync(dir)) continue;
+    const entries = readdirSync(dir, { withFileTypes: true }).filter((e) => e.isDirectory());
+    for (const entry of entries) {
+      const packDir = join(dir, entry.name);
+      const manifestPath = join(packDir, 'pack.manifest.json');
+      if (!existsSync(manifestPath)) continue;
+      let parsed;
+      try {
+        parsed = JSON.parse(readFileSync(manifestPath, 'utf8'));
+      } catch {
+        continue;
+      }
+      if (parsed?.id === packId) {
+        return { tier, packDir, manifestPath, parsed };
+      }
+    }
+  }
+  return null;
+}
+
+/**
+ * @param {string} packId
+ * @param {{ rootDir?: string, homeDir?: string, packageRoot?: string, requestedVersion?: string, knownProviders?: object }} [opts]
+ * @returns {{ ok: true, pack: object, tier: string, alreadyCore?: true } | { ok: false, error: string }}
+ */
+export function enablePack(packId, opts = {}) {
+  const { rootDir = process.cwd(), homeDir, packageRoot, requestedVersion, knownProviders } = opts;
+
+  if (isCorePackId(packId, packageRoot)) {
+    return { ok: true, alreadyCore: true, pack: { id: packId }, tier: 'builtin' };
+  }
+
+  const found = findPackManifest(packId, { rootDir, homeDir });
+  if (!found) {
+    const dirs = resolvePackDirs({ rootDir, homeDir });
+    return { ok: false, error: `pack '${packId}' not found in any builtin/user/project pack directory (looked under ${dirs.project}, ${dirs.user}, ${dirs.builtin})` };
+  }
+
+  if (requestedVersion && found.parsed.version !== requestedVersion) {
+    return { ok: false, error: `pack '${packId}' on disk is version ${found.parsed.version}, requested ${requestedVersion}` };
+  }
+
+  const result = validatePackManifest(found.parsed, { filePath: found.manifestPath, knownProviders });
+  if (!result.valid) {
+    return { ok: false, error: `pack '${packId}' failed validation: ${result.errors.join('; ')}` };
+  }
+
+  const state = readEnablementState(rootDir);
+  state.enabled[packId] = { version: found.parsed.version, enabledAt: new Date().toISOString(), tier: found.tier };
+  writeEnablementState(rootDir, state);
+
+  return { ok: true, pack: found.parsed, tier: found.tier };
+}
+
+/**
+ * Idempotent — disabling an already-disabled (or never-enabled) pack still
+ * returns ok:true. The core pack cannot be disabled (ADR-0055 foundation tier).
+ *
+ * @param {string} packId
+ * @param {{ rootDir?: string, packageRoot?: string }} [opts]
+ * @returns {{ ok: true, wasEnabled: boolean } | { ok: false, error: string }}
+ */
+export function disablePack(packId, opts = {}) {
+  const { rootDir = process.cwd(), packageRoot } = opts;
+  if (isCorePackId(packId, packageRoot)) {
+    return { ok: false, error: `pack '${packId}' is the core pack and cannot be disabled` };
+  }
+  const state = readEnablementState(rootDir);
+  const wasEnabled = Boolean(state.enabled[packId]);
+  delete state.enabled[packId];
+  writeEnablementState(rootDir, state);
+  return { ok: true, wasEnabled };
+}
+
+/**
+ * Enablement-gated counterpart to `loadAllPacks` — same merge/precedence,
+ * filtered to only the core pack plus whatever the durable state marks
+ * enabled. Consumers that must not act on a merely-configured-but-unenabled
+ * pack (prompt/framework resolution, embed bindings) should call this
+ * instead of loadAllPacks directly.
+ *
+ * @param {object} opts  same shape as loadAllPacks' opts
+ * @returns {{packs: object[], errors: string[], state: object}}
+ */
+export function loadEnabledPacks(opts = {}) {
+  const { packs, errors } = loadAllPacks(opts);
+  const state = readEnablementState(opts.rootDir);
+  const filtered = packs.filter((p) => isEnabled(p.id, state, { packageRoot: opts.packageRoot }));
+  return { packs: filtered, errors, state };
+}

package/lib/packs/index.mjs

@@ -0,0 +1,23 @@
+/**
+ * lib/packs/index.mjs — public API for the pack manifest system.
+ *
+ * Re-exports all symbols from the five pack sub-modules so consumers
+ * can import from a single entry point:
+ *
+ *   import { validatePackManifest, loadAllPacks, PACK_REQUIRED_FIELDS } from './packs/index.mjs';
+ */
+
+export {
+  PACK_REQUIRED_FIELDS, PACK_OPTIONAL_FIELDS, PACK_COMPAT_VERSION,
+  PACK_ID_RE, PACK_SOURCE_TIERS,
+} from './manifest-schema.mjs';
+
+export { validatePackManifest } from './validate.mjs';
+
+export { validatePackPrompts, resolvePersonaPrompt } from './prompts.mjs';
+
+export { loadCorePack } from './core-pack.mjs';
+
+export {
+  loadPacksFromDir, mergePackTiers, resolvePackDirs, loadAllPacks,
+} from './loader.mjs';

package/lib/packs/loader.mjs

@@ -0,0 +1,176 @@
+/**
+ * lib/packs/loader.mjs — pack manifest directory loader and merger.
+ *
+ * Three manifest tiers exist: builtin (shipped with Construct), user (in
+ * ~/.config/construct/packs/), and project (in .cx/packs/). Project packs
+ * take highest precedence; user packs override builtin. The core pack is
+ * programmatically injected at the builtin tier via loadCorePack().
+ *
+ * `loadPacksFromDir` reads every subdirectory containing pack.manifest.json
+ * and validates each one. `mergePackTiers` merges the three tiers by id.
+ * `resolvePackDirs` returns the canonical paths for each tier.
+ * `loadAllPacks` is a convenience that loads from all tiers.
+ *
+ * Prompt validation (LMCP-E2): in team/enterprise deployment mode a pack whose
+ * declared prompt files are missing or lack valid frontmatter is rejected at
+ * load time — the error names the missing file — rather than letting the
+ * worker discover the gap mid-run and silently substitute a generic persona.
+ * Solo mode does not hard-fail here; the worker records the miss as a visible
+ * degraded fallback instead (lib/orchestration/worker.mjs).
+ *
+ * embedBindings validation (LMCP-E4): every pack's `embedBindings` block is
+ * cross-checked against the builtin extension manifests (lib/extensions) so
+ * a binding naming an unknown provider id or an undeclared capability fails
+ * pack validation with a path, rather than the authority guard discovering
+ * the gap at proposal time.
+ */
+
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { validatePackManifest } from './validate.mjs';
+import { validatePackPrompts } from './prompts.mjs';
+import { loadCorePack } from './core-pack.mjs';
+import { getDeploymentMode } from '../deployment-mode.mjs';
+import { loadManifestsFromDir, resolveManifestDirs } from '../extensions/loader.mjs';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const PACKAGE_ROOT = resolve(__dirname, '..', '..');
+
+const PROMPT_HARD_FAIL_MODES = new Set(['team', 'enterprise']);
+
+/**
+ * Load builtin extension manifests keyed by id, for embedBindings
+ * cross-validation. Only the builtin tier is consulted — the same set every
+ * `construct doctor` / pack loader run sees, independent of project overrides.
+ */
+function loadKnownProviderManifests(packageRoot) {
+  const { builtin } = resolveManifestDirs({ rootDir: packageRoot });
+  const { manifests } = loadManifestsFromDir(builtin);
+  const byId = {};
+  for (const m of manifests) byId[m.id] = m;
+  return byId;
+}
+
+export function loadPacksFromDir(packsBaseDir, opts = {}) {
+  const packs = [];
+  const errors = [];
+
+  if (!existsSync(packsBaseDir)) {
+    return { packs, errors };
+  }
+
+  let entries;
+  try {
+    entries = readdirSync(packsBaseDir, { withFileTypes: true });
+  } catch (err) {
+    errors.push(`${packsBaseDir}: failed to read directory (${err.message})`);
+    return { packs, errors };
+  }
+
+  const packDirs = entries.filter(e => e.isDirectory()).map(e => join(packsBaseDir, e.name)).sort();
+  const deploymentMode = opts.deploymentMode || getDeploymentMode(opts.env);
+  const packageRoot = opts.packageRoot || PACKAGE_ROOT;
+  const knownProviders = opts.knownProviders || loadKnownProviderManifests(packageRoot);
+
+  for (const packDir of packDirs) {
+    const manifestPath = join(packDir, 'pack.manifest.json');
+    if (!existsSync(manifestPath)) continue;
+
+    let parsed;
+    try {
+      parsed = JSON.parse(readFileSync(manifestPath, 'utf8'));
+    } catch (err) {
+      errors.push(`${manifestPath}: failed to parse JSON (${err.message})`);
+      continue;
+    }
+
+    const result = validatePackManifest(parsed, { filePath: manifestPath, strict: opts.strict, knownProviders });
+    if (!result.valid) {
+      errors.push(...result.errors);
+      continue;
+    }
+
+    if (PROMPT_HARD_FAIL_MODES.has(deploymentMode)) {
+      const promptResult = validatePackPrompts({ ...parsed, _packDir: packDir }, { packageRoot });
+      if (!promptResult.valid) {
+        errors.push(...promptResult.errors.map((e) => `${manifestPath}: ${e}`));
+        continue;
+      }
+    }
+
+    packs.push({ ...parsed, _tier: opts.tier || 'unknown', _manifestPath: manifestPath, _packDir: packDir });
+  }
+
+  return { packs, errors };
+}
+
+export function mergePackTiers(builtin = [], user = [], project = []) {
+  const map = new Map();
+
+  for (const p of builtin) map.set(p.id, p);
+  for (const p of user) map.set(p.id, p);
+  for (const p of project) map.set(p.id, p);
+
+  return [...map.values()];
+}
+
+export function resolvePackDirs({ rootDir, homeDir } = {}) {
+  const home = homeDir ?? (process.env.HOME || process.env.USERPROFILE || '');
+
+  return {
+    builtin: join(PACKAGE_ROOT, 'lib', 'packs', 'manifests'),
+    user: join(home, '.config', 'construct', 'packs'),
+    project: join(rootDir || process.cwd(), '.cx', 'packs'),
+  };
+}
+
+export function loadAllPacks(opts = {}) {
+  const dirs = resolvePackDirs(opts);
+  const allErrors = [];
+  const deploymentMode = opts.deploymentMode || getDeploymentMode(opts.env);
+  const packageRoot = opts.packageRoot || PACKAGE_ROOT;
+  const knownProviders = opts.knownProviders || loadKnownProviderManifests(packageRoot);
+
+  const builtinResult = loadPacksFromDir(dirs.builtin, { ...opts, tier: 'builtin', deploymentMode, packageRoot, knownProviders });
+  allErrors.push(...builtinResult.errors);
+
+  const userResult = loadPacksFromDir(dirs.user, { ...opts, tier: 'user', deploymentMode, packageRoot, knownProviders });
+  allErrors.push(...userResult.errors);
+
+  const projectResult = loadPacksFromDir(dirs.project, { ...opts, tier: 'project', deploymentMode, packageRoot, knownProviders });
+  allErrors.push(...projectResult.errors);
+
+  const corePack = loadCorePack(packageRoot);
+  let builtinPacks = [...builtinResult.packs, corePack];
+
+  // The core pack ships with Construct and is not read from a manifest file,
+  // bypassing loadPacksFromDir's validation loop above; the same hard-fail
+  // check still applies under team/enterprise, naming the missing file. The
+  // same is true of embedBindings — validated explicitly here so an unknown
+  // provider id or undeclared capability in the core pack's own bindings
+  // fails loudly instead of silently granting excess authority.
+  if (PROMPT_HARD_FAIL_MODES.has(deploymentMode)) {
+    const coreResult = validatePackPrompts(corePack, { packageRoot });
+    if (!coreResult.valid) {
+      allErrors.push(...coreResult.errors.map((e) => `${corePack._sourceDir || '@construct/core'}: ${e}`));
+      builtinPacks = builtinResult.packs;
+    }
+  }
+
+  if (corePack.embedBindings) {
+    const coreBindingResult = validatePackManifest(
+      { id: corePack.id, version: corePack.version, compatVersion: corePack.compatVersion, embedBindings: corePack.embedBindings },
+      { filePath: corePack._sourceDir || '@construct/core', knownProviders }
+    );
+    if (!coreBindingResult.valid) {
+      allErrors.push(...coreBindingResult.errors);
+      builtinPacks = builtinPacks.filter((p) => p.id !== corePack.id);
+    }
+  }
+
+  const merged = mergePackTiers(builtinPacks, userResult.packs, projectResult.packs);
+
+  return { packs: merged, errors: allErrors };
+}