showdar-skills 0.7.0 → 0.8.0

package/CHANGELOG.md

@@ -4,6 +4,37 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
+## [0.8.0]
+
+### Added
+
+- Local extension packs: static declarative directories (`pack.json` metadata only, no content hash) installed from a local directory or workspace-relative path.
+- Custom workflows composed from built-in primitive stages (`vendor-name` IDs), with canonical skip reasons/policies and the frozen completion contract.
+- Immutable deterministic extension catalog snapshots (`createExtensionCatalog`): no global registry, input-order independent, duplicate/collision rejecting.
+- Pack-local and project-local profiles; the six built-in profiles remain primitive-only and immutable.
+- User-owned `.showdar/overrides.json` for descriptions, discovery hints, guidance, custom-workflow policy refinement, and new project profiles.
+- CLI: `showdar add-pack <path>`, `showdar remove-pack <name>`, `showdar add-workflow <path>`, `showdar init --pack <path>`, `showdar list --extensions`.
+- Full-tree pack hashing: Showdar computes SHA-256 over the validated source tree at install and records it in `.showdar.json` (`extensions.packs[].hash`); docs-only edits change the hash as source identity, not as a behavior claim.
+- Opt-in custom workflow evaluation (`npm run eval:custom-workflows`); never part of `npm run eval` or the release gate.
+
+### Changed
+
+- Workflow-state APIs accept an optional explicit extension-catalog context; omitted context preserves built-in behavior exactly. State schema stays `schemaVersion: 1`.
+- Trace projection accepts `input.extensionCatalog` as validation context only; event types, envelope, and ordering are unchanged.
+- Manifest v2 gains an optional additive `extensions` object (`packs[]`, `customWorkflows[]`, `overrides` metadata). Existing manifests without it remain valid.
+
+### Security
+
+- Built-in workflow policy (stages, required stages, skips, completion, identity) and built-in profile definitions are protected and non-overrideable.
+- Recursive structured authority-key rejection (`primaryCapability`, `authorizedAction`, `mutationPermission`, `routeAuthority` and all canonical `FORBIDDEN_AUTHORITY_KEYS`); ordinary prose is not censored.
+- Path/symlink/ownership protection on pack install, removal, and override reads; foreign files are never silently overwritten or deleted.
+- Local-only source model: no network, Git, npm/registry, or executable hooks. Tarball, URL, and Git pack sources are rejected in 0.8.
+- Extensions cannot create capabilities, grant authority, modify Phase 6G, mutate built-ins, or execute code.
+
+### Migration
+
+- No migration required. Existing 0.7 installs, manifests (v2), checkpoints (schemaVersion 1), profiles, and adapters work unchanged. Extensions and overrides are opt-in; no mandatory action for existing users.
+
 ## [0.7.0]
 
 ### Added

package/MIGRATION.md

@@ -1,3 +1,23 @@
+# Migrating to 0.8.0
+
+0.8.0 adds local declarative extensibility (extension packs, custom
+workflows, user-owned project overrides) over the unchanged 0.7
+runtime. No user action is required.
+
+- Existing 0.7 installs and configs remain valid: manifest stays
+  version 2 (the `extensions` object is optional and additive),
+  workflow state stays schemaVersion 1, and existing checkpoints remain
+  valid.
+- Built-in workflows (`showdar-feature`, `showdar-bugfix`,
+  `showdar-release`, `showdar-incident`), the six built-in profiles,
+  adapters, and Phase 6G authority are unchanged.
+- Extensions are opt-in: `add-pack`, `add-workflow`, `init --pack`,
+  `list --extensions`. Project overrides in `.showdar/overrides.json`
+  are user-owned; Showdar reads and validates the file but never
+  rewrites or deletes it.
+- Pack sources in 0.8 are local directories/workspace paths only;
+  tarball, URL, Git, and npm/registry sources are rejected.
+
 # Migrating to 0.7.0
 
 0.7.0 adds deterministic workflow trace projection

package/README.md

@@ -557,6 +557,64 @@ is idempotent, preserves the configured profile, supports `--ai`/`--scope`
 overrides, and refuses to overwrite a foreign same-name skill directory that
 Showdar does not own.
 
