jhste-skills 0.1.0

package/cli/guard/baseline.mjs

@@ -0,0 +1,64 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { readJsonFile, validateJsonObject } from '../json-file.mjs';
+import { nowIso, relativeDisplay } from '../shared.mjs';
+
+export function loadBaseline(repoRoot, baselinePath, callbacks = {}) {
+  const failConfig = callbacks.failConfig || ((message) => { throw new Error(message); });
+  if (!fs.existsSync(baselinePath)) return new Map();
+  try {
+    const data = readJsonFile(baselinePath, {
+      description: `baseline ${relativeDisplay(repoRoot, baselinePath)}`,
+      validate: validateJsonObject,
+    });
+    const items = Array.isArray(data.violations) ? data.violations : [];
+    return new Map(items.filter((item) => typeof item.fingerprint === 'string').map((item) => [item.fingerprint, item]));
+  } catch (error) {
+    failConfig(`Failed to parse baseline ${relativeDisplay(repoRoot, baselinePath)}.`, [error instanceof Error ? error.message : String(error)]);
+  }
+  return new Map();
+}
+
+export function writeBaseline(baselinePath, violations, existingBaseline = new Map()) {
+  fs.mkdirSync(path.dirname(baselinePath), { recursive: true });
+  const now = nowIso();
+  const rowsByFingerprint = new Map();
+  for (const item of violations) {
+    const existing = existingBaseline.get(item.fingerprint) || {};
+    rowsByFingerprint.set(item.fingerprint, {
+      fingerprint: item.fingerprint,
+      occurrence_key: item.occurrence_key,
+      rule_id: item.rule_id,
+      path: item.path,
+      severity: item.severity,
+      first_seen: existing.first_seen || now,
+      last_seen: now,
+      reason: existing.reason || 'remediation queue item; fix or explicitly keep tracking before enforcing',
+      owner: existing.owner || null,
+      expires_at: existing.expires_at || null,
+      fix_tracking: existing.fix_tracking || null,
+    });
+  }
+  const rows = [...rowsByFingerprint.values()];
+  fs.writeFileSync(baselinePath, `${JSON.stringify({ version: 1, created_at: now, updated_at: now, violations: rows }, null, 2)}\n`);
+}
+
+export function applyBaseline(violations, baselineMap, mode, callbacks = {}) {
+  const failConfig = callbacks.failConfig || ((message) => { throw new Error(message); });
+  if (!['off', 'use', 'update', 'ratchet'].includes(mode)) failConfig(`Unsupported --baseline ${mode}. Use off, use, update, or ratchet.`);
+  if (mode === 'off' || mode === 'update') return violations.map((item) => ({ ...item, baseline_status: 'unmanaged' }));
+  return violations.map((item) => {
+    const baseline = baselineMap.get(item.fingerprint);
+    if (!baseline) return { ...item, baseline_status: 'new' };
+    return {
+      ...item,
+      baseline_status: 'matched',
+      baseline_reason: baseline.reason || '',
+      baseline_first_seen: baseline.first_seen || null,
+      baseline_last_seen: baseline.last_seen || null,
+      baseline_owner: baseline.owner || null,
+      baseline_expires_at: baseline.expires_at || null,
+      baseline_fix_tracking: baseline.fix_tracking || null,
+    };
+  });
+}

package/cli/guard/config.mjs

