avorelo 0.1.0

package/scripts/lib/source-catalog.js

@@ -0,0 +1,700 @@
+"use strict";
+
+const path = require("path");
+
+const VALID_SOURCE_TYPES = new Set([
+  "repository",
+  "documentation",
+  "spec",
+  "guide",
+  "product_reference",
+  "skill_pack",
+  "skills_repo",
+  "adapter_reference",
+]);
+
+const VALID_SOURCE_TRUST_LEVELS = new Set(["unknown", "low", "medium", "high"]);
+const VALID_RISK_LEVELS = new Set(["low", "medium", "high"]);
+const VALID_SOURCE_REVIEW_STATUSES = new Set(["unreviewed", "reviewed", "trusted", "blocked"]);
+const VALID_ALLOWED_USE_MODES = new Set([
+  "reference_only",
+  "suggested_install",
+  "wrapped_adapter",
+  "adapted_internal",
+  "vendored_with_attribution",
+  "blocked",
+]);
+const VALID_PRODUCT_DECISIONS = new Set([
+  "adopt_now",
+  "adapt_now",
+  "reference_only",
+  "defer",
+  "blocked",
+]);
+
+const SOURCE_CATALOG = Object.freeze([
+  {
+    id: "playwright-local-runner",
+    name: "Playwright",
+    sourceType: "documentation",
+    sourceUrl: "https://playwright.dev",
+    owner: "Microsoft",
+    license: "Apache-2.0",
+    licenseUrl: "https://github.com/microsoft/playwright/blob/main/LICENSE",
+    attributionRequired: true,
+    noticeRequired: true,
+    commercialUseMetadata: "Apache-2.0 generally permits commercial use subject to license conditions. This is metadata, not legal advice.",
+    sourceTrustLevel: "high",
+    riskLevel: "low",
+    sourceReviewStatus: "reviewed",
+    lastReviewedAt: "2026-05-12",
+    sourceSnapshot: { type: "docs_reference" },
+    supportedAgents: ["claude-code", "codex", "cursor", "generic"],
+    sourceCategories: ["browser_automation", "visual_qa"],
+    usefulPatterns: ["local browser runner", "screenshot-backed verification"],
+    adaptationCandidates: ["frontend readiness", "visual qa"],
+    blockedPatterns: ["bundling upstream code"],
+    knownRisks: ["User must install and configure independently."],
+    securityNotes: ["Treat Playwright as a local runner reference only."],
+    licenseNotes: ["Keep attribution when referenced in user-facing docs."],
+    attributionText: "Playwright is developed and maintained by Microsoft Corporation. Licensed under Apache-2.0. See https://playwright.dev",
+    allowedUseModes: ["reference_only", "suggested_install"],
+    defaultUseMode: "reference_only",
+    dogfoodStatus: "reviewed_for_runner_reference",
+    dogfoodEvidencePath: "docs/dogfood/operating-layer-dogfood-report.md",
+    productDecision: "reference_only",
+    notesFile: "docs/references/source-review-notes.md",
+  },
+  {
+    id: "addyosmani-agent-skills",
+    name: "Addy Osmani Agent Skills",
+    sourceType: "skills_repo",
+    sourceUrl: "https://github.com/addyosmani/agent-skills",
+    owner: "Addy Osmani",
+    license: "MIT",
+    licenseUrl: "https://github.com/addyosmani/agent-skills/blob/main/LICENSE",
+    attributionRequired: true,
+    noticeRequired: true,
+    commercialUseMetadata: "MIT generally permits commercial use subject to license conditions. This is metadata, not legal advice.",
+    sourceTrustLevel: "high",
+    riskLevel: "medium",
+    sourceReviewStatus: "reviewed",
+    lastReviewedAt: "2026-05-12",
+    sourceSnapshot: {
+      type: "reviewed_subset_vendored",
+      upstreamCommit: "3ff4b518b3cd3077ca27cf883aa21d21faf53802",
+      localPath: "vendor/skillpacks/addyosmani-agent-skills",
+    },
+    supportedAgents: ["claude-code", "codex", "cursor", "generic"],
+    sourceCategories: ["workflow_skills", "context_engineering", "verification"],
+    usefulPatterns: [
+      "using-agent-skills meta-skill",
+      "SKILL.md anatomy",
+      "incremental implementation",
+      "verification gates",
+      "rationalizations and red flags",
+      "source-driven development",
+    ],
+    adaptationCandidates: [
+      "reference_first_implementation",
+      "spec_driven_development",
+      "pr_quality_gate",
+      "test_driven_development",
+    ],
+    blockedPatterns: [
+      "blind runtime import",
+      "auto-executing upstream scripts",
+      "full prompt dump of vendored skills",
+    ],
+    knownRisks: [
+      "Imported scripts must remain non-runnable by default.",
+    ],
+    securityNotes: [
+      "Treat imported scripts as data only until explicitly reviewed.",
+      "Run static scanning before any deeper adaptation.",
+    ],
+    licenseNotes: [
+      "MIT confirmed from upstream reference.",
+      "Preserve LICENSE and attribution when vendoring locally.",
+    ],
+    attributionText: "Addy Osmani Agent Skills by Addy Osmani, used with attribution under the MIT license.",
+    allowedUseModes: ["reference_only", "adapted_internal", "vendored_with_attribution"],
+    defaultUseMode: "vendored_with_attribution",
+    dogfoodStatus: "reviewed_subset_vendored",
+    dogfoodEvidencePath: "docs/dogfood/skills-operating-layer-dogfood.md",
+    productDecision: "adopt_now",
+    notesFile: "docs/references/source-review-notes.md",
+  },
+  {
+    id: "anthropic-skills-repo",
+    name: "Anthropic Skills repo",
+    sourceType: "skills_repo",
+    sourceUrl: "https://github.com/anthropics/skills",
+    owner: "Anthropic",
+    license: "reference_only_pending_review",
+    licenseUrl: "https://github.com/anthropics/skills",
+    attributionRequired: true,
+    noticeRequired: true,
+    commercialUseMetadata: "Mixed-license repository. Reuse requires per-skill review.",
+    sourceTrustLevel: "high",
+    riskLevel: "medium",
+    sourceReviewStatus: "reviewed",
+    lastReviewedAt: "2026-05-13",
+    sourceSnapshot: { type: "docs_and_repo_reference_only" },
+    supportedAgents: ["claude-code", "generic"],
+    sourceCategories: ["skills", "browser_proof"],
+    usefulPatterns: ["narrow task skills", "supporting assets", "task-specific packaging"],
+    adaptationCandidates: ["skill structure", "browser proof workflow references"],
+    blockedPatterns: ["bulk import of mixed-license content", "runtime use without per-skill review"],
+    knownRisks: ["Not all skills share the same reuse status."],
+    securityNotes: ["Per-skill provenance review is required before any future vendoring."],
+    licenseNotes: ["Treat as structure and pattern source unless a specific open skill is reviewed."],
+    attributionText: "Anthropic Skills repo reviewed for structure and workflow patterns only.",
+    allowedUseModes: ["reference_only", "adapted_internal", "blocked"],
+    defaultUseMode: "reference_only",
+    dogfoodStatus: "reviewed_for_structure_only",
+    dogfoodEvidencePath: "docs/dogfood/skills-operating-layer-dogfood.md",
+    productDecision: "adapt_now",
+    notesFile: "docs/references/source-review-notes.md",
+  },
+  {
+    id: "anthropic-webapp-testing-skill",
+    name: "Anthropic webapp-testing skill",
+    sourceType: "guide",
+    sourceUrl: "https://github.com/anthropics/skills/blob/main/skills/webapp-testing/SKILL.md",
+    owner: "Anthropic",
+    license: "reference_only_pending_review",
+    licenseUrl: "https://github.com/anthropics/skills",
+    attributionRequired: true,
+    noticeRequired: true,
+    commercialUseMetadata: "Workflow reference only unless a specific licensed subset is approved later.",
+    sourceTrustLevel: "high",
+    riskLevel: "low",
+    sourceReviewStatus: "reviewed",
+    lastReviewedAt: "2026-05-13",
+    sourceSnapshot: { type: "workflow_reference_only" },
+    supportedAgents: ["claude-code", "generic"],
+    sourceCategories: ["browser_proof", "visual_qa"],
+    usefulPatterns: ["local server lifecycle", "browser evidence capture", "console and network inspection"],
+    adaptationCandidates: ["future Browser Proof capability"],
+    blockedPatterns: ["claiming Browser Proof is shipped in this PR", "copying mixed-license bodies into adapters"],
+    knownRisks: ["This source informs later Browser Proof work only."],
+    securityNotes: ["Keep Browser Proof out of this PR scope."],
+    licenseNotes: ["Reference workflow patterns only for now."],
+    attributionText: "Anthropic webapp-testing skill reviewed as a Browser Proof workflow reference only.",
+    allowedUseModes: ["reference_only"],
+    defaultUseMode: "reference_only",
+    dogfoodStatus: "reviewed_for_browser_proof_later",
+    dogfoodEvidencePath: "docs/dogfood/skills-operating-layer-dogfood.md",
+    productDecision: "reference_only",
+    notesFile: "docs/references/source-review-notes.md",
+  },
+  {
+    id: "openai-codex-skills-docs",
+    name: "OpenAI Codex Skills docs",
+    sourceType: "documentation",
+    sourceUrl: "https://developers.openai.com/codex/skills",
+    owner: "OpenAI",
+    license: "docs_reference",
+    licenseUrl: "https://openai.com/policies/",
+    attributionRequired: true,
+    noticeRequired: false,
+    commercialUseMetadata: "Use as documentation reference only.",
+    sourceTrustLevel: "high",
+    riskLevel: "low",
+    sourceReviewStatus: "reviewed",
+    lastReviewedAt: "2026-05-12",
+    sourceSnapshot: { type: "docs_reference" },
+    supportedAgents: ["codex"],
+    sourceCategories: ["skills", "adapter_behavior"],
+    usefulPatterns: ["skill directory with SKILL.md", "progressive disclosure", "context-budgeted discovery"],
+    adaptationCandidates: ["codex adapter guidance", "canonical avorelo skills", "skill registry validation"],
+    blockedPatterns: ["copying long docs text into adapters"],
+    knownRisks: ["Documentation can change without notice."],
+    securityNotes: ["Use as behavior reference only."],
+    licenseNotes: ["Do not mirror docs text wholesale."],
+    attributionText: "Behavior aligned with OpenAI Codex Skills documentation.",
+    allowedUseModes: ["reference_only", "adapted_internal"],
+    defaultUseMode: "adapted_internal",
+    dogfoodStatus: "reviewed_for_patterns",
+    dogfoodEvidencePath: "docs/dogfood/operating-layer-dogfood-report.md",
+    productDecision: "adapt_now",
+    notesFile: "docs/references/source-review-notes.md",
+  },
+  {
+    id: "claude-code-skills-docs",
+    name: "Claude Code Skills docs",
+    sourceType: "documentation",
+    sourceUrl: "https://code.claude.com/docs/en/skills",
+    owner: "Anthropic",
+    license: "docs_reference",
+    licenseUrl: "https://www.anthropic.com/legal/consumer-terms",
+    attributionRequired: true,
+    noticeRequired: false,
+    commercialUseMetadata: "Use as documentation reference only.",
+    sourceTrustLevel: "high",
+    riskLevel: "low",
+    sourceReviewStatus: "reviewed",
+    lastReviewedAt: "2026-05-12",
+    sourceSnapshot: { type: "docs_reference" },
+    supportedAgents: ["claude-code"],
+    sourceCategories: ["skills", "context_loading"],
+    usefulPatterns: [
+      "supporting files stay out of always-loaded context",
+      "skills load only when needed",
+      "precise invocation descriptions",
+    ],
+    adaptationCandidates: ["claude adapter guidance", "canonical avorelo skills"],
+    blockedPatterns: ["manual divergent copies of skill content"],
+    knownRisks: ["Documentation can evolve."],
+    securityNotes: ["Keep supporting files separate from always-loaded prompts."],
+    licenseNotes: ["Reference patterns only."],
+    attributionText: "Behavior aligned with Claude Code Skills documentation.",
+    allowedUseModes: ["reference_only", "adapted_internal"],
+    defaultUseMode: "adapted_internal",
+    dogfoodStatus: "reviewed_for_patterns",
+    dogfoodEvidencePath: "docs/dogfood/operating-layer-dogfood-report.md",
+    productDecision: "adapt_now",
+    notesFile: "docs/references/source-review-notes.md",
+  },
+  {
+    id: "claude-code-hooks-docs",
+    name: "Claude Code Hooks docs",
+    sourceType: "documentation",
+    sourceUrl: "https://code.claude.com/docs/en/hooks",
+    owner: "Anthropic",
+    license: "docs_reference",
+    licenseUrl: "https://www.anthropic.com/legal/consumer-terms",
+    attributionRequired: true,
+    noticeRequired: false,
+    commercialUseMetadata: "Use as documentation reference only.",
+    sourceTrustLevel: "high",
+    riskLevel: "medium",
+    sourceReviewStatus: "reviewed",
+    lastReviewedAt: "2026-05-12",
+    sourceSnapshot: { type: "docs_reference" },
+    supportedAgents: ["claude-code"],
+    sourceCategories: ["hooks", "lifecycle"],
+    usefulPatterns: ["SessionStart", "UserPromptSubmit", "PreToolUse", "PostToolUse", "PermissionRequest", "SessionEnd", "Stop"],
+    adaptationCandidates: ["future deterministic enforcement-point mapping"],
+    blockedPatterns: ["heavy new runtime hook system without safe existing infrastructure"],
+    knownRisks: ["Hook coverage differs across hosts."],
+    securityNotes: ["Use only for low-risk deterministic validations in v1."],
+    licenseNotes: ["Reference patterns only."],
+    attributionText: "Lifecycle mapping references Claude Code Hooks documentation.",
+    allowedUseModes: ["reference_only", "adapted_internal"],
+    defaultUseMode: "reference_only",
+    dogfoodStatus: "reviewed_for_mapping",
+    dogfoodEvidencePath: "docs/dogfood/operating-layer-dogfood-report.md",
+    productDecision: "adapt_now",
+    notesFile: "docs/references/source-review-notes.md",
+  },
+  {
+    id: "agents-md",
+    name: "AGENTS.md",
+    sourceType: "spec",
+    sourceUrl: "https://agents.md/",
+    owner: "AGENTS.md",
+    license: "spec_reference",
+    licenseUrl: "https://agents.md/",
+    attributionRequired: true,
+    noticeRequired: false,
+    commercialUseMetadata: "Use as open spec reference.",
+    sourceTrustLevel: "high",
+    riskLevel: "low",
+    sourceReviewStatus: "reviewed",
+    lastReviewedAt: "2026-05-12",
+    sourceSnapshot: { type: "spec_reference" },
+    supportedAgents: ["generic", "codex", "claude-code", "cursor", "gemini", "copilot"],
+    sourceCategories: ["instructions", "adapter_guidance"],
+    usefulPatterns: ["thin agent instruction surface"],
+    adaptationCandidates: ["generated adapter AGENTS.md files"],
+    blockedPatterns: ["pasting full skill bodies into AGENTS.md"],
+    knownRisks: [],
+    securityNotes: ["Keep generated files thin and public-safe."],
+    licenseNotes: ["Reference the spec, do not over-copy text."],
+    attributionText: "Adapter guidance is structured to align with AGENTS.md conventions.",
+    allowedUseModes: ["reference_only", "adapted_internal"],
+    defaultUseMode: "adapted_internal",
+    dogfoodStatus: "generated_guidance",
+    dogfoodEvidencePath: "docs/dogfood/operating-layer-dogfood-report.md",
+    productDecision: "adapt_now",
+    notesFile: "docs/references/source-review-notes.md",
+  },
+  {
+    id: "cursor-rules-docs",
+    name: "Cursor Rules docs",
+    sourceType: "documentation",
+    sourceUrl: "https://cursor.com/docs/rules",
+    owner: "Cursor",
+    license: "docs_reference",
+    licenseUrl: "https://cursor.com/legal",
+    attributionRequired: true,
+    noticeRequired: false,
+    commercialUseMetadata: "Use as documentation reference only.",
+    sourceTrustLevel: "high",
+    riskLevel: "low",
+    sourceReviewStatus: "reviewed",
+    lastReviewedAt: "2026-05-12",
+    sourceSnapshot: { type: "docs_reference" },
+    supportedAgents: ["cursor"],
+    sourceCategories: ["rules", "adapter_behavior"],
+    usefulPatterns: ["thin rules file"],
+    adaptationCandidates: ["generated cursor rules file"],
+    blockedPatterns: ["copying proprietary docs text into runtime"],
+    knownRisks: [],
+    securityNotes: ["Keep generated guidance thin."],
+    licenseNotes: ["Reference patterns only."],
+    attributionText: "Cursor adapter guidance references Cursor Rules documentation.",
+    allowedUseModes: ["reference_only", "adapted_internal"],
+    defaultUseMode: "adapted_internal",
+    dogfoodStatus: "generated_guidance",
+    dogfoodEvidencePath: "docs/dogfood/operating-layer-dogfood-report.md",
+    productDecision: "adapt_now",
+    notesFile: "docs/references/source-review-notes.md",
+  },
+  {
+    id: "gemini-cli-gemini-md",
+    name: "Gemini CLI GEMINI.md reference",
+    sourceType: "guide",
+    sourceUrl: "https://github.com/google-gemini/gemini-cli",
+    owner: "Google",
+    license: "reference_only_pending_review",
+    licenseUrl: null,
+    attributionRequired: true,
+    noticeRequired: false,
+    commercialUseMetadata: "Use as structural reference only until the exact document license is confirmed.",
+    sourceTrustLevel: "medium",
+    riskLevel: "medium",
+    sourceReviewStatus: "reviewed",
+    lastReviewedAt: "2026-05-12",
+    sourceSnapshot: { type: "pattern_reference" },
+    supportedAgents: ["gemini"],
+    sourceCategories: ["adapter_behavior"],
+    usefulPatterns: ["thin GEMINI.md adapter guidance"],
+    adaptationCandidates: ["generated GEMINI.md file"],
+    blockedPatterns: ["copying long upstream text"],
+    knownRisks: ["Exact doc path/license not locked in this repo."],
+    securityNotes: ["Keep guidance thin and point to core CLI."],
+    licenseNotes: ["Pattern-level adaptation only."],
+    attributionText: "Gemini adapter guidance uses thin-file patterns informed by Gemini CLI docs.",
+    allowedUseModes: ["reference_only", "adapted_internal"],
+    defaultUseMode: "adapted_internal",
+    dogfoodStatus: "generated_guidance",
+    dogfoodEvidencePath: "docs/dogfood/operating-layer-dogfood-report.md",
+    productDecision: "adapt_now",
+    notesFile: "docs/references/source-review-notes.md",
+  },
+  {
+    id: "github-copilot-custom-instructions-docs",
+    name: "GitHub Copilot custom instructions docs",
+    sourceType: "documentation",
+    sourceUrl: "https://docs.github.com/en/copilot/how-tos/custom-instructions/adding-repository-custom-instructions-for-github-copilot",
+    owner: "GitHub",
+    license: "docs_reference",
+    licenseUrl: "https://docs.github.com/en/site-policy/github-terms/github-terms-of-service",
+    attributionRequired: true,
+    noticeRequired: false,
+    commercialUseMetadata: "Use as documentation reference only.",
+    sourceTrustLevel: "high",
+    riskLevel: "low",
+    sourceReviewStatus: "reviewed",
+    lastReviewedAt: "2026-05-13",
+    sourceSnapshot: { type: "docs_reference" },
+    supportedAgents: ["copilot"],
+    sourceCategories: ["instructions", "adapter_guidance"],
+    usefulPatterns: ["repo instruction file", "path-specific instructions", "thin instruction surfaces"],
+    adaptationCandidates: ["generated copilot guidance"],
+    blockedPatterns: ["copying long docs text", "embedding core routing or policy logic in Copilot instructions"],
+    knownRisks: ["Docs can evolve over time."],
+    securityNotes: ["Keep generated files public-safe and thin."],
+    licenseNotes: ["Reference patterns only."],
+    attributionText: "Copilot guidance patterns align with GitHub Copilot custom instruction docs.",
+    allowedUseModes: ["reference_only", "adapted_internal"],
+    defaultUseMode: "adapted_internal",
+    dogfoodStatus: "reviewed_for_adapter_generation",
+    dogfoodEvidencePath: "docs/dogfood/skills-operating-layer-dogfood.md",
+    productDecision: "adapt_now",
+    notesFile: "docs/references/source-review-notes.md",
+  },
+  {
+    id: "play-ai-workspace",
+    name: "Play AI Workspace",
+    sourceType: "product_reference",
+    sourceUrl: "https://play.fast/",
+    owner: "Play",
+    license: "reference_only",
+    licenseUrl: null,
+    attributionRequired: true,
+    noticeRequired: false,
+    commercialUseMetadata: "Product-positioning reference only.",
+    sourceTrustLevel: "medium",
+    riskLevel: "medium",
+    sourceReviewStatus: "reviewed",
+    lastReviewedAt: "2026-05-12",
+    sourceSnapshot: { type: "product_positioning_reference" },
+    supportedAgents: ["generic"],
+    sourceCategories: ["positioning"],
+    usefulPatterns: ["invisible AI", "works with existing stack", "permissions as adoption enabler"],
+    adaptationCandidates: ["website copy positioning"],
+    blockedPatterns: ["copying text", "copying design", "copying screenshots", "copying assets"],
+    knownRisks: ["Product pages are not reusable source material."],
+    securityNotes: ["Reference only."],
+    licenseNotes: ["No text or design reuse."],
+    attributionText: "Positioning patterns informed by Play AI Workspace product references.",
+    allowedUseModes: ["reference_only"],
+    defaultUseMode: "reference_only",
+    dogfoodStatus: "positioning_review_only",
+    dogfoodEvidencePath: "docs/dogfood/operating-layer-dogfood-report.md",
+    productDecision: "reference_only",
+    notesFile: "docs/references/source-review-notes.md",
+  },
+  {
+    id: "impeccable-systems",
+    name: "Impeccable design skill systems",
+    sourceType: "repository",
+    sourceUrl: "unknown",
+    owner: "unknown",
+    license: "unknown",
+    licenseUrl: null,
+    attributionRequired: true,
+    noticeRequired: true,
+    commercialUseMetadata: "Exact source and license must be confirmed before reuse.",
+    sourceTrustLevel: "low",
+    riskLevel: "high",
+    sourceReviewStatus: "unreviewed",
+    lastReviewedAt: "2026-05-12",
+    sourceSnapshot: { type: "placeholder_reference" },
+    supportedAgents: ["claude-code", "codex"],
+    sourceCategories: ["frontend_quality"],
+    usefulPatterns: ["frontend anti-pattern vocabulary"],
+    adaptationCandidates: ["frontend readiness heuristics"],
+    blockedPatterns: ["copying code or text without confirmed source/license"],
+    knownRisks: ["Exact upstream reference was not present in the repo."],
+    securityNotes: ["Reference only until exact source is reviewed."],
+    licenseNotes: ["Blocked from copying until confirmed."],
+    attributionText: "Potential frontend-readiness patterns pending exact source confirmation.",
+    allowedUseModes: ["reference_only", "blocked"],
+    defaultUseMode: "reference_only",
+    dogfoodStatus: "deferred_pending_exact_source",
+    dogfoodEvidencePath: "docs/Capability-Sources.md",
+    productDecision: "defer",
+    notesFile: "docs/references/source-review-notes.md",
+  },
+  {
+    id: "marketing-skills-systems",
+    name: "Marketing skill systems",
+    sourceType: "repository",
+    sourceUrl: "unknown",
+    owner: "unknown",
+    license: "unknown",
+    licenseUrl: null,
+    attributionRequired: true,
+    noticeRequired: true,
+    commercialUseMetadata: "Exact source and license must be confirmed before reuse.",
+    sourceTrustLevel: "low",
+    riskLevel: "high",
+    sourceReviewStatus: "unreviewed",
+    lastReviewedAt: "2026-05-12",
+    sourceSnapshot: { type: "placeholder_reference" },
+    supportedAgents: ["claude-code", "codex"],
+    sourceCategories: ["marketing_readiness"],
+    usefulPatterns: ["positioning review", "SEO/CRO basics", "article outline review"],
+    adaptationCandidates: ["marketing readiness heuristics"],
+    blockedPatterns: ["copying code or text without confirmed source/license"],
+    knownRisks: ["Exact upstream reference was not present in the repo."],
+    securityNotes: ["Reference only until exact source is reviewed."],
+    licenseNotes: ["Blocked from copying until confirmed."],
+    attributionText: "Potential marketing-readiness patterns pending exact source confirmation.",
+    allowedUseModes: ["reference_only", "blocked"],
+    defaultUseMode: "reference_only",
+    dogfoodStatus: "deferred_pending_exact_source",
+    dogfoodEvidencePath: "docs/Capability-Sources.md",
+    productDecision: "defer",
+    notesFile: "docs/references/source-review-notes.md",
+  },
+]);
+
+const SOURCE_MAP = new Map(SOURCE_CATALOG.map((entry) => [entry.id, entry]));
+
+const REQUIRED_FIELDS = [
+  "id",
+  "name",
+  "sourceUrl",
+  "sourceType",
+  "license",
+  "sourceTrustLevel",
+  "riskLevel",
+  "sourceReviewStatus",
+  "allowedUseModes",
+  "defaultUseMode",
+  "productDecision",
+  "notesFile",
+];
+
+function validateSource(entry) {
+  const errors = [];
+  for (const field of REQUIRED_FIELDS) {
+    if (entry[field] === undefined || entry[field] === null || entry[field] === "") {
+      errors.push(`Missing required field: ${field}`);
+    }
+  }
+
+  if (!VALID_SOURCE_TYPES.has(entry.sourceType)) {
+    errors.push(`Invalid sourceType: ${entry.sourceType}`);
+  }
+  if (!VALID_SOURCE_TRUST_LEVELS.has(entry.sourceTrustLevel)) {
+    errors.push(`Invalid sourceTrustLevel: ${entry.sourceTrustLevel}`);
+  }
+  if (!VALID_RISK_LEVELS.has(entry.riskLevel)) {
+    errors.push(`Invalid riskLevel: ${entry.riskLevel}`);
+  }
+  if (!VALID_SOURCE_REVIEW_STATUSES.has(entry.sourceReviewStatus)) {
+    errors.push(`Invalid sourceReviewStatus: ${entry.sourceReviewStatus}`);
+  }
+  if (!VALID_PRODUCT_DECISIONS.has(entry.productDecision)) {
+    errors.push(`Invalid productDecision: ${entry.productDecision}`);
+  }
+  if (!Array.isArray(entry.allowedUseModes) || entry.allowedUseModes.length === 0) {
+    errors.push("allowedUseModes must be a non-empty array");
+  } else {
+    entry.allowedUseModes.forEach((mode) => {
+      if (!VALID_ALLOWED_USE_MODES.has(mode)) {
+        errors.push(`Invalid allowedUseMode: ${mode}`);
+      }
+    });
+  }
+  if (!VALID_ALLOWED_USE_MODES.has(entry.defaultUseMode)) {
+    errors.push(`Invalid defaultUseMode: ${entry.defaultUseMode}`);
+  }
+  if (Array.isArray(entry.allowedUseModes) && !entry.allowedUseModes.includes(entry.defaultUseMode)) {
+    errors.push("defaultUseMode must be included in allowedUseModes");
+  }
+  if (entry.sourceReviewStatus === "unreviewed" && entry.defaultUseMode === "vendored_with_attribution") {
+    errors.push("Unreviewed sources cannot default to vendored_with_attribution");
+  }
+  if ((entry.license === "unknown" || entry.license === "reference_only_pending_review") && entry.defaultUseMode === "vendored_with_attribution") {
+    errors.push("Sources without a confirmed reusable license cannot default to vendored_with_attribution");
+  }
+  return { valid: errors.length === 0, errors };
+}
+
+function validateSourceCatalog() {
+  const errors = [];
+  const seenIds = new Set();
+
+  SOURCE_CATALOG.forEach((entry) => {
+    if (seenIds.has(entry.id)) {
+      errors.push(`Duplicate source ID: ${entry.id}`);
+    }
+    seenIds.add(entry.id);
+    const result = validateSource(entry);
+    result.errors.forEach((error) => errors.push(`[${entry.id}] ${error}`));
+  });
+
+  return { valid: errors.length === 0, errors };
+}
+
+function getSource(id) {
+  return SOURCE_MAP.get(String(id || "").trim()) || null;
+}
+
+function listSources() {
+  return Array.from(SOURCE_CATALOG);
+}
+
+function isSourceAutoRunnable(id) {
+  const entry = getSource(id);
+  if (!entry) return false;
+  if (entry.sourceReviewStatus !== "trusted") return false;
+  return entry.defaultUseMode === "wrapped_adapter" || entry.defaultUseMode === "adapted_internal";
+}
+
+function canVendorSource(id) {
+  const entry = getSource(id);
+  if (!entry) return false;
+  if (entry.license === "unknown" || entry.license === "reference_only_pending_review") return false;
+  return entry.allowedUseModes.includes("vendored_with_attribution");
+}
+
+function hasConfirmedReusableLicense(entry) {
+  return !["unknown", "reference_only_pending_review", "docs_reference", "spec_reference", "reference_only"].includes(entry.license);
+}
+
+function allowsReusableDecision(entry) {
+  return entry.productDecision === "adopt_now" || entry.productDecision === "adapt_now";
+}
+
+function canReuseSource(entry) {
+  if (!allowsReusableDecision(entry)) return false;
+  if (!hasConfirmedReusableLicense(entry)) return false;
+  return entry.allowedUseModes.includes("vendored_with_attribution") || entry.allowedUseModes.includes("adapted_internal");
+}
+
+function canCopyCode(entry) {
+  if (!allowsReusableDecision(entry)) return false;
+  if (!hasConfirmedReusableLicense(entry)) return false;
+  return entry.allowedUseModes.includes("vendored_with_attribution");
+}
+
+function canCopyText(entry) {
+  if (!allowsReusableDecision(entry)) return false;
+  if (!hasConfirmedReusableLicense(entry)) return false;
+  if (entry.sourceType === "documentation" || entry.sourceType === "product_reference" || entry.sourceType === "spec" || entry.sourceType === "guide") {
+    return false;
+  }
+  return false;
+}
+
+function canLearnPatterns(entry) {
+  return entry.productDecision !== "blocked";
+}
+
+function toReferenceJsonEntry(entry) {
+  return {
+    id: entry.id,
+    name: entry.name,
+    sourceUrl: entry.sourceUrl,
+    sourceType: entry.sourceType,
+    license: entry.license,
+    sourceTrustLevel: entry.sourceTrustLevel,
+    riskLevel: entry.riskLevel,
+    decision: entry.productDecision,
+    reuseAllowed: canReuseSource(entry),
+    copyCodeAllowed: canCopyCode(entry),
+    copyTextAllowed: canCopyText(entry),
+    learnPatternAllowed: canLearnPatterns(entry),
+    attributionRequired: entry.attributionRequired,
+    avoreloFit: entry.sourceCategories.join(", "),
+    implementationArea: entry.adaptationCandidates.join(", "),
+    notesFile: entry.notesFile,
+    lastReviewed: entry.lastReviewedAt,
+  };
+}
+
+function resolveNotesPath(cwd, entry) {
+  return path.join(cwd, entry.notesFile);
+}
+
+module.exports = {
+  SOURCE_CATALOG,
+  VALID_SOURCE_TYPES,
+  VALID_SOURCE_TRUST_LEVELS,
+  VALID_RISK_LEVELS,
+  VALID_SOURCE_REVIEW_STATUSES,
+  VALID_ALLOWED_USE_MODES,
+  VALID_PRODUCT_DECISIONS,
+  validateSource,
+  validateSourceCatalog,
+  getSource,
+  listSources,
+  isSourceAutoRunnable,
+  canVendorSource,
+  toReferenceJsonEntry,
+  hasConfirmedReusableLicense,
+  canReuseSource,
+  canCopyCode,
+  canCopyText,
+  canLearnPatterns,
+  resolveNotesPath,
+};