+## Extensions (0.8.0)
+
+Extension packs are local, static, declarative directories installed from a
+local directory or workspace-relative path. A pack carries `pack.json`
+metadata (name, version, skills, workflows, pack-local profiles), skill
+directories, custom workflow definitions, and docs. Packs contain no
+executable hooks, lifecycle scripts, or remote code.
+
+```bash
+showdar add-pack ../acme-pack
+showdar list --extensions
+showdar remove-pack acme
+```
+
+Pack skill IDs use the `vendor/skill` namespace (for example,
+`acme/lint`); the `showdar-` prefix is reserved for built-ins. Skill
+`domains` are lowercase kebab-case discovery hints only (at most 8 per
+skill) — they never create capabilities, routes, or authority.
+
+Custom workflows compose built-in primitive stages under a `vendor-name`
+ID (for example, `acme-release`). Stages, skip rules, and completion
+policy follow the same frozen contracts as built-in workflows; custom
+workflows cannot define new primitives, authority, evidence kinds, or
+state schemas. Workflow state remains `schemaVersion: 1` and the trace
+projection is unchanged.
+
+```bash
+showdar add-workflow ./workflows/acme-release.json
+showdar init --pack ../acme-pack
+```
+
+Project overrides live in the user-owned `.showdar/overrides.json` file:
+skill descriptions, discovery hints, advisory guidance text, custom
+workflow policy refinement, and new project-owned profiles. Showdar reads
+and validates the file but never rewrites or deletes it; built-in
+workflow semantics and the six built-in profiles cannot be overridden.
+Pack-local profiles select pack-owned skills and workflows only.
+
+Showdar computes a full-tree SHA-256 over the validated pack source at
+install and records it in `.showdar.json` (`extensions.packs[].hash`).
+The hash is source-tree identity — a docs-only edit changes it without
+implying any behavior change. Drift means the source tree differs from
+the recorded installation source.
+
+Extensions cannot create capabilities, grant authority, modify Phase 6G,
+change built-in workflow semantics or profiles, or execute arbitrary
+code. Supported sources are local directories and workspace-relative
+paths; tarball, URL, Git, and npm/registry sources are rejected in 0.8.
+
+Opt-in custom workflow evaluation (never part of the release gate):
+
+```bash
+node scripts/generate-custom-eval-fixture.mjs
+node scripts/custom-workflows-eval.mjs \
+  --scenarios .tmp/custom-eval-fixture/custom-scenarios \
+  --pack .tmp/custom-eval-fixture/acme-pack/pack.json
+```
+
 ## Routing
 
 Showdar routes each request through progressive disclosure: the host discovers
