clckernel 1.2.6

package/src/catalog.js

@@ -0,0 +1,217 @@
+/**
+ * CLC Kernel — Central Safeguard Catalog
+ *
+ * Single source of truth describing every safeguard/guard the clckernel
+ * framework knows about. Drives config validation (src/config.js),
+ * config-driven harness generation (src/generator.js), doctor checks, and
+ * the future safeguard audit.
+ *
+ * Entry shape (design §1.2, additive fields noted):
+ *   name        {string}        guard script basename WITHOUT extension
+ *   labels      {string[]}      alias labels (yaml/js/python variants) for config matching
+ *   checks      {string}        short description of what the safeguard verifies (design §1.2)
+ *   verify      {string[]}      plausible verify_* audit-goal tokens this safeguard covers
+ *   applies_when{string}        applicability predicate key (stack/project conditions)
+ *   severity    {string}        'error' | 'warning' | 'advisory' (catalog default)
+ *   gate_mode   {string}        'hard' | 'advisory' (catalog default)
+ *   config_keys {string[]}      .clc-forge.yml keys this safeguard consumes
+ *   phase       {string}        10-phase harness phase: 'audit' | 'test' | 'review' | 'handover'
+ *   file        {string|null}   bundled tools/ file(s), '+' separated; null = external CLI
+ *   manifest    {boolean}       true = declared by >=1 adapter manifest (design §1.2)
+ *   planned     {boolean}       true = tool file not yet materialized (future slice)
+ *
+ * The catalog is a JOIN, not a rewrite: the no-config adapter path never
+ * consults it; only the config-driven generation path does.
+ */
+
+const SAFEGUARD_CATALOG = [
+  { name: 'scan_secrets', labels: ['scan_secrets', 'scan_secrets.js', 'scan_secrets.py'],
+    checks: 'Secret & private-key leak scan', verify: ['verify_secret_leaks', 'verify_no_hardcoded_secrets'],
+    applies_when: 'always', severity: 'error', gate_mode: 'hard', config_keys: ['scope', 'exclude_paths'],
+    phase: 'audit', file: 'scan_secrets.js+scan_secrets.py', manifest: true, planned: false },
+
+  { name: 'check_architecture', labels: ['check_architecture', 'check_architecture.js', 'check_architecture.py'],
+    checks: 'Clean Architecture layer / server-component boundaries', verify: ['verify_architecture_layers', 'verify_server_component_boundaries'],
+    applies_when: 'frontend,backend', severity: 'error', gate_mode: 'hard', config_keys: ['scope', 'exclude_paths'],
+    phase: 'audit', file: 'check_architecture.js+check_architecture.py', manifest: true, planned: false },
+
+  { name: 'check_custom', labels: ['check_custom', 'check_custom.js', 'check_custom.py'],
+    checks: 'User-defined regex rules from `.clc-forge.yml`', verify: ['verify_custom_rules', 'verify_user_defined_regex_rules'],
+    applies_when: 'always', severity: 'error', gate_mode: 'hard', config_keys: ['scope', 'exclude_paths'],
+    phase: 'audit', file: 'check_custom.js+check_custom.py', manifest: true, planned: false },
+
+  { name: 'check_a11y', labels: ['check_a11y', 'check_a11y.js'],
+    checks: 'ARIA + alt accessibility', verify: ['verify_a11y', 'verify_accessibility'],
+    applies_when: 'frontend', severity: 'error', gate_mode: 'hard', config_keys: ['scope', 'exclude_paths'],
+    phase: 'audit', file: 'check_a11y.js', manifest: true, planned: false },
+
+  { name: 'check_ui_reuse', labels: ['check_ui_reuse', 'check_ui_reuse.js'],
+    checks: 'UI primitive reuse from components/ui/', verify: ['verify_ui_reuse', 'verify_component_reuse'],
+    applies_when: 'frontend', severity: 'warning', gate_mode: 'advisory', config_keys: ['scope', 'exclude_paths'],
+    phase: 'audit', file: 'check_ui_reuse.js', manifest: true, planned: false },
+
+  { name: 'check_performance', labels: ['check_performance', 'check_performance.js'],
+    checks: 'next/image + tree-shaking', verify: ['verify_performance', 'verify_image_optimization'],
+    applies_when: 'frontend', severity: 'warning', gate_mode: 'advisory', config_keys: ['scope', 'exclude_paths'],
+    phase: 'audit', file: 'check_performance.js', manifest: true, planned: false },
+
+  { name: 'check_responsive', labels: ['check_responsive', 'check_responsive.js'],
+    checks: 'Mobile-first responsiveness, fixed-width overflow & touch target size', verify: ['verify_responsive', 'verify_mobile_adaptability'],
+    applies_when: 'frontend', severity: 'warning', gate_mode: 'advisory', config_keys: ['scope', 'exclude_paths'],
+    phase: 'audit', file: 'check_responsive.js', manifest: true, planned: false },
+
+  { name: 'check_seo', labels: ['check_seo', 'check_seo.js'],
+    checks: 'SEO metadata, OpenGraph, GEO tags, semantic HTML & LCP priority', verify: ['verify_seo', 'verify_geo_metadata', 'verify_core_web_vitals'],
+    applies_when: 'frontend', severity: 'warning', gate_mode: 'advisory', config_keys: ['scope', 'exclude_paths'],
+    phase: 'audit', file: 'check_seo.js', manifest: true, planned: false },
+
+  { name: 'check_storybook', labels: ['check_storybook', 'check_storybook.js'],
+    checks: 'Storybook coverage (`.stories.tsx`)', verify: ['verify_storybook_coverage'],
+    applies_when: 'frontend', severity: 'warning', gate_mode: 'advisory', config_keys: ['scope', 'exclude_paths'],
+    phase: 'audit', file: 'check_storybook.js', manifest: true, planned: false },
+
+  { name: 'check_api_contracts', labels: ['check_api_contracts', 'check_api_contracts.js'],
+    checks: 'Zod response-schema parsing', verify: ['verify_api_contracts', 'verify_response_schemas'],
+    applies_when: 'frontend', severity: 'error', gate_mode: 'hard', config_keys: ['scope', 'exclude_paths'],
+    phase: 'audit', file: 'check_api_contracts.js', manifest: true, planned: false },
+
+  { name: 'check_migrations', labels: ['check_migrations', 'check_migrations.py'],
+    checks: 'Alembic/Django migration idempotency', verify: ['verify_migration_idempotency'],
+    applies_when: 'backend,fastapi,django', severity: 'error', gate_mode: 'hard', config_keys: ['scope', 'exclude_paths'],
+    phase: 'audit', file: 'check_migrations.py', manifest: true, planned: false },
+
+  { name: 'verify_tdd', labels: ['verify_tdd', 'verify_tdd.py'],
+    checks: 'Real red→green TDD validation', verify: ['verify_tdd_red_green', 'verify_tdd_evidence'],
+    applies_when: 'backend', severity: 'error', gate_mode: 'hard', config_keys: ['scope', 'exclude_paths'],
+    phase: 'audit', file: 'verify_tdd.py', manifest: false, planned: false },
+
+  { name: 'check_scope', labels: ['check_scope', 'check_scope.py'],
+    checks: 'git-diff vs SDD-authorization scope guardrail', verify: ['verify_scope_authorization', 'verify_sdd_scope'],
+    applies_when: 'always', severity: 'error', gate_mode: 'hard', config_keys: ['scope', 'exclude_paths'],
+    phase: 'audit', file: 'check_scope.py', manifest: false, planned: false },
+
+  { name: 'celery_guard', labels: ['celery_guard', 'celery_guard.py'],
+    checks: 'Broker URL exposure, ignore_result, result backend', verify: ['verify_celery_broker_config'],
+    applies_when: 'celery', severity: 'error', gate_mode: 'hard', config_keys: ['scope', 'exclude_paths'],
+    phase: 'audit', file: 'celery_guard.py', manifest: true, planned: false },
+
+  { name: 'redis_guard', labels: ['redis_guard', 'redis_guard.py'],
+    checks: 'decode_responses, connect timeout, hardcoded URLs', verify: ['verify_redis_config'],
+    applies_when: 'redis', severity: 'error', gate_mode: 'hard', config_keys: ['scope', 'exclude_paths'],
+    phase: 'audit', file: 'redis_guard.py', manifest: true, planned: false },
+
+  { name: 'postgres_guard', labels: ['postgres_guard', 'postgres_guard.py'],
+    checks: 'Raw SQL string formatting, hstore misuse', verify: ['verify_postgres_sql_usage'],
+    applies_when: 'postgresql', severity: 'error', gate_mode: 'hard', config_keys: ['scope', 'exclude_paths'],
+    phase: 'audit', file: 'postgres_guard.py', manifest: true, planned: false },
+
+  { name: 'docker_guard', labels: ['docker_guard', 'docker_guard.py'],
+    checks: 'Non-root USER, ENV secrets, missing HEALTHCHECK', verify: ['verify_dockerfile_security'],
+    applies_when: 'docker', severity: 'error', gate_mode: 'hard', config_keys: ['scope', 'exclude_paths'],
+    phase: 'audit', file: 'docker_guard.py', manifest: true, planned: false },
+
+  { name: 'ruff', labels: ['ruff'],
+    checks: 'Python AST linter (external CLI)', verify: ['verify_python_lint'],
+    applies_when: 'backend', severity: 'warning', gate_mode: 'advisory', config_keys: [],
+    phase: 'test', file: null, manifest: true, planned: false },
+
+  { name: 'pytest', labels: ['pytest'],
+    checks: 'Test runner (external CLI)', verify: ['verify_test_coverage'],
+    applies_when: 'backend', severity: 'warning', gate_mode: 'advisory', config_keys: [],
+    phase: 'test', file: null, manifest: true, planned: false },
+
+  { name: 'tsc', labels: ['tsc'],
+    checks: 'TypeScript typecheck (external)', verify: ['verify_typescript_types'],
+    applies_when: 'frontend', severity: 'error', gate_mode: 'hard', config_keys: [],
+    phase: 'test', file: null, manifest: true, planned: false },
+
+  { name: 'lint', labels: ['lint', 'lint-staged'],
+    checks: 'lint-staged (external)', verify: ['verify_lint_staged'],
+    applies_when: 'frontend', severity: 'warning', gate_mode: 'advisory', config_keys: [],
+    phase: 'test', file: null, manifest: true, planned: false },
+
+  { name: 'graphify', labels: ['graphify'],
+    checks: 'Memory graph (external, graceful-skip)', verify: ['verify_memory_graph'],
+    applies_when: 'always', severity: 'warning', gate_mode: 'advisory', config_keys: [],
+    phase: 'review', file: null, manifest: false, planned: false },
+
+  { name: 'gentle_ai_review', labels: ['gentle_ai_review', 'gentle-ai'],
+    checks: 'Native bounded review gate (external, graceful-skip)', verify: ['verify_rdd_review_gate'],
+    applies_when: 'always', severity: 'error', gate_mode: 'hard', config_keys: [],
+    phase: 'review', file: null, manifest: false, planned: false },
+
+  { name: 'check_openapi_drift', labels: ['check_openapi_drift', 'check_openapi_drift.py'],
+    checks: 'FastAPI OpenAPI schema drift vs app routes', verify: ['verify_openapi_drift'],
+    applies_when: 'fastapi', severity: 'error', gate_mode: 'hard', config_keys: ['scope', 'exclude_paths'],
+    phase: 'audit', file: 'check_openapi_drift.py', manifest: true, planned: true },
+
+  { name: 'check_db_efficiency', labels: ['check_db_efficiency', 'check_db_efficiency.py'],
+    checks: 'ORM N+1 / select_related / prefetch_related', verify: ['verify_db_efficiency', 'verify_no_n_plus_1'],
+    applies_when: 'django|sqlalchemy', severity: 'error', gate_mode: 'hard', config_keys: ['scope', 'exclude_paths'],
+    phase: 'audit', file: 'check_db_efficiency.py', manifest: true, planned: false },
+
+  { name: 'check_observability', labels: ['check_observability', 'check_observability.py'],
+    checks: 'structlog structured logging; bare print/logger ban', verify: ['verify_structured_logging'],
+    applies_when: 'backend', severity: 'warning', gate_mode: 'advisory', config_keys: ['scope', 'exclude_paths'],
+    phase: 'audit', file: 'check_observability.py', manifest: true, planned: true },
+];
+
+// Freeze the registry so config validation and generation can rely on it.
+Object.freeze(SAFEGUARD_CATALOG);
+for (const entry of SAFEGUARD_CATALOG) {
+  Object.freeze(entry.labels);
+  Object.freeze(entry.verify);
+  Object.freeze(entry.config_keys);
+  Object.freeze(entry);
+}
+
+/** Valid value sets exported for validators (src/config.js, tests). */
+const VALID_SEVERITIES = ['error', 'warning', 'advisory'];
+const VALID_GATE_MODES = ['hard', 'advisory'];
+const VALID_PHASES = ['audit', 'test', 'review', 'handover'];
+const VALID_APPLIES_WHEN = [
+  'always', 'frontend', 'backend', 'fastapi', 'django', 'django|sqlalchemy',
+  'celery', 'redis', 'postgresql', 'docker', 'frontend,backend', 'backend,fastapi,django',
+];
+
+/** Normalize an input label for catalog lookup. */
+function normalizeLabel(name) {
+  return typeof name === 'string' ? name.trim().toLowerCase() : '';
+}
+
+/**
+ * Resolve a guard name (or any alias label) to its catalog entry.
+ * @param {string} name - entry name or alias label (e.g. 'check_custom.js', 'lint-staged')
+ * @returns {object|null} the catalog entry, or null when unknown
+ */
+function applyTo(name) {
+  const key = normalizeLabel(name);
+  if (!key) return null;
+  for (const entry of SAFEGUARD_CATALOG) {
+    if (entry.labels.includes(key)) return entry;
+  }
+  return null;
+}
+
+/** Catalog default severity for a guard name/label; null when unknown. */
+function severityFor(name) {
+  const entry = applyTo(name);
+  return entry ? entry.severity : null;
+}
+
+/** Catalog default gate mode for a guard name/label; null when unknown. */
+function gateFor(name) {
+  const entry = applyTo(name);
+  return entry ? entry.gate_mode : null;
+}
+
+module.exports = {
+  SAFEGUARD_CATALOG,
+  VALID_SEVERITIES,
+  VALID_GATE_MODES,
+  VALID_PHASES,
+  VALID_APPLIES_WHEN,
+  applyTo,
+  severityFor,
+  gateFor,
+};