@@ -0,0 +1,48 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { DEFAULT_BASELINE_PATH } from '../profile.mjs';
+import { relativeDisplay, resolveRepoContainedPath } from '../shared.mjs';
+
+export function profileUsesMode(profile, mode) {
+  if (profile?.mode === mode) return true;
+  if (Object.values(profile?.packs || {}).some((config) => config?.mode === mode)) return true;
+  if (Object.values(profile?.rules || {}).some((config) => config?.mode === mode)) return true;
+  return false;
+}
+
+export function resolveGuardConfig(args, profileState, repoRoot, callbacks = {}) {
+  const failConfig = callbacks.failConfig || ((message) => { throw new Error(message); });
+  const inManagedHook = callbacks.inManagedHook || (() => false);
+  const format = String(args.format || profileState.profile.guard.default_format || 'text');
+  if (!['text', 'json'].includes(format)) failConfig('--format must be text or json.');
+
+  const strictProfile = profileUsesMode(profileState.profile, 'strict');
+  const baselineNewOnlyProfile = profileUsesMode(profileState.profile, 'baseline-new-only');
+  const failOn = String(args['fail-on'] || profileState.profile.guard.fail_on || (strictProfile ? 'error' : 'none'));
+  if (!['none', 'warning', 'error'].includes(failOn)) failConfig('--fail-on must be none, warning, or error.');
+  if (strictProfile && failOn === 'none') {
+    failConfig('Profile mode strict requires enforcement; set guard.fail_on to error/warning or choose a non-strict mode.');
+  }
+
+  const baselineMode = String(args.baseline || (baselineNewOnlyProfile ? 'ratchet' : (profileState.profile.baseline.enabled ? 'use' : 'off')));
+  if (!['off', 'use', 'update', 'ratchet'].includes(baselineMode)) {
+    failConfig(`Unsupported --baseline ${baselineMode}. Use off, use, update, or ratchet.`);
+  }
+  let baselinePath;
+  try {
+    baselinePath = resolveRepoContainedPath(repoRoot, String(args['baseline-path'] || profileState.profile.baseline.path || DEFAULT_BASELINE_PATH), { label: '--baseline-path' });
+  } catch (error) {
+    failConfig(error instanceof Error ? error.message : String(error));
+  }
+  if (inManagedHook() && baselineMode === 'update') {
+    failConfig('Managed hook execution is read-only; --baseline update is not allowed while JHSTE_HOOK_ACTIVE=1.');
+  }
+  if (baselineMode === 'ratchet' && !fs.existsSync(baselinePath)) {
+    failConfig(`--baseline ratchet requires an existing baseline at ${relativeDisplay(repoRoot, baselinePath)}.`);
+  }
+  const scopedArgs = {
+    ...args,
+    scope: args.scope || (strictProfile ? 'all' : (profileState.profile.guard.default_scope || 'changed')),
+  };
+  return { format, failOn, baselineMode, baselinePath, scopedArgs };
+}

package/cli/guard/profile-commands.mjs

@@ -0,0 +1,87 @@
+import { spawnSync } from 'node:child_process';
+import { violation } from './scanners/index.mjs';
+
+const DEFAULT_COMMAND_TIMEOUT_MS = 120000;
+const PROFILE_OUTPUT_LIMIT = 4000;
+
+function redactSecretLike(text) {
+  return String(text || '')
+    .replace(/sk-(?:proj-)?[A-Za-z0-9_-]{20,}/g, '[REDACTED_OPENAI_KEY]')
+    .replace(/gh[pousr]_[A-Za-z0-9_]{20,}/g, '[REDACTED_GITHUB_TOKEN]')
+    .replace(/\bBearer\s+[A-Za-z0-9._~+/=-]{12,}/gi, 'Bearer [REDACTED_TOKEN]')
+    .replace(/\bAuthorization\s*:\s*(?:Bearer|Basic)\s+[^\r\n'"]+/gi, 'Authorization: [REDACTED_AUTHORIZATION]')
+    .replace(/\bCookie\s*:\s*[^\r\n]+/gi, 'Cookie: [REDACTED_COOKIE]')
+    .replace(/\b(password|secret|token|api[_-]?key|authorization|cookie|session)\s*[:=]\s*(['"]?)[^\s'"]{8,}\2/gi, '$1=[REDACTED_SECRET]');
+}
+
+function compactOutput(text) {
+  const value = redactSecretLike(text).trim();
+  if (value.length <= PROFILE_OUTPUT_LIMIT) return value;
+  return `${value.slice(0, PROFILE_OUTPUT_LIMIT)}\n... truncated ${value.length - PROFILE_OUTPUT_LIMIT} chars`;
+}
+
+function safeCommandRuleId(name) {
+  const slug = String(name || 'unnamed').toLowerCase().replace(/[^a-z0-9_.-]+/g, '-').replace(/^-+|-+$/g, '');
+  return `profile.command.${slug || 'unnamed'}`;
+}
+
+export function profileCommandExecutionErrors(commands, { trusted = false, allowShell = false } = {}) {
+  const errors = [];
+  if (!trusted && (commands || []).length > 0) {
+    errors.push('--run-profile-commands executes repo-local commands; pass --trust-repo-profile after reviewing .jhste/profile.yaml.');
+  }
+  for (const command of commands || []) {
+    if (command.run && !allowShell) {
+      errors.push(`Profile command ${command.name || 'unnamed'} uses legacy shell run; pass --allow-profile-shell to execute it.`);
+    }
+  }
+  return errors;
+}
+
+export function runProfileCommands(repoRoot, commands, { allowShell = false } = {}) {
+  const violations = [];
+  const failures = [];
+  for (const command of commands || []) {
+    const usingShell = Boolean(command.run);
+    if (usingShell && !allowShell) {
+      failures.push({
+        code: 'profile.command.config',
+        message: `Profile command shell execution is not allowed: ${command.name}`,
+        details: ['Pass --allow-profile-shell only after reviewing .jhste/profile.yaml.'],
+      });
+      continue;
+    }
+    const executable = usingShell ? command.run : command.cmd;
+    const commandArgs = usingShell ? [] : (command.args || []).map(String);
+    const result = spawnSync(executable, commandArgs, {
+      cwd: repoRoot,
+      shell: usingShell,
+      encoding: 'utf8',
+      timeout: command.timeoutSeconds ? command.timeoutSeconds * 1000 : DEFAULT_COMMAND_TIMEOUT_MS,
+      maxBuffer: 1024 * 1024,
+    });
+    if (result.error) {
+      failures.push({
+        code: 'profile.command.runtime',
+        message: `Profile command could not run: ${command.name}`,
+        details: [redactSecretLike(result.error.message), redactSecretLike(usingShell ? command.run : [command.cmd, ...commandArgs].join(' '))],
+      });
+      continue;
+    }
+    if (result.status !== 0) {
+      const output = compactOutput([result.stdout, result.stderr].filter(Boolean).join('\n'));
+      violations.push(violation({
+        ruleId: safeCommandRuleId(command.name),
+        severity: command.severity || 'error',
+        relPath: '.jhste/profile.yaml',
+        line: 1,
+        symbol: command.name,
+        message: `Profile command failed: ${command.name}`,
+        source: 'profile',
+        confidence: 'high',
+      }));
+      if (output) violations[violations.length - 1].details = [`exit=${result.status}`, output];
+    }
+  }
+  return { violations, failures };
+}

package/cli/guard/registry.mjs

@@ -0,0 +1,47 @@
+export const FINDING_METADATA = {
+  'silent.catch.empty': { family: 'no_silent_failure', pack: 'core', scanner: 'scanSilentFailures' },
+  'silent.promise_catch.empty': { family: 'no_silent_failure', pack: 'core', scanner: 'scanSilentFailures' },
+  'silent.python_except.pass': { family: 'no_silent_failure', pack: 'core', scanner: 'scanSilentFailures' },
+  'silent.catch.fallback_no_reason': { family: 'no_silent_failure', pack: 'core', scanner: 'scanSilentFailures' },
+  'secret.logging': { family: 'no_secret_logging', pack: 'core', scanner: 'scanSecretLogging' },
+  'file_size.warning': { family: 'file_size_advisory', pack: 'core', scanner: 'scanFileSizeAdvisory' },
+  'file_size.review': { family: 'file_size_advisory', pack: 'core', scanner: 'scanFileSizeAdvisory' },
+  'boundary.import.server_in_client': { family: 'component_responsibility', pack: 'web', scanner: 'scanClientServerBoundary' },
+  'workflow.input_interpolation.run': { family: 'workflow_security', pack: 'core', scanner: 'scanWorkflowSecurity' },
+  'workflow.action.unpinned': { family: 'workflow_security', pack: 'core', scanner: 'scanWorkflowSecurity' },
+  'input.file_parse_unvalidated': { family: 'external_input_validation', pack: 'core', scanner: 'scanExternalInputValidation' },
+  'input.third_party_json_unvalidated': { family: 'external_input_validation', pack: 'core', scanner: 'scanExternalInputValidation' },
+  'input.request_body_direct_use': { family: 'external_input_validation', pack: 'core', scanner: 'scanExternalInputValidation' },
+  'input.env_export_unvalidated': { family: 'external_input_validation', pack: 'core', scanner: 'scanExternalInputValidation' },
+  'responsibility.page.budget': { family: 'responsibility_budget', pack: 'core', scanner: 'scanResponsibilityBudget' },
+  'responsibility.client.budget': { family: 'responsibility_budget', pack: 'core', scanner: 'scanResponsibilityBudget' },
+  'responsibility.route.budget': { family: 'responsibility_budget', pack: 'core', scanner: 'scanResponsibilityBudget' },
+  'responsibility.script.budget': { family: 'responsibility_budget', pack: 'core', scanner: 'scanResponsibilityBudget' },
+  'responsibility.python_orchestrator.budget': { family: 'responsibility_budget', pack: 'core', scanner: 'scanResponsibilityBudget' },
+  'srp.function.length': { family: 'single_responsibility_advisory', pack: 'core', scanner: 'scanSingleResponsibility' },
+  'srp.function.mixed_responsibility': { family: 'single_responsibility_advisory', pack: 'core', scanner: 'scanSingleResponsibility' },
+  'srp.module.mixed_exports': { family: 'single_responsibility_advisory', pack: 'core', scanner: 'scanSingleResponsibility' },
+  'state.non_null_assertion': { family: 'null_state_safety', pack: 'core', scanner: 'scanStateSafety' },
+  'state.async_ui_missing_fallback': { family: 'null_state_safety', pack: 'core', scanner: 'scanStateSafety' },
+  'authz.scope_not_visible': { family: 'authz_data_isolation', pack: 'core', scanner: 'scanAuthzDataIsolation' },
+  'authz.read_scope_not_visible': { family: 'authz_data_isolation', pack: 'core', scanner: 'scanAuthzDataIsolation' },
+  'authz.mutation_without_auth_context': { family: 'authz_data_isolation', pack: 'core', scanner: 'scanAuthzDataIsolation' },
+  'authz.read_without_auth_context': { family: 'authz_data_isolation', pack: 'core', scanner: 'scanAuthzDataIsolation' },
+  'runtime.env_direct_access': { family: 'build_runtime_env_safety', pack: 'core', scanner: 'scanRuntimeEnvSafety' },
+  'runtime.import_meta_env_direct_access': { family: 'build_runtime_env_safety', pack: 'core', scanner: 'scanRuntimeEnvSafety' },
+  'runtime.getenv_direct_access': { family: 'build_runtime_env_safety', pack: 'core', scanner: 'scanRuntimeEnvSafety' },
+  'write.loop_without_transaction': { family: 'write_safety_idempotency', pack: 'core', scanner: 'scanWriteSafety' },
+  'write.mutation_retry_safety': { family: 'write_safety_idempotency', pack: 'core', scanner: 'scanWriteSafety' },
+  'contract.boundary_without_schema': { family: 'api_contract_compatibility', pack: 'core', scanner: 'scanApiContractCompatibility' },
+  'contract.raw_storage_response': { family: 'api_contract_compatibility', pack: 'core', scanner: 'scanApiContractCompatibility' },
+  'performance.multiple_fetch_sources': { family: 'performance_duplicate_fetch', pack: 'core', scanner: 'scanPerformanceDuplicateFetch' },
+  'performance.fetch_in_effect': { family: 'performance_duplicate_fetch', pack: 'core', scanner: 'scanPerformanceDuplicateFetch' },
+  'sql.raw_interpolation': { family: 'sql_parameter_binding', pack: 'database', scanner: 'scanSqlParameterBinding' },
+  'error.public_raw_details': { family: 'public_safe_error', pack: 'api', scanner: 'scanPublicSafeError' },
+  'database.raw_row_public_response': { family: 'db_row_validation', pack: 'database', scanner: 'scanDbRowValidation' },
+  'route.direct_db_access': { family: 'thin_api_route', pack: 'api', scanner: 'scanThinApiRoute' },
+  'type.escape': { family: 'type_escape_advisory', pack: 'web', scanner: 'scanTypeEscapeAdvisory' },
+  'side_effect.hidden_in_helper': { family: 'side_effect_boundary', pack: 'core', scanner: 'scanSideEffectBoundary' },
+  'crawler.producer_direct_persistence': { family: 'crawler_producer_boundary', pack: 'crawler', scanner: 'scanCrawlerProducerBoundary' },
+  'python.broad_exception': { family: 'broad_exception_advisory', pack: 'core', scanner: 'scanBroadExceptionAdvisory' },
+};

package/cli/guard/reporting.mjs

@@ -0,0 +1,165 @@
+import { nowIso } from '../shared.mjs';
+import { FINDING_METADATA } from './registry.mjs';
+
+export const EXIT_VIOLATION = 1;
+export const EXIT_GUARD_FAILURE = 2;
+export const SEVERITIES = ['info', 'warning', 'error'];
+
+export function summarize(violations, failures = []) {
+  const active = violations.filter((item) => item.baseline_status !== 'matched');
+  const baselineMatched = violations.length - active.length;
+  const summary = {
+    error: 0,
+    warning: 0,
+    info: 0,
+    baseline_matched: baselineMatched,
+    // Backward-compatible alias for schema_version: 1 consumers. Prefer baseline_matched in new integrations.
+    suppressed: baselineMatched,
+    failures: failures.length,
+  };
+  for (const item of active) summary[item.severity] = (summary[item.severity] || 0) + 1;
+  return summary;
+}
+
+export function guardResult(violations, failures = [], meta = {}) {
+  return {
+    schema_version: 1,
+    generated_at: nowIso(),
+    summary: summarize(violations, failures),
+    meta,
+    violations,
+    failures,
+  };
+}
+
+export function severityMeets(severity, threshold) {
+  if (threshold === 'none') return false;
+  const severityIndex = SEVERITIES.indexOf(severity);
+  const thresholdIndex = SEVERITIES.indexOf(threshold);
+  return severityIndex >= thresholdIndex;
+}
+
+export function exitCodeFor(result, failOn, baselineMode) {
+  if (result.failures.length > 0) return EXIT_GUARD_FAILURE;
+  if (baselineMode === 'update') return 0;
+  const active = result.violations.filter((item) => item.baseline_status !== 'matched');
+  if (baselineMode === 'ratchet' && active.length > 0) return EXIT_VIOLATION;
+  if (active.some((item) => severityMeets(item.severity, failOn))) return EXIT_VIOLATION;
+  return 0;
+}
+
+function guidanceForFinding(item) {
+  const family = item.rule_family || FINDING_METADATA[item.rule_id]?.family || item.rule_id;
+  if (family === 'file_size_advisory') {
+    return {
+      means: 'This file exceeds the configured line limit. It is not proof of a bug, but it increases the chance that review, conflict resolution, and test boundaries become harder to manage.',
+      next: 'Split the file along natural boundaries so each helper, adapter, scanner family, or test fixture carries one main responsibility at a time.',
+    };
+  }
+  if (family === 'responsibility_budget') {
+    return {
+      means: 'This file may be combining multiple responsibilities such as UI, state, IO, validation, persistence, and response shaping.',
+      next: 'Check whether the code can move into smaller modules with explicit names such as loader, service, repository, or view.',
+    };
+  }
+
+  if (family === 'single_responsibility_advisory') {
+    return {
+      means: 'This class, module, or function may have more than one reason to change. The finding is heuristic and should be reviewed, not treated as proof.',
+      next: 'Name the one main responsibility, then move only independently changing work behind a real seam; avoid extracting shallow pass-through wrappers.',
+    };
+  }
+  if (family === 'external_input_validation') {
+    return {
+      means: 'This is a candidate path where external input such as files, request bodies, third-party API data, or env values may be trusted without shape validation.',
+      next: 'Add an explicit validation boundary such as schema.safeParse, a validator, or assert/parseEnv, or make an existing validation step clearly visible in code.',
+    };
+  }
+  if (family === 'no_secret_logging') {
+    return {
+      means: 'This is a candidate path where logs may include sensitive fields such as tokens, passwords, or session values.',
+      next: 'Confirm that real secrets are not emitted, and redact values before logging when needed.',
+    };
+  }
+  if (family === 'build_runtime_env_safety') {
+    return {
+      means: 'Direct env reads can fail differently across build and runtime environments, producing undefined values or invalid configuration.',
+      next: 'Use startup-time env schema validation, defaults, or a requiredEnv helper so failure points are explicit.',
+    };
+  }
+  if (family === 'write_safety_idempotency') {
+    return {
+      means: 'This is a candidate path where repeated or retried writes could create duplicate records or partial success states.',
+      next: 'Check whether transactions, upserts, idempotency keys, dedupe logic, or batch semantics are the right safety mechanism here.',
+    };
+  }
+  if (family === 'api_contract_compatibility') {
+    return {
+      means: 'The request or response shape may be unclear at the API boundary, or storage-layer shapes may be leaking directly to callers.',
+      next: 'Add an input schema and public DTO mapping so the caller-facing contract stays explicit and stable.',
+    };
+  }
+  if (family === 'authz_data_isolation') {
+    return {
+      means: 'Authn/authz checks or tenant-owner scoping may be unclear in code, creating a candidate risk of cross-user data access.',
+      next: 'Make requireUser/permission checks and owner filters such as userId, orgId, or tenantId visible in the same flow.',
+    };
+  }
+  if (family === 'performance_duplicate_fetch') {
+    return {
+      means: 'Duplicate fetches or missing cache use in the same path may cause slow rendering or unnecessary network calls.',
+      next: 'Check whether these calls can be consolidated behind a shared loader, query hook, or cache key.',
+    };
+  }
+  if (item.confidence === 'low') {
+    return {
+      means: 'This is a low-confidence static heuristic candidate. It does not mean the code is definitely buggy.',
+      next: 'If the code is safe, make the validation or safeguard more visible. If the risk is real, add a small boundary fix.',
+    };
+  }
+  return null;
+}
+
+export function printResult(result, format) {
+  if (format === 'json') {
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+  const { summary } = result;
+  console.log(`jhste guard: errors=${summary.error} warnings=${summary.warning} info=${summary.info} baseline-matched=${summary.baseline_matched} failures=${summary.failures}`);
+  if (result.meta?.git?.file_source) {
+    const fallback = result.meta.git.file_source === 'filesystem-fallback' ? ` (fallback: ${result.meta.git.fallback_reason || 'unknown reason'})` : '';
+    console.log(`File collection: ${result.meta.git.file_source}${fallback}`);
+  }
+  if (result.failures.length) {
+    console.log('\nGuard failures:');
+    for (const failure of result.failures) console.log(`- [${failure.code}] ${failure.message}${failure.details?.length ? ` (${failure.details.join('; ')})` : ''}`);
+  }
+  const active = result.violations.filter((item) => item.baseline_status !== 'matched');
+  const visible = active.slice(0, 80);
+  if (visible.length) {
+    console.log('\nViolations:');
+    for (const item of visible) {
+      const confidence = item.confidence ? ` [${item.confidence}-confidence]` : '';
+      const family = item.rule_family && item.rule_family !== item.rule_id ? ` (${item.rule_family})` : '';
+      const related = item.related_key ? ` [related: ${item.related_key}]` : '';
+      console.log(`- [${item.severity}]${confidence} ${item.rule_id}${family} ${item.path}:${item.line}${related} — ${item.message}`);
+      const guidance = guidanceForFinding(item);
+      if (guidance) {
+        console.log(`  Meaning: ${guidance.means}`);
+        console.log(`  Next: ${guidance.next}`);
+      }
+    }
+    if (active.length > visible.length) console.log(`- ... ${active.length - visible.length} more omitted from text output`);
+  }
+  const matched = result.violations.filter((item) => item.baseline_status === 'matched');
+  if (matched.length) {
+    console.log('\nExisting known issues encountered from baseline (remediation queue; not a pass):');
+    for (const item of matched.slice(0, 40)) {
+      const family = item.rule_family && item.rule_family !== item.rule_id ? ` (${item.rule_family})` : '';
+      const reason = item.baseline_reason ? ` — ${item.baseline_reason}` : '';
+      console.log(`- [${item.severity}] ${item.rule_id}${family} ${item.path}:${item.line}${reason}`);
+    }
+    if (matched.length > 40) console.log(`- ... ${matched.length - 40} more baseline issues encountered in this scan scope`);
+  }
+}

package/cli/guard/scanners/code-health.mjs

@@ -0,0 +1,213 @@
+import path from 'node:path';
+import {
+  hasUseClientDirective,
+  isSourceCodePath,
+  lineAt,
+  violation,
+} from './utils.mjs';
+
+export function scanSilentFailures(relPath, text) {
+  if (!isSourceCodePath(relPath)) return [];
+  const out = [];
+  for (const match of text.matchAll(/\bcatch\s*(?:\([^)]*\))?\s*\{\s*\}/gsu)) {
+    const before = text.slice(Math.max(0, (match.index || 0) - 40), match.index || 0);
+    if (/['"`]\s*$/.test(before)) continue;
+    if (/matchAll\s*\(\s*\/|RegExp\s*\(/.test(before)) continue;
+    out.push(violation({
+      ruleId: 'silent.catch.empty',
+      severity: 'error',
+      relPath,
+      line: lineAt(text, match.index || 0),
+      symbol: 'catch{}',
+      message: 'Empty catch block hides failures; return a failure, log a redacted reason, or document an intentional fallback.',
+      confidence: 'high',
+    }));
+  }
+  for (const match of text.matchAll(/\.catch\s*\(\s*(?:async\s*)?\(?\s*[^)]*\)?\s*=>\s*\{\s*\}\s*\)/gsu)) {
+    out.push(violation({
+      ruleId: 'silent.promise_catch.empty',
+      severity: 'error',
+      relPath,
+      line: lineAt(text, match.index || 0),
+      symbol: '.catch-empty',
+      message: 'Empty promise rejection handler hides failures; return a failure, log a redacted reason, or document an intentional fallback.',
+      confidence: 'high',
+    }));
+  }
+  for (const match of text.matchAll(/(?:^|\n)\s*except\s+(?:Exception|BaseException)?\s*:\s*pass\b/gu)) {
+    out.push(violation({
+      ruleId: 'silent.python_except.pass',
+      severity: 'error',
+      relPath,
+      line: lineAt(text, match.index || 0),
+      symbol: 'except-pass',
+      message: 'Broad Python exception handler with pass hides failures; record a redacted reason or return an explicit fallback result.',
+      confidence: 'high',
+    }));
+  }
+  for (const match of text.matchAll(/\bcatch\s*(?:\([^)]*\))?\s*\{(?:(?!\}).){0,180}\breturn\s+(?:\[\]|null|undefined|false)\s*;?\s*\}/gsu)) {
+    const block = match[0];
+    if (/console\.|logger\.|reason|fallback|best[- ]?effort|optional|allowlist/i.test(block)) continue;
+    out.push(violation({
+      ruleId: 'silent.catch.fallback_no_reason',
+      severity: 'warning',
+      relPath,
+      line: lineAt(text, match.index || 0),
+      symbol: 'catch-fallback',
+      message: 'Exception is converted to an empty/null fallback without log, metric, reason, or best-effort marker.',
+      confidence: 'medium',
+    }));
+  }
+  return out;
+}
+
+export function scanWorkflowSecurity(relPath, text) {
+  if (!/^\.github\/workflows\/.+\.ya?ml$/u.test(relPath)) return [];
+  const out = [];
+  const lines = text.split(/\r?\n/);
+  lines.forEach((line, index) => {
+    if (/\brun\s*:/.test(line) && /\$\{\{\s*(github\.event\.inputs|inputs)\./.test(line)) {
+      out.push(violation({
+        ruleId: 'workflow.input_interpolation.run',
+        severity: 'error',
+        relPath,
+        line: index + 1,
+        symbol: 'workflow-input-run',
+        message: 'Workflow run command directly interpolates dispatch input; pass input through env and validate it before shell use.',
+        confidence: 'high',
+      }));
+    }
+    if (/\buses\s*:\s*[^\s#]+\/[^\s#]+@(?:v\d+|main|master)\b/.test(line)) {
+      out.push(violation({
+        ruleId: 'workflow.action.unpinned',
+        severity: 'warning',
+        relPath,
+        line: index + 1,
+        symbol: line.trim(),
+        message: 'External workflow action is not pinned to a full commit SHA; consider pinning for supply-chain safety.',
+        confidence: 'medium',
+      }));
+    }
+  });
+  return out;
+}
+
+export function scanFileSizeAdvisory(relPath, text, settings) {
+  const ext = path.extname(relPath).toLowerCase();
+  if (!['.js', '.jsx', '.ts', '.tsx', '.mjs', '.cjs', '.py'].includes(ext)) return [];
+  const lineCount = text.split(/\r?\n/).length;
+  if (lineCount >= settings.source_file_review_lines) {
+    return [violation({
+      ruleId: 'file_size.review',
+      severity: 'warning',
+      relPath,
+      symbol: 'source-file-review',
+      message: `${lineCount} lines in source file; limit is ${settings.source_file_review_lines}. Large files are harder to review, test, and safely change.`,
+      confidence: 'medium',
+    })];
+  }
+  if (lineCount >= settings.source_file_warning_lines) {
+    return [violation({
+      ruleId: 'file_size.warning',
+      severity: 'info',
+      relPath,
+      symbol: 'source-file-warning',
+      message: `${lineCount} lines in source file; warning threshold is ${settings.source_file_warning_lines}. Watch for responsibility creep.`,
+      confidence: 'medium',
+    })];
+  }
+  return [];
+}
+
+export function scanResponsibilityBudget(relPath, text, settings) {
+  const ext = path.extname(relPath).toLowerCase();
+  if (!['.js', '.jsx', '.ts', '.tsx', '.mjs', '.cjs', '.py'].includes(ext)) return [];
+  const lineCount = text.split(/\r?\n/).length;
+  const out = [];
+  const nextPage = relPath.endsWith('/page.tsx') && /(^|\/)(app|src\/app|apps\/[^/]+\/src\/app)\//.test(relPath);
+  if (nextPage && lineCount > settings.next_page_review_lines) {
+    out.push(violation({ ruleId: 'responsibility.page.budget', severity: 'warning', relPath, symbol: 'next-page', message: `${lineCount} lines in Next page; review loader/model/view split.`, confidence: 'medium' }));
+  }
+  if (hasUseClientDirective(text) && lineCount > settings.client_module_review_lines) {
+    out.push(violation({ ruleId: 'responsibility.client.budget', severity: 'warning', relPath, symbol: 'use-client', message: `${lineCount} lines in client module; review hook/adapter/presentation split.`, confidence: 'medium' }));
+  }
+  const routeLike = /(^|\/)(api|routes?|controllers?|pages\/api)\//i.test(relPath) || /route\.(ts|js)$/.test(relPath);
+  if (routeLike && lineCount >= settings.route_review_lines) {
+    out.push(violation({ ruleId: 'responsibility.route.budget', severity: 'warning', relPath, symbol: 'route', message: `${lineCount} lines in route/controller-like file; review auth/validation/service/response seams.`, confidence: 'medium' }));
+  }
+  const scriptPipeline = /(^|\/)scripts\/(data|ops|import|imports|backfill|repair|migrate|migration)\//.test(relPath);
+  if (scriptPipeline && lineCount >= settings.import_ops_script_review_lines) {
+    out.push(violation({ ruleId: 'responsibility.script.budget', severity: 'warning', relPath, symbol: 'script-pipeline', message: `${lineCount} lines in import/ops-style script; review CLI/loader/transform/persist/report seams.`, confidence: 'medium' }));
+  }
+  if (ext === '.py' && /(^|\/)(main|.*orchestrator|.*runner|stage_runner)\.py$/.test(relPath) && lineCount >= settings.python_orchestrator_review_lines) {
+    out.push(violation({ ruleId: 'responsibility.python_orchestrator.budget', severity: 'warning', relPath, symbol: 'python-orchestrator', message: `${lineCount} lines in Python orchestrator/runner; review policy/IO/runtime/notification/result seams.`, confidence: 'medium' }));
+  }
+  return out;
+}
+
+export function scanSecretLogging(relPath, text) {
+  if (!isSourceCodePath(relPath)) return [];
+  const out = [];
+  const lines = text.split(/\r?\n/);
+  lines.forEach((line, index) => {
+    if (/\b(console\.(log|info|warn|error|debug)|logger\.(info|warn|error|debug)|print)\s*\(/.test(line)
+      && /\b(secret|token|password|authorization|cookie|session|api[_-]?key)\b/i.test(line)) {
+      const withoutStrings = line.replace(/(['"`])(?:\\.|(?!\1).)*\1/gu, '');
+      const hasSecretIdentifier = /\b[A-Za-z_$][\w$]*(secret|token|password|authorization|cookie|session|apiKey|api_key)[\w$]*\b/i.test(withoutStrings)
+        || /\b(secret|token|password|authorization|cookie|session|api[_-]?key)[A-Za-z_$][\w$]*\b/i.test(withoutStrings);
+      const stringOnly = !hasSecretIdentifier;
+      out.push(violation({
+        ruleId: 'secret.logging',
+        severity: stringOnly ? 'warning' : 'error',
+        relPath,
+        line: index + 1,
+        symbol: 'secret-like-log',
+        message: stringOnly
+          ? 'Log message contains secret-like wording; confirm it does not include secret values.'
+          : 'Log statement references secret-like data; log a stable request id or redacted reason code instead.',
+        confidence: stringOnly ? 'low' : 'high',
+      }));
+    }
+  });
+  return out;
+}
+
+export function scanTypeEscapeAdvisory(relPath, text) {
+  if (!/\.(tsx?|jsx?)$/u.test(relPath)) return [];
+  const out = [];
+  const lines = text.split(/\r?\n/);
+  lines.forEach((line, index) => {
+    if (/\bas\s+any\b|:\s*any\b|@ts-ignore/.test(line)) {
+      out.push(violation({
+        ruleId: 'type.escape',
+        severity: 'warning',
+        relPath,
+        line: index + 1,
+        symbol: 'type-escape',
+        message: 'Broad TypeScript escape detected; localize it or add a boundary parser/type guard where data enters.',
+        confidence: 'medium',
+      }));
+    }
+  });
+  return out;
+}
+
+export function scanBroadExceptionAdvisory(relPath, text) {
+  if (!relPath.endsWith('.py')) return [];
+  const out = [];
+  const lines = text.split(/\r?\n/);
+  lines.forEach((line, index) => {
+    if (/^\s*except\s*(?:Exception|BaseException)?\s*(?:as\s+\w+)?\s*:/.test(line) && !/\bpass\b/.test(line)) {
+      out.push(violation({
+        ruleId: 'python.broad_exception',
+        severity: 'warning',
+        relPath,
+        line: index + 1,
+        symbol: 'broad-exception',
+        message: 'Broad Python exception handler detected; prefer specific exceptions or record a clear fallback reason.',
+        confidence: 'low',
+      }));
+    }
+  });
+  return out;
+}