@@ -591,7 +649,11 @@ Product behavior notes:
 ```bash
 showdar init [--scope <project|global>] --ai <target> --profile <profile>
 showdar add <skill> [--ai <target>] [--scope <project|global>]
+showdar add-pack <local-path>
+showdar remove-pack <name>
+showdar add-workflow <local-path>
 showdar list
+showdar list --extensions
 showdar status [--scope <project|global>]
 showdar doctor [--scope <project|global>]
 showdar validate

package/bin/showdar.js

@@ -4,7 +4,7 @@ import { homedir } from 'node:os';
 import { readFile } from 'node:fs/promises';
 import { fileURLToPath } from 'node:url';
 import { AI_TARGETS, PRIMITIVE_COUNT, PROFILE_ALIASES, PROFILES, SKILLS, TOTAL_COUNT, WORKFLOW_COUNT, canonicalProfile, isDeprecatedProfile, resolveProfile } from '../src/catalog.js';
-import { addSkill, globalManifestPath, initGlobal, initProject, inspectGlobal, inspectProject, removeGlobal, removeProject } from '../src/project.js';
+import { addPack, addSkill, addWorkflow, globalManifestPath, initGlobal, initProject, inspectGlobal, inspectProject, listExtensions, removeGlobal, removePack, removeProject } from '../src/project.js';
 import { validateRepository } from '../src/validate.js';
 
 const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
@@ -43,7 +43,7 @@ function printHelp(version, command = null) {
     console.log(`Showdar Skills ${version}\n\nUsage:\n  showdar add <skill> [--ai <universal|codex|opencode|cursor|claude>] [--scope <project|global>]\n\nExamples:\n  showdar add debug\n  showdar add showdar-security\n  showdar add test --ai cursor\n  showdar add review --scope global --ai claude\n\nDefault scope: project. Default AI target: universal, or the configured .showdar.json value when present.`);
     return;
   }
-  console.log(`Showdar Skills ${version}\n\nUsage:\n  showdar init ${scopeUsage} [--profile <name>] [--ai <universal|codex|opencode|cursor|claude|all>]\n  showdar add <skill> [--ai <universal|codex|opencode|cursor|claude>] [--scope <project|global>]\n  showdar status ${scopeUsage}\n  showdar doctor ${scopeUsage}\n  showdar validate\n  showdar list\n  showdar remove ${scopeUsage}\n\nDefaults: scope project, profile full, AI target universal.\nProfiles: ${Object.keys(PROFILES).join(', ')}\nDeprecated aliases: ${Object.entries(PROFILE_ALIASES).map(([alias, target]) => `${alias} -> ${target}`).join(', ')}\nAI targets: ${AI_TARGETS.join(', ')}`);
+  console.log(`Showdar Skills ${version}\n\nUsage:\n  showdar init ${scopeUsage} [--profile <name>] [--ai <universal|codex|opencode|cursor|claude|all>] [--pack <local-path>]\n  showdar add <skill> [--ai <universal|codex|opencode|cursor|claude>] [--scope <project|global>]\n  showdar add-pack <local-path>\n  showdar remove-pack <name>\n  showdar add-workflow <local-path>\n  showdar status ${scopeUsage}\n  showdar doctor ${scopeUsage}\n  showdar validate\n  showdar list [--extensions]\n  showdar remove ${scopeUsage}\n\nExtension packs accept local directories/workspace paths only; tarball, URL, Git, and registry sources are rejected.\n\nDefaults: scope project, profile full, AI target universal.\nProfiles: ${Object.keys(PROFILES).join(', ')}\nDeprecated aliases: ${Object.entries(PROFILE_ALIASES).map(([alias, target]) => `${alias} -> ${target}`).join(', ')}\nAI targets: ${AI_TARGETS.join(', ')}`);
 }
 
 async function main() {
@@ -62,11 +62,44 @@ async function main() {
   const scope = ['init', 'status', 'doctor', 'remove', 'add'].includes(command) ? scopeAfter(args) : null;
 
   if (command === 'list') {
+    if (args.includes('--extensions')) {
+      const result = await listExtensions({ cwd: projectRoot });
+      console.log('Packs:');
+      for (const pack of result.packs) console.log(`  ${pack.name}@${pack.version}  ${pack.hash}`);
+      console.log('Custom workflows:');
+      for (const workflow of result.customWorkflows) console.log(`  ${workflow.id}  [${workflow.source}]  ${workflow.path}`);
+      console.log(`Project overrides: ${result.overrides.present ? result.overrides.status : 'absent'}`);
+      return;
+    }
     console.log(`Profiles: ${Object.keys(PROFILES).join(', ')}\nDeprecated aliases: ${Object.entries(PROFILE_ALIASES).map(([alias, target]) => `${alias} -> ${target}`).join(', ')}\n\nSkills:`);
     for (const skill of SKILLS) console.log(`  ${skill.id}  [${skill.domain}]  ${skill.description}`);
     return;
   }
 
+  if (command === 'add-pack') {
+    const packSource = args[1];
+    if (!packSource) throw new Error('Pack source is required. Usage: showdar add-pack <local-path>');
+    const result = await addPack({ cwd: projectRoot, source: packSource, packageVersion: version });
+    console.log(`Showdar pack added.\nPack: ${result.pack}\nFiles: ${result.files}\nHash: ${result.hash}\nPath: ${result.destination}`);
+    return;
+  }
+
+  if (command === 'remove-pack') {
+    const packName = args[1];
+    if (!packName) throw new Error('Pack name is required. Usage: showdar remove-pack <name>');
+    await removePack({ cwd: projectRoot, name: packName });
+    console.log(`Showdar pack removed: ${packName}`);
+    return;
+  }
+
+  if (command === 'add-workflow') {
+    const workflowSource = args[1];
+    if (!workflowSource) throw new Error('Workflow source is required. Usage: showdar add-workflow <local-path>');
+    const result = await addWorkflow({ cwd: projectRoot, source: workflowSource });
+    console.log(`Showdar workflow added.\nWorkflow: ${result.workflow}\nPath: ${result.path}`);
+    return;
+  }
+
   if (command === 'validate') {
     const result = await validateRepository(packageRoot);
     if (result.ok) console.log(`Showdar validation OK (${PRIMITIVE_COUNT} primitives, ${WORKFLOW_COUNT} workflows, ${TOTAL_COUNT} total).`);
@@ -86,9 +119,15 @@ async function main() {
     const ai = valueAfter(args, '--ai', 'universal');
     const skillIds = resolveProfile(requestedProfile);
     if (isDeprecatedProfile(requestedProfile)) console.warn(`Warning: profile "${requestedProfile}" is deprecated; use "${profile}".`);
+    const packSource = valueAfter(args, '--pack', null);
+    if (packSource && scope === 'global') throw new Error('--pack is only supported with project scope in 0.8.');
     const result = scope === 'global'
       ? await initGlobal({ homeRoot: homedir(), packageRoot, profile, ai, skillIds, packageVersion: version })
       : await initProject({ projectRoot, packageRoot, profile, ai, skillIds, packageVersion: version });
+    if (packSource) {
+      const pack = await addPack({ cwd: projectRoot, source: packSource, packageVersion: version });
+      console.log(`Pack: ${pack.pack}@${pack.version ?? ''}  Hash: ${pack.hash}`);
+    }
     console.log(`Showdar Skills installed.\nScope: ${scope}\nProfile: ${profile}\nAI: ${ai}\nTargets: ${result.targets.join(', ')}\nSkills: ${result.skills}\nOpenCode commands: ${result.commands}`);
     if (scope === 'project') {
       console.log(`Requested: ${result.requestedSkills}\nInstalled in project: ${result.installedSkills}\nSatisfied by global: ${result.satisfiedByGlobal}\nSkipped duplicate copies: ${result.skippedDuplicates}`);

package/config/custom-workflow.schema.json

@@ -0,0 +1,57 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Showdar custom workflow definition",
+  "description": "Custom workflows compose built-in primitive skills only. Stages, skip enums, completion policy, and state schema are frozen contracts.",
+  "type": "object",
+  "required": ["id", "stages"],
+  "additionalProperties": false,
+  "properties": {
+    "id": { "type": "string", "pattern": "^[a-z][a-z0-9]*-[a-z][a-z0-9-]*$" },
+    "description": { "type": "string", "minLength": 30 },
+    "stages": {
+      "type": "array",
+      "minItems": 1,
+      "uniqueItems": true,
+      "items": { "type": "string", "pattern": "^showdar-[a-z][a-z0-9-]*$" }
+    },
+    "allowedSkips": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["stage", "reason", "policy", "evidence"],
+        "additionalProperties": false,
+        "properties": {
+          "stage": { "type": "string", "pattern": "^showdar-[a-z][a-z0-9-]*$" },
+          "reason": { "enum": ["behavior-defined", "local-low-risk", "no-ux-decision", "known-root-cause", "readiness-only", "no-ops-authority", "no-security-risk"] },
+          "policy": { "enum": ["adaptive-skip", "known-root-cause", "readiness-only", "no-ops-authority", "no-security-risk", "behavior-defined", "local-low-risk", "no-ux-decision"] },
+          "evidence": { "type": "array", "items": { "type": "string" } }
+        }
+      }
+    },
+    "requiredStages": {
+      "type": "array",
+      "items": { "type": "string", "pattern": "^showdar-[a-z][a-z0-9-]*$" }
+    },
+    "completionPolicy": {
+      "type": "object",
+      "required": ["allSelectedStagesAccounted", "noBlockers", "requiredVerificationSatisfied", "noNegativeEvidence"],
+      "additionalProperties": false,
+      "properties": {
+        "allSelectedStagesAccounted": { "type": "boolean", "const": true },
+        "noBlockers": { "type": "boolean", "const": true },
+        "requiredVerificationSatisfied": { "type": "boolean", "const": true },
+        "noNegativeEvidence": { "type": "boolean", "const": true }
+      }
+    },
+    "workflowStateCompat": {
+      "type": "object",
+      "required": ["schemaVersion", "selectableStages", "skipRules"],
+      "additionalProperties": false,
+      "properties": {
+        "schemaVersion": { "const": 1 },
+        "selectableStages": { "type": "array", "items": { "type": "string" } },
+        "skipRules": { "type": "object" }
+      }
+    }
+  }
+}

package/config/pack.schema.json

@@ -0,0 +1,54 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Showdar extension pack manifest",
+  "description": "Metadata only. pack.json MUST NOT contain the authoritative pack-content hash; Showdar computes hashTree() at install and records it in managed manifest state.",
+  "type": "object",
+  "required": ["name", "version", "skills"],
+  "additionalProperties": false,
+  "properties": {
+    "name": { "type": "string", "pattern": "^[a-z][a-z0-9-]*$" },
+    "version": { "type": "string", "pattern": "^\\d+\\.\\d+\\.\\d+$" },
+    "description": { "type": "string" },
+    "skills": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["id", "path"],
+        "additionalProperties": false,
+        "properties": {
+          "id": { "type": "string", "pattern": "^[a-z][a-z0-9]*/[a-z][a-z0-9-]*$" },
+          "path": { "type": "string", "minLength": 1 },
+          "description": { "type": "string" },
+          "domains": {
+            "type": "array",
+            "minItems": 1,
+            "maxItems": 8,
+            "items": { "type": "string", "pattern": "^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$", "minLength": 2, "maxLength": 40 }
+          }
+        }
+      }
+    },
+    "workflows": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["id", "path"],
+        "additionalProperties": false,
+        "properties": {
+          "id": { "type": "string", "pattern": "^[a-z][a-z0-9]*-[a-z][a-z0-9-]*$" },
+          "path": { "type": "string", "minLength": 1 }
+        }
+      }
+    },
+    "profiles": {
+      "type": "object",
+      "patternProperties": {
+        "^[a-z][a-z0-9-]*$": {
+          "type": "array",
+          "items": { "type": "string" }
+        }
+      },
+      "additionalProperties": false
+    }
+  }
+}

package/config/project-overrides.schema.json

@@ -0,0 +1,68 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Showdar project overrides (.showdar/overrides.json)",
+  "description": "User-owned project extension configuration. Built-in workflow policy and built-in profile definitions are protected and MUST NOT appear here as semantic overrides.",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "version": { "const": 1 },
+    "skillDescriptions": {
+      "type": "object",
+      "patternProperties": {
+        "^showdar-[a-z][a-z0-9-]*$": { "type": "string", "minLength": 1 }
+      },
+      "additionalProperties": false
+    },
+    "skillDomains": {
+      "type": "object",
+      "patternProperties": {
+        "^showdar-[a-z][a-z0-9-]*$": { "type": "string", "pattern": "^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$", "minLength": 2, "maxLength": 40 }
+      },
+      "additionalProperties": false
+    },
+    "workflowPolicy": {
+      "type": "object",
+      "description": "Custom workflows only. Built-in showdar-* workflow IDs are rejected.",
+      "patternProperties": {
+        "^[a-z][a-z0-9]*-[a-z][a-z0-9-]*$": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "stages": {
+              "type": "array",
+              "minItems": 1,
+              "uniqueItems": true,
+              "items": { "type": "string", "pattern": "^showdar-[a-z][a-z0-9-]*$" }
+            },
+            "skipRules": { "type": "object" },
+            "requiredStages": {
+              "type": "array",
+              "items": { "type": "string", "pattern": "^showdar-[a-z][a-z0-9-]*$" }
+            }
+          }
+        }
+      },
+      "additionalProperties": false
+    },
+    "guidance": {
+      "type": "object",
+      "description": "Separate advisory text. MUST NOT replace SKILL.md semantics or claim authority.",
+      "patternProperties": {
+        "^showdar-[a-z][a-z0-9-]*$": { "type": "string", "minLength": 1 }
+      },
+      "additionalProperties": false
+    },
+    "profiles": {
+      "type": "object",
+      "description": "New project-owned profiles only. MUST NOT mutate built-in profile definitions.",
+      "patternProperties": {
+        "^[a-z][a-z0-9-]*$": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "type": "string" }
+        }
+      },
+      "additionalProperties": false
+    }
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "showdar-skills",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Production-grade software engineering lifecycle skills for coding agents.",
   "type": "module",
   "bin": { "showdar": "./bin/showdar.js" },
@@ -11,12 +11,13 @@
     "eval": "npm run eval:retrieval && npm run eval:workflows",
     "eval:retrieval": "node scripts/retrieval-eval.mjs",
     "eval:workflows": "node scripts/workflow-observability-eval.mjs",
+    "eval:custom-workflows": "node scripts/custom-workflows-eval.mjs",
     "check": "npm test && npm run validate && npm pack --dry-run",
     "smoke": "node scripts/package-smoke.mjs",
     "release:check": "node scripts/check-release-version.mjs"
   },
   "engines": { "node": ">=20" },
-  "files": ["bin", "src", "skills", "commands", "router", "bundles", "profiles", "engine", "README.md", "LICENSE", "CHANGELOG.md", "MIGRATION.md"],
+  "files": ["bin", "src", "config", "skills", "commands", "router", "bundles", "profiles", "engine", "README.md", "LICENSE", "CHANGELOG.md", "MIGRATION.md"],
   "keywords": ["agent-skills", "coding-agents", "codex", "opencode", "claude-code", "software-engineering", "developer-tools", "requirements", "qa", "security", "devops", "workflow"],
   "license": "MIT",
   "repository": {

package/src/extension-catalog.js

@@ -0,0 +1,196 @@
+import { SKILLS, WORKFLOW_SKILLS, PROFILES, PROFILE_ALIASES, getSkill as getBuiltinSkill, getWorkflow as getBuiltinWorkflow } from './catalog.js';
+import { SELECTABLE_STAGES, SKIP_RULES, REQUIRED_STAGES } from './workflow-state.js';
+import {
+  validatePackManifest,
+  validateCustomWorkflowDoc,
+  validateProjectOverridesDoc,
+  validatePackSkillId,
+  validateCustomWorkflowId,
+  validateBuiltinSkillId,
+  containsForbiddenAuthorityKey,
+} from './validate-pack.js';
+
+function deepFreeze(value) {
+  if (value !== null && typeof value === 'object' && !Object.isFrozen(value)) {
+    for (const child of Object.values(value)) deepFreeze(child);
+    Object.freeze(value);
+  }
+  return value;
+}
+
+function sortedEntries(record) {
+  return Object.entries(record).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+}
+
+function builtinSnapshot() {
+  const skills = [...SKILLS].sort((a, b) => (a.id < b.id ? -1 : 1)).map((s) => deepFreeze({ ...s }));
+  const workflows = [...WORKFLOW_SKILLS].sort((a, b) => (a.id < b.id ? -1 : 1)).map((w) => deepFreeze({ ...w }));
+  const profiles = Object.fromEntries(sortedEntries(PROFILES).map(([name, members]) => [name, Object.freeze([...members].sort())]));
+  return {
+    skills: Object.freeze(skills),
+    workflows: Object.freeze(workflows),
+    profiles: Object.freeze(profiles),
+    overrides: Object.freeze({ skillDescriptions: Object.freeze({}), skillDomains: Object.freeze({}), guidance: Object.freeze({}) }),
+    selectableStages: Object.freeze(Object.fromEntries(sortedEntries(SELECTABLE_STAGES).map(([id, stages]) => [id, Object.freeze([...stages])]))),
+    skipRules: Object.freeze(Object.fromEntries(sortedEntries(SKIP_RULES).map(([id, rules]) => [id, deepFreeze(JSON.parse(JSON.stringify(rules)))]))),
+    requiredStages: Object.freeze(Object.fromEntries(sortedEntries(REQUIRED_STAGES).map(([id, stages]) => [id, Object.freeze([...stages])]))),
+  };
+}
+
+export const BUILTIN_SNAPSHOT = deepFreeze(builtinSnapshot());
+
+const BUILTIN_SKILL_IDS = new Set(SKILLS.map((s) => s.id));
+const BUILTIN_WORKFLOW_IDS = new Set(WORKFLOW_SKILLS.map((w) => w.id));
+const BUILTIN_PROFILE_NAMES = new Set(Object.keys(PROFILES));
+
+export function createExtensionCatalog({ packs = [], projectOverrides = null } = {}) {
+  const errors = [];
+  if (!Array.isArray(packs)) return { ok: false, errors: ['packs must be an array'] };
+  if (projectOverrides !== null && (typeof projectOverrides !== 'object' || Array.isArray(projectOverrides))) {
+    return { ok: false, errors: ['projectOverrides must be an object or null'] };
+  }
+  const sortedPacks = [...packs].sort((a, b) => String(a?.manifest?.name ?? '').localeCompare(String(b?.manifest?.name ?? '')));
+  const skillById = new Map();
+  const workflowById = new Map();
+  const packProfiles = {};
+  const customWorkflows = new Map();
+  const seenSkillIds = new Set([...BUILTIN_SKILL_IDS, ...BUILTIN_WORKFLOW_IDS]);
+
+  for (const pack of sortedPacks) {
+    if (!pack || typeof pack !== 'object') { errors.push('pack entry must be an object'); continue; }
+    const manifest = pack.manifest;
+    const manifestResult = validatePackManifest(manifest);
+    if (!manifestResult.ok) { errors.push(...manifestResult.errors.map((e) => `pack ${manifest?.name ?? '?'}: ${e}`)); continue; }
+    const ownedIds = new Set([...(manifest.skills ?? []).map((s) => s.id), ...((manifest.workflows ?? []).map((w) => w.id))]);
+    for (const skill of manifest.skills) {
+      if (seenSkillIds.has(skill.id)) { errors.push(`duplicate skill id: ${skill.id}`); continue; }
+      seenSkillIds.add(skill.id);
+      skillById.set(skill.id, deepFreeze({
+        id: skill.id,
+        kind: 'pack',
+        pack: manifest.name,
+        description: skill.description ?? '',
+        domains: Object.freeze([...(skill.domains ?? [])].sort()),
+      }));
+    }
+    for (const workflow of manifest.workflows ?? []) {
+      if (seenSkillIds.has(workflow.id)) { errors.push(`duplicate workflow id: ${workflow.id}`); continue; }
+      const doc = { ...(pack.workflows?.[workflow.id] ?? {}), id: workflow.id };
+      const docErrors = validateCustomWorkflowDoc(doc, `pack ${manifest.name} workflow ${workflow.id}`);
+      if (docErrors.length) { errors.push(...docErrors); continue; }
+      const authorityHit = containsForbiddenAuthorityKey(doc);
+      if (authorityHit) { errors.push(`pack ${manifest.name} workflow ${workflow.id} contains forbidden authority key at ${authorityHit}`); continue; }
+      seenSkillIds.add(workflow.id);
+      customWorkflows.set(workflow.id, { pack: manifest.name, doc: deepFreeze(JSON.parse(JSON.stringify(doc))) });
+      workflowById.set(workflow.id, deepFreeze({
+        id: workflow.id,
+        kind: 'custom-workflow',
+        pack: manifest.name,
+        description: doc.description ?? '',
+        stages: Object.freeze([...doc.stages].sort()),
+      }));
+    }
+    for (const [name, members] of Object.entries(manifest.profiles ?? {})) {
+      if (BUILTIN_PROFILE_NAMES.has(name) || packProfiles[name]) { errors.push(`duplicate profile name: ${name}`); continue; }
+      for (const member of members) {
+        if (!ownedIds.has(member)) errors.push(`pack ${manifest.name} profile ${name} references non-pack-owned id: ${member}`);
+      }
+      packProfiles[name] = Object.freeze([...members].sort());
+    }
+  }
+
+  let overridesResult = { ok: true, errors: [] };
+  let overrides = { skillDescriptions: {}, skillDomains: {}, guidance: {} };
+  if (projectOverrides) {
+    overridesResult = validateProjectOverridesDoc(projectOverrides, { knownIds: BUILTIN_SKILL_IDS });
+    if (!overridesResult.ok) errors.push(...overridesResult.errors.map((e) => `overrides: ${e}`));
+    else {
+      overrides = {
+        skillDescriptions: { ...(projectOverrides.skillDescriptions ?? {}) },
+        skillDomains: { ...(projectOverrides.skillDomains ?? {}) },
+        guidance: { ...(projectOverrides.guidance ?? {}) },
+      };
+      for (const id of Object.keys(projectOverrides.workflowPolicy ?? {})) {
+        if (!customWorkflows.has(id)) errors.push(`overrides workflowPolicy references unknown custom workflow: ${id}`);
+      }
+      for (const [name, members] of Object.entries(projectOverrides.profiles ?? {})) {
+        if (BUILTIN_PROFILE_NAMES.has(name)) { errors.push(`overrides MUST NOT mutate built-in profile: ${name}`); continue; }
+        for (const member of members) {
+          if (!BUILTIN_SKILL_IDS.has(member) && !BUILTIN_WORKFLOW_IDS.has(member) && !seenSkillIds.has(member)) {
+            errors.push(`overrides profile ${name} references unknown id: ${member}`);
+          }
+        }
+      }
+    }
+  }
+
+  if (errors.length) return { ok: false, errors: [...new Set(errors)].sort() };
+
+  const skills = [...SKILLS.map((s) => ({ ...s })), ...[...skillById.values()].map((s) => ({ ...s }))].sort((a, b) => (a.id < b.id ? -1 : 1));
+  const workflows = [...WORKFLOW_SKILLS.map((w) => ({ ...w })), ...[...workflowById.values()].map((w) => ({ ...w }))].sort((a, b) => (a.id < b.id ? -1 : 1));
+  const selectableStages = { ...SELECTABLE_STAGES };
+  const skipRules = JSON.parse(JSON.stringify(SKIP_RULES));
+  const requiredStages = { ...REQUIRED_STAGES };
+  for (const [id, { doc }] of [...customWorkflows.entries()].sort(([a], [b]) => (a < b ? -1 : 1))) {
+    const refinement = projectOverrides?.workflowPolicy?.[id];
+    const stages = refinement?.stages ?? doc.stages;
+    const required = refinement?.requiredStages ?? doc.requiredStages ?? [];
+    const compat = doc.workflowStateCompat;
+    const skip = compat ? compat.skipRules : Object.fromEntries(
+      (doc.allowedSkips ?? []).map((s) => [s.stage, { reason: s.reason, policy: s.policy, evidence: s.evidence }]),
+    );
+    const refinedSkip = { ...skip, ...(refinement?.skipRules ?? {}) };
+    selectableStages[id] = [...stages];
+    requiredStages[id] = [...required];
+    skipRules[id] = refinedSkip;
+  }
+  const profiles = {
+    ...Object.fromEntries(sortedEntries(PROFILES).map(([name, members]) => [name, [...members].sort()])),
+    ...Object.fromEntries(sortedEntries(packProfiles).map(([name, members]) => [name, [...members]])),
+    ...Object.fromEntries(sortedEntries(projectOverrides?.profiles ?? {}).map(([name, members]) => [name, [...members].sort()])),
+  };
+
+  const snapshot = {
+    skills: Object.freeze(skills.map((s) => deepFreeze(s))),
+    workflows: Object.freeze(workflows.map((w) => deepFreeze(w))),
+    profiles: deepFreeze(profiles),
+    overrides: deepFreeze(JSON.parse(JSON.stringify(overrides))),
+    selectableStages: deepFreeze(JSON.parse(JSON.stringify(selectableStages))),
+    skipRules: deepFreeze(JSON.parse(JSON.stringify(skipRules))),
+    requiredStages: deepFreeze(JSON.parse(JSON.stringify(requiredStages))),
+  };
+  return { ok: true, errors: [], value: deepFreeze(snapshot) };
+}
+
+export function getCatalogSkill(catalog, id) {
+  const snapshot = catalog ?? BUILTIN_SNAPSHOT;
+  const skill = snapshot.skills.find((s) => s.id === id) ?? null;
+  if (!skill) return getBuiltinSkill(id);
+  const description = snapshot.overrides?.skillDescriptions?.[id] ?? skill.description;
+  const domain = snapshot.overrides?.skillDomains?.[id];
+  const descChanged = description !== skill.description;
+  const domainChanged = domain !== undefined && domain !== skill.domain;
+  if (!descChanged && !domainChanged) return skill;
+  return { ...skill, ...(descChanged ? { description } : {}), ...(domainChanged ? { domain } : {}) };
+}
+
+export function getCatalogWorkflow(catalog, id) {
+  const snapshot = catalog ?? BUILTIN_SNAPSHOT;
+  return snapshot.workflows.find((w) => w.id === id) ?? getBuiltinWorkflow(id);
+}
+
+export function resolveCatalogProfile(catalog, profile) {
+  const snapshot = catalog ?? BUILTIN_SNAPSHOT;
+  const canonical = PROFILE_ALIASES[profile] ?? profile;
+  if (snapshot.profiles[canonical]) return [...snapshot.profiles[canonical]];
+  if (Object.hasOwn(PROFILE_ALIASES, profile) && snapshot.profiles[PROFILE_ALIASES[profile]]) return [...snapshot.profiles[PROFILE_ALIASES[profile]]];
+  throw new Error(`Unknown profile "${profile}".`);
+}
+
+export const extensionCatalogAPI = {
+  createExtensionCatalog,
+  getCatalogSkill,
+  getCatalogWorkflow,
+  resolveCatalogProfile,
+  BUILTIN_SNAPSHOT,
+};