package/src/config.js

@@ -0,0 +1,250 @@
+/**
+ * CLC Kernel - extended .clckernel.yml / .clc-forge.yml loader / validator / resolver.
+ * Backbone = src/catalog.js. Invalid config -> actionable ConfigError;
+ * never a silent fallback.
+ */
+
+const { parseYaml } = require('./yaml.js');
+const {
+  SAFEGUARD_CATALOG,
+  VALID_SEVERITIES,
+  VALID_GATE_MODES,
+  applyTo,
+  severityFor,
+} = require('./catalog.js');
+
+/**
+ * Canonical 10-phase workflow order (design §3.1). NOTE: catalog VALID_PHASES
+ * is the per-entry `phase` field, NOT this workflow — the `phases` config key
+ * validates against this list.
+ */
+const HARNESS_PHASES = [
+  'research', 'plan', 'test-scenarios', 'hit', 'tdd-red',
+  'green', 'audit', 'rdd-review', 'handover', 'close',
+];
+
+const ENV_SEVERITIES = 'CLCKERNEL_SEVERITIES';
+const LEGACY_ENV_SEVERITIES = 'CLC_FORGE_SEVERITIES';
+const DEFAULT_SCOPE = '.';
+
+class ConfigError extends Error {
+  constructor(path, message, allowed) {
+    const list = Array.isArray(allowed) ? allowed : allowed != null ? [allowed] : [];
+    super(
+      `Invalid .clckernel.yml: key "${path}" — ${message}` +
+        (list.length ? ` (allowed: ${list.join(', ')})` : '')
+    );
+    this.name = 'ConfigError';
+    this.path = path;
+    this.allowed = list;
+    this.fix =
+      list.length
+        ? `Set "${path}" to one of: ${list.join(', ')}. ${message}`
+        : `Correct the value of "${path}". ${message}`;
+  }
+}
+
+function arrOrThrow(raw, path, what) {
+  if (!Array.isArray(raw)) throw new ConfigError(path, `expected an array, got ${raw === null ? 'null' : typeof raw}`, what);
+  if (!raw.length) throw new ConfigError(path, 'must not be empty', what);
+}
+
+function strItems(arr, base) {
+  arr.forEach((v, i) => {
+    if (typeof v !== 'string' || v.trim() === '') {
+      throw new ConfigError(`${base}[${i}]`, 'each item must be a non-empty string');
+    }
+  });
+  return arr;
+}
+
+function listGuards() {
+  return SAFEGUARD_CATALOG.map((e) => e.name);
+}
+
+function validateConfig(raw) {
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+    throw new ConfigError('<root>', 'expected a YAML mapping (object)');
+  }
+
+  const { active_guards, gate_mode, severities, phases, scope, exclude_paths, layers, rules } = raw;
+
+  if (active_guards !== undefined) {
+    arrOrThrow(active_guards, 'active_guards', 'a list of catalog guard names');
+    active_guards.forEach((name, i) => {
+      if (typeof name !== 'string' || name.trim() === '') throw new ConfigError(`active_guards[${i}]`, 'each active guard must be a non-empty string');
+      if (!applyTo(name)) throw new ConfigError(`active_guards[${i}]`, `unknown guard "${name}"`, listGuards());
+    });
+  }
+
+  if (gate_mode !== undefined && (typeof gate_mode !== 'string' || !VALID_GATE_MODES.includes(gate_mode))) {
+    throw new ConfigError('gate_mode', `invalid value "${gate_mode}"`, VALID_GATE_MODES);
+  }
+
+  if (severities !== undefined) {
+    if (!severities || typeof severities !== 'object' || Array.isArray(severities)) {
+      throw new ConfigError('severities', 'expected an object mapping guard -> severity');
+    }
+    for (const [name, severity] of Object.entries(severities)) {
+      if (!applyTo(name)) throw new ConfigError(`severities.${name}`, `unknown guard "${name}"`, listGuards());
+      if (!VALID_SEVERITIES.includes(severity)) throw new ConfigError(`severities.${name}`, `invalid severity "${severity}"`, VALID_SEVERITIES);
+    }
+  }
+
+  if (phases !== undefined) {
+    arrOrThrow(phases, 'phases', 'the canonical 10-phase workflow names');
+    let last = -1;
+    phases.forEach((phase, i) => {
+      if (typeof phase !== 'string' || phase.trim() === '') throw new ConfigError(`phases[${i}]`, 'each phase must be a non-empty string');
+      const idx = HARNESS_PHASES.indexOf(phase);
+      if (idx === -1) throw new ConfigError(`phases[${i}]`, `unknown phase "${phase}"`, HARNESS_PHASES);
+      if (idx <= last) throw new ConfigError(`phases[${i}]`, `phase "${phase}" is out of order — canonical order is ${HARNESS_PHASES.join(' → ')}`);
+      last = idx;
+    });
+  }
+
+  if (scope !== undefined) {
+    const items = typeof scope === 'string' ? [scope] : scope;
+    arrOrThrow(items, 'scope', 'a glob string or array of glob strings');
+    strItems(items, 'scope');
+  }
+
+  if (exclude_paths !== undefined) { arrOrThrow(exclude_paths, 'exclude_paths', 'an array of glob strings'); strItems(exclude_paths, 'exclude_paths'); }
+  if (layers !== undefined) { arrOrThrow(layers, 'layers', 'an array of layer name strings'); strItems(layers, 'layers'); }
+
+  if (rules !== undefined) {
+    arrOrThrow(rules, 'rules', 'an array of legacy rule objects');
+    const seen = new Set();
+    rules.forEach((rule, i) => {
+      if (!rule || typeof rule !== 'object' || Array.isArray(rule)) throw new ConfigError(`rules[${i}]`, 'each rule must be an object');
+      if (typeof rule.name !== 'string' || rule.name.trim() === '') throw new ConfigError(`rules[${i}]`, 'each rule requires a non-empty "name"');
+      if (seen.has(rule.name)) throw new ConfigError(`rules[${i}].name`, `duplicate rule name "${rule.name}"`);
+      seen.add(rule.name);
+      if (rule.severity !== undefined && !['error', 'warning'].includes(rule.severity)) {
+        throw new ConfigError(`rules[${i}].severity`, `invalid severity "${rule.severity}"`, ['error', 'warning']);
+      }
+    });
+  }
+
+  return raw;
+}
+
+const loadConfig = (yamlString) => {
+  if (yamlString === undefined || yamlString === null || yamlString.trim() === '') return {};
+  let raw;
+  try { raw = parseYaml(yamlString); } catch (err) { throw new ConfigError('<root>', `YAML parse error: ${err.message}`); }
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) throw new ConfigError('<root>', 'expected a YAML mapping (object) at the top level');
+  return raw;
+};
+
+/** Env override map (tolerant: malformed JSON/non-object ignored). */
+function envSeverities() {
+  const raw =
+    process.env[ENV_SEVERITIES] ||
+    process.env.CLC_KERNEL_SEVERITIES ||
+    process.env[LEGACY_ENV_SEVERITIES];
+  if (!raw) return {};
+  try {
+    const parsed = JSON.parse(raw);
+    if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) return parsed;
+  } catch { /* ignore malformed env override */ }
+  return {};
+}
+
+/** Catalog names among detected.techTools (design §1.3 JOIN rule). */
+function detectedToolNames(detected) {
+  const names = new Set();
+  if (!detected || !Array.isArray(detected.techTools)) return names;
+  for (const tool of detected.techTools) {
+    const name = tool && typeof tool === 'object' ? tool.name : tool;
+    const entry = applyTo(name);
+    if (entry) names.add(entry.name);
+  }
+  return names;
+}
+
+/** True when a catalog row applies to the detected stack. */
+function rowApplies(row, detected, detectedTools) {
+  if (row.applies_when === 'always') return true;
+  if (!detected || typeof detected !== 'object') return false;
+  if (detectedTools && detectedTools.has(row.name)) return true;
+  const deps = new Set(
+    [detected.projectType, detected.framework, detected.orm]
+      .filter((x) => typeof x === 'string')
+      .map((x) => x.toLowerCase())
+  );
+  for (const alt of row.applies_when.split('|')) {
+    for (const tok of alt.split(',')) {
+      const t = tok.trim();
+      if (t && deps.has(t)) return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * Generation-time severity precedence: env CLC_FORGE_SEVERITIES > config
+ * severities > catalog default > 'error'. (Guard-result still wins at runtime
+ * audit — slice C.)
+ */
+function resolveSeverity(name, configSeverities, envMap) {
+  if (envMap[name] && VALID_SEVERITIES.includes(envMap[name])) return envMap[name];
+  if (configSeverities[name] && VALID_SEVERITIES.includes(configSeverities[name])) return configSeverities[name];
+  const cat = severityFor(name);
+  if (cat && VALID_SEVERITIES.includes(cat)) return cat;
+  return 'error';
+}
+
+/**
+ * Effective resolved config (catalog defaults merged with overrides).
+ * @param {object} raw - validated raw config.
+ * @param {object} [detected] - autoDetectStack output (optional; {} when unknown).
+ */
+function resolveConfig(raw, detected) {
+  const validated = validateConfig(raw);
+  const gateMode = validated.gate_mode === undefined ? 'hard' : validated.gate_mode;
+  const phases = validated.phases === undefined ? HARNESS_PHASES.slice() : validated.phases;
+  const detectedTools = detectedToolNames(detected);
+  const base = SAFEGUARD_CATALOG.filter((row) => rowApplies(row, detected, detectedTools));
+  const active =
+    Array.isArray(validated.active_guards) && validated.active_guards.length
+      ? validated.active_guards
+      : base.map((row) => row.name);
+  const configSeverities = validated.severities || {};
+  const envMap = envSeverities();
+
+  const effectiveSeverities = {};
+  const __catalog = active.map((name) => {
+    const entry = applyTo(name);
+    const severity = resolveSeverity(name, configSeverities, envMap);
+    effectiveSeverities[name] = severity;
+    return {
+      name,
+      checks: entry ? entry.checks : undefined,
+      applies_when: entry ? entry.applies_when : undefined,
+      severity,
+      gate_mode: gateMode === 'advisory' ? 'advisory' : entry ? entry.gate_mode : 'hard',
+      file: entry ? entry.file : null,
+      manifest: entry ? entry.manifest : false,
+      planned: entry ? entry.planned : false,
+      config_keys: entry ? entry.config_keys : [],
+    };
+  });
+
+  return {
+    activeGuards: active,
+    phases,
+    gateMode,
+    effectiveSeverities,
+    layers: validated.layers || [],
+    scope: validated.scope === undefined ? DEFAULT_SCOPE : validated.scope,
+    excludePaths: validated.exclude_paths || [],
+    framework: detected && detected.framework ? detected.framework : 'unknown',
+    projectType: detected && detected.projectType ? detected.projectType : 'unknown',
+    testRunner: detected && detected.testRunner ? detected.testRunner : 'unknown',
+    rules: validated.rules || [],
+    __catalog,
+  };
+}
+
+module.exports = { loadConfig, validateConfig, resolveConfig, ConfigError, HARNESS_PHASES, ENV_SEVERITIES, DEFAULT_SCOPE };

package/src/detector.js

@@ -0,0 +1,85 @@
+/**
+ * CLC Forge — Universal Auto-Discovery Engine
+ * Inspects repository signatures to auto-match the right polyglot Stack Adapter
+ * (Next.js, FastAPI, Django, Astro, Rails, Go, Rust, Laravel).
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const NextjsAdapter = require('./adapters/nextjs');
+const FastApiAdapter = require('./adapters/fastapi');
+const DjangoAdapter = require('./adapters/django');
+const AstroAdapter = require('./adapters/astro');
+const RailsAdapter = require('./adapters/rails');
+const GoAdapter = require('./adapters/go');
+const RustAdapter = require('./adapters/rust');
+const LaravelAdapter = require('./adapters/laravel');
+const { TechnologyDetector } = require('./technologies/detector');
+
+const adapters = [
+  new NextjsAdapter(),
+  new FastApiAdapter(),
+  new DjangoAdapter(),
+  new AstroAdapter(),
+  new RailsAdapter(),
+  new GoAdapter(),
+  new RustAdapter(),
+  new LaravelAdapter()
+];
+
+function autoDetectStack(targetDir) {
+  // 1. Check registered polyglot adapters
+  for (const adapter of adapters) {
+    if (adapter.detect(targetDir)) {
+      // Detect Phase-1 technologies (Celery, Redis, PostgreSQL, Docker)
+      const techDetector = new TechnologyDetector();
+      const detectedTechs = techDetector.detect(targetDir);
+      const techTools = techDetector.getToolsForTech(detectedTechs);
+
+      return {
+        projectType: adapter.projectType,
+        framework: adapter.name,
+        styling: adapter.projectType === 'frontend' ? 'Tailwind CSS v4' : 'N/A',
+        uiLibrary: adapter.projectType === 'frontend' ? 'Component Primitives' : 'N/A',
+        testRunner: adapter.testRunner,
+        gitHooks: fs.existsSync(path.join(targetDir, '.husky')) ? 'husky' : 'githooks',
+        orm: 'Framework Native',
+        adapter,
+        techTools
+      };
+    }
+  }
+
+  // 2. Fallback detection
+  const techDetector = new TechnologyDetector();
+  const detectedTechs = techDetector.detect(targetDir);
+  const techTools = techDetector.getToolsForTech(detectedTechs);
+
+  const config = {
+    projectType: 'unknown',
+    framework: 'unknown',
+    styling: 'none',
+    uiLibrary: 'none',
+    testRunner: 'unknown',
+    gitHooks: fs.existsSync(path.join(targetDir, '.husky')) ? 'husky' : 'githooks',
+    orm: 'none',
+    adapter: null,
+    techTools
+  };
+
+  if (fs.existsSync(path.join(targetDir, 'src', 'app')) || fs.existsSync(path.join(targetDir, 'src', 'pages'))) {
+    config.projectType = 'frontend';
+    config.framework = 'Next.js';
+    config.testRunner = 'Vitest';
+    config.styling = 'Tailwind CSS v4';
+  } else {
+    config.projectType = 'backend';
+    config.framework = 'FastAPI';
+    config.testRunner = 'Pytest';
+  }
+
+  return config;
+}
+
+module.exports = { autoDetectStack };