jhste-skills 0.1.0

package/cli/guard.mjs

@@ -0,0 +1,125 @@
+#!/usr/bin/env node
+import path from 'node:path';
+import { KIT_ROOT, findGitRoot, parseArgs, relativeDisplay } from './shared.mjs';
+import {
+  fileSizeSettings,
+  loadProfileConfig,
+  responsibilityBudgetSettings,
+  singleResponsibilitySettings,
+  validateProfileConfig,
+} from './profile.mjs';
+import { readJsonFile, validateJsonObject } from './json-file.mjs';
+import { loadBaseline, writeBaseline, applyBaseline } from './guard/baseline.mjs';
+import { resolveGuardConfig } from './guard/config.mjs';
+import { profileCommandExecutionErrors, runProfileCommands } from './guard/profile-commands.mjs';
+import { guardResult, printResult, exitCodeFor } from './guard/reporting.mjs';
+import { resolveScopeFiles } from './guard/scope.mjs';
+import { scanFile } from './guard/scanners/index.mjs';
+
+const EXIT_VIOLATION = 1;
+const EXIT_GUARD_FAILURE = 2;
+const EXIT_CONFIG_FAILURE = 3;
+let currentFormat = 'text';
+
+function inManagedHook() {
+  return process.env.JHSTE_HOOK_ACTIVE === '1';
+}
+
+function failGuard(message, details = []) {
+  const result = guardResult([], [{ code: 'guard.runtime', message, details }]);
+  printResult(result, currentFormat);
+  process.exit(EXIT_GUARD_FAILURE);
+}
+
+function failConfig(message, details = []) {
+  const result = guardResult([], [{ code: 'guard.config', message, details }]);
+  printResult(result, currentFormat);
+  process.exit(EXIT_CONFIG_FAILURE);
+}
+
+function toolVersion() {
+  try {
+    const pkg = readJsonFile(path.join(KIT_ROOT, 'package.json'), {
+      description: 'package.json',
+      validate: validateJsonObject,
+    });
+    return String(pkg.version || '0.0.0');
+  } catch {
+    return '0.0.0';
+  }
+}
+
+function requestedOutputFormat(args, profileState = null) {
+  const requested = String(args.format || profileState?.profile?.guard?.default_format || 'text');
+  return ['text', 'json'].includes(requested) ? requested : 'text';
+}
+
+async function main() {
+  const startedAt = Date.now();
+  const args = parseArgs(process.argv.slice(2));
+  currentFormat = requestedOutputFormat(args);
+  const repoRoot = findGitRoot(args.repo || process.cwd());
+  const profileState = loadProfileConfig(repoRoot);
+  currentFormat = requestedOutputFormat(args, profileState);
+  const profileErrors = validateProfileConfig(profileState.profile);
+  if (profileErrors.length) failConfig(`Invalid profile ${relativeDisplay(repoRoot, profileState.path)}.`, profileErrors);
+  const { format, failOn, baselineMode, baselinePath, scopedArgs } = resolveGuardConfig(args, profileState, repoRoot, {
+    failConfig,
+    inManagedHook,
+  });
+  currentFormat = format;
+  const scope = resolveScopeFiles(repoRoot, scopedArgs, { failConfig, failGuard });
+  const violations = [];
+  const failures = [];
+  const scanSettings = {
+    profile: profileState.profile,
+    scope: scope.scope,
+    fileSize: fileSizeSettings(profileState.profile),
+    responsibilityBudget: responsibilityBudgetSettings(profileState.profile),
+    singleResponsibility: singleResponsibilitySettings(profileState.profile),
+  };
+  for (const relPath of scope.files) {
+    const result = scanFile(repoRoot, relPath, scanSettings);
+    violations.push(...result.violations);
+    if (result.failure) failures.push(result.failure);
+  }
+  if (args['run-profile-commands']) {
+    if (inManagedHook()) {
+      failConfig('Managed hook execution is read-only; --run-profile-commands is not allowed while JHSTE_HOOK_ACTIVE=1.');
+    }
+    const executionErrors = profileCommandExecutionErrors(profileState.profile.commands, {
+      trusted: Boolean(args['trust-repo-profile']),
+      allowShell: Boolean(args['allow-profile-shell']),
+    });
+    if (executionErrors.length) failConfig('Profile command execution requires explicit trust.', executionErrors);
+    const profile = runProfileCommands(repoRoot, profileState.profile.commands, {
+      allowShell: Boolean(args['allow-profile-shell']),
+    });
+    violations.push(...profile.violations);
+    failures.push(...profile.failures);
+  }
+  const baselineMap = loadBaseline(repoRoot, baselinePath, { failConfig });
+  if (baselineMode === 'update' && failures.length === 0) writeBaseline(baselinePath, violations, baselineMap);
+  const managed = applyBaseline(violations, baselineMap, baselineMode, { failConfig });
+  const result = guardResult(managed, failures, {
+    tool_version: toolVersion(),
+    scope: scope.scope,
+    files_considered: scope.files_considered,
+    files_scanned: scope.files.length,
+    fail_on: failOn,
+    baseline_mode: baselineMode,
+    baseline_path: relativeDisplay(repoRoot, baselinePath),
+    profile_path: profileState.exists ? relativeDisplay(repoRoot, profileState.path) : null,
+    duration_ms: Date.now() - startedAt,
+    git: scope.git,
+  });
+  printResult(result, format);
+  process.exit(exitCodeFor(result, failOn, baselineMode));
+}
+
+main().catch((error) => {
+  const message = error instanceof Error ? error.message : String(error);
+  const result = guardResult([], [{ code: 'guard.unhandled', message, details: [] }]);
+  printResult(result, currentFormat);
+  process.exit(EXIT_GUARD_FAILURE);
+});

package/cli/hook-utils.mjs

@@ -0,0 +1,127 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { ensureDir, KIT_ROOT, relativeDisplay } from './shared.mjs';
+import { readJsonFile, validateJsonObject } from './json-file.mjs';
+
+export const EXIT_CONFIG_FAILURE = 3;
+export const MANAGED_START = '# jhste-skills managed hook start';
+export const MANAGED_END = '# jhste-skills managed hook end';
+export const HOOKS = new Set(['pre-commit', 'pre-push']);
+
+export function git(repoRoot, args) {
+  return execFileSync('git', ['-C', repoRoot, ...args], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }).trim();
+}
+
+export function gitHooksDir(repoRoot) {
+  git(repoRoot, ['rev-parse', '--is-inside-work-tree']);
+  return git(repoRoot, ['rev-parse', '--path-format=absolute', '--git-path', 'hooks']);
+}
+
+export function selectedHooks(value) {
+  const hook = String(value || 'pre-commit');
+  if (hook === 'all') return ['pre-commit', 'pre-push'];
+  if (!HOOKS.has(hook)) throw new Error('--hook must be pre-commit, pre-push, or all.');
+  return [hook];
+}
+
+export function isManagedHook(content) {
+  return content.includes(MANAGED_START) && content.includes(MANAGED_END);
+}
+
+export function guardScopeForHook(hook) {
+  return hook === 'pre-push' ? 'changed' : 'staged';
+}
+
+function toolVersion() {
+  try {
+    const pkg = readJsonFile(path.join(KIT_ROOT, 'package.json'), {
+      description: 'package.json',
+      validate: validateJsonObject,
+    });
+    return String(pkg.version || '0.0.0');
+  } catch {
+    return '0.0.0';
+  }
+}
+
+export function hookScript({ hook, mode, failOn }) {
+  const scope = guardScopeForHook(hook);
+  const cliPath = path.join(path.dirname(fileURLToPath(import.meta.url)), 'index.mjs');
+  const escapedCliPath = cliPath.replaceAll("'", "'\\''");
+  return `#!/usr/bin/env sh
+${MANAGED_START}
+# mode=${mode} hook=${hook} scope=${scope}
+# jhste-skills version=${toolVersion()}
+set -u
+if [ "\${JHSTE_HOOK_ACTIVE:-}" = "1" ]; then
+  echo "jhste-skills: nested managed hook invocation skipped."
+  exit 0
+fi
+run_jhste_skills() {
+  if [ -f '${escapedCliPath}' ]; then
+    node '${escapedCliPath}' "$@"
+  elif command -v jhste-skills >/dev/null 2>&1; then
+    jhste-skills "$@"
+  else
+    echo "jhste-skills: CLI not found. Expected '${escapedCliPath}' or jhste-skills on PATH." >&2
+    return 2
+  fi
+}
+
+echo "jhste-skills: running guard --scope ${scope} --fail-on ${failOn} (${mode})"
+export JHSTE_HOOK_ACTIVE=1
+run_jhste_skills guard --scope ${scope} --format text --fail-on ${failOn}
+status=$?
+if [ "$status" -eq 2 ] || [ "$status" -eq 3 ]; then
+  echo "jhste-skills: guard runtime/config failure is not a validation pass (exit $status)."
+fi
+if [ "${mode}" = "advisory" ]; then
+  if [ "$status" -ne 0 ]; then
+    echo "jhste-skills: advisory hook reported issues but did not block. Use --mode blocking to enforce."
+  fi
+  exit 0
+fi
+exit "$status"
+${MANAGED_END}
+`;
+}
+
+export function preflightHookTarget(repoRoot, target) {
+  let hooksDir;
+  try {
+    hooksDir = gitHooksDir(repoRoot);
+  } catch {
+    return { target, status: 'failed', reason: `not a git repository: ${repoRoot}` };
+  }
+
+  const file = path.join(hooksDir, target);
+  if (!fs.existsSync(file)) return { target, status: 'will-install', path: file };
+  const existing = fs.readFileSync(file, 'utf8');
+  if (isManagedHook(existing)) return { target, status: 'will-refresh', path: file };
+  return {
+    target,
+    status: 'skipped-non-managed',
+    path: file,
+    reason: `${relativeDisplay(repoRoot, file)} already exists and is not managed by jhste-skills`,
+  };
+}
+
+export function installHookTarget(repoRoot, { target, mode, failOn }) {
+  const preflight = preflightHookTarget(repoRoot, target);
+  if (preflight.status === 'failed' || preflight.status === 'skipped-non-managed') {
+    return { ...preflight, mode, failOn };
+  }
+  const hooksDir = path.dirname(preflight.path);
+  ensureDir(hooksDir);
+  fs.writeFileSync(preflight.path, hookScript({ hook: target, mode, failOn }), { mode: 0o755 });
+  fs.chmodSync(preflight.path, 0o755);
+  return {
+    target,
+    mode,
+    failOn,
+    path: preflight.path,
+    status: preflight.status === 'will-refresh' ? 'refreshed-managed' : 'installed',
+  };
+}

package/cli/hooks.mjs

@@ -0,0 +1,127 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+import path from 'node:path';
+import { findGitRoot, parseArgs, relativeDisplay } from './shared.mjs';
+import {
+  EXIT_CONFIG_FAILURE,
+  HOOKS,
+  gitHooksDir,
+  hookScript,
+  isManagedHook,
+  selectedHooks,
+} from './hook-utils.mjs';
+
+function usage() {
+  console.log(`jhste-skills hooks
+
+Usage:
+  jhste-skills hooks install [--repo <path>] [--mode advisory|blocking] [--hook pre-commit|pre-push|all] [--fail-on none|warning|error]
+  jhste-skills hooks uninstall [--repo <path>] [--hook pre-commit|pre-push|all]
+  jhste-skills hooks doctor [--repo <path>]
+
+Notes:
+  install never overwrites a non-managed existing hook.
+  advisory hooks print guard output but return success.
+  blocking hooks return the guard exit code.
+`);
+}
+
+function fail(message) {
+  console.error(`jhste-skills hooks: ${message}`);
+  process.exit(EXIT_CONFIG_FAILURE);
+}
+
+function install(repoRoot, args) {
+  const mode = String(args.mode || 'advisory');
+  if (!['advisory', 'blocking'].includes(mode)) fail('--mode must be advisory or blocking.');
+  const failOn = String(args['fail-on'] || (mode === 'blocking' ? 'error' : 'none'));
+  if (!['none', 'warning', 'error'].includes(failOn)) fail('--fail-on must be none, warning, or error.');
+  let hooksDir;
+  try {
+    hooksDir = gitHooksDir(repoRoot);
+  } catch {
+    fail(`not a git repository: ${repoRoot}`);
+  }
+  fs.mkdirSync(hooksDir, { recursive: true });
+  let hooks;
+  try {
+    hooks = selectedHooks(args.hook);
+  } catch (error) {
+    fail(error.message);
+  }
+  for (const hook of hooks) {
+    const file = path.join(hooksDir, hook);
+    if (fs.existsSync(file)) {
+      const existing = fs.readFileSync(file, 'utf8');
+      if (!isManagedHook(existing)) {
+        fail(`${relativeDisplay(repoRoot, file)} already exists and is not managed by jhste-skills; refusing to overwrite.`);
+      }
+    }
+  }
+  for (const hook of hooks) {
+    const file = path.join(hooksDir, hook);
+    fs.writeFileSync(file, hookScript({ hook, mode, failOn }), { mode: 0o755 });
+    fs.chmodSync(file, 0o755);
+    console.log(`installed ${relativeDisplay(repoRoot, file)} (${mode}, fail-on=${failOn})`);
+  }
+}
+
+function uninstall(repoRoot, args) {
+  let hooksDir;
+  try {
+    hooksDir = gitHooksDir(repoRoot);
+  } catch {
+    fail(`not a git repository: ${repoRoot}`);
+  }
+  let hooks;
+  try {
+    hooks = selectedHooks(args.hook);
+  } catch (error) {
+    fail(error.message);
+  }
+  for (const hook of hooks) {
+    const file = path.join(hooksDir, hook);
+    if (!fs.existsSync(file)) {
+      console.log(`${hook}: not installed`);
+      continue;
+    }
+    const existing = fs.readFileSync(file, 'utf8');
+    if (!isManagedHook(existing)) {
+      console.log(`${hook}: existing non-managed hook left untouched`);
+      continue;
+    }
+    fs.rmSync(file);
+    console.log(`${hook}: removed managed hook`);
+  }
+}
+
+function doctor(repoRoot) {
+  let hooksDir;
+  try {
+    hooksDir = gitHooksDir(repoRoot);
+  } catch {
+    fail(`not a git repository: ${repoRoot}`);
+  }
+  for (const hook of HOOKS) {
+    const file = path.join(hooksDir, hook);
+    if (!fs.existsSync(file)) {
+      console.log(`${hook}: absent`);
+      continue;
+    }
+    const existing = fs.readFileSync(file, 'utf8');
+    console.log(`${hook}: ${isManagedHook(existing) ? 'managed by jhste-skills' : 'present but not managed'}`);
+  }
+}
+
+const [subcommand, ...rest] = process.argv.slice(2);
+if (!subcommand || subcommand === '--help' || subcommand === '-h') {
+  usage();
+  process.exit(0);
+}
+
+const args = parseArgs(rest);
+const repoRoot = findGitRoot(args.repo || process.cwd());
+if (subcommand === 'install') install(repoRoot, args);
+else if (subcommand === 'uninstall') uninstall(repoRoot, args);
+else if (subcommand === 'doctor') doctor(repoRoot);
+else fail(`unknown subcommand: ${subcommand}`);

package/cli/index.mjs

@@ -0,0 +1,35 @@
+#!/usr/bin/env node
+import { spawnSync } from 'node:child_process';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const cliDir = path.dirname(fileURLToPath(import.meta.url));
+const [command, ...rest] = process.argv.slice(2);
+const commands = new Set(['install', 'connect', 'sync', 'update', 'deep-scan', 'guard', 'hooks', 'tune', 'baseline', 'uninstall']);
+
+if (!command || command === '--help' || command === '-h') {
+  console.log(`jhste-skills
+
+Usage:
+  jhste-skills install [--mode minimal|normal|full|custom] [--yes] [--repo <path>]
+  jhste-skills connect [--mode normal|full|custom] [--repo <path>]
+  jhste-skills sync [--repo <path>] [--skills-dir <path>] [--yes]
+  jhste-skills update [--repo <path>] [--skills-dir <path>] [--yes]
+  jhste-skills deep-scan [--repo <path>]
+  jhste-skills guard [--repo <path>] [--scope changed|staged|all|files-from] [--format text|json]
+  jhste-skills hooks install|uninstall|doctor [--repo <path>]
+  jhste-skills tune [--repo <path>]
+  jhste-skills baseline [--repo <path>]
+  jhste-skills uninstall [--repo <path>] [--skills-dir <path>] [--yes]
+`);
+  process.exit(0);
+}
+
+if (!commands.has(command)) {
+  console.error(`Unknown command: ${command}`);
+  process.exit(1);
+}
+
+const script = path.join(cliDir, `${command}.mjs`);
+const result = spawnSync(process.execPath, [script, ...rest], { stdio: 'inherit' });
+process.exit(result.status ?? 1);

package/cli/install-actions/apply-plan.mjs

@@ -0,0 +1,39 @@
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { KIT_ROOT } from '../shared.mjs';
+import { installHookTarget } from '../hook-utils.mjs';
+import { bridgeTargetNames, writeManagedBridge } from './bridge-writer.mjs';
+import { writeProfile } from './profile-writer.mjs';
+import { installSkills } from './skills.mjs';
+
+const EXIT_CONFIG_FAILURE = 3;
+
+export function applyPlan(plan) {
+  const result = { skillResults: [], profileResult: null, bridgeResults: [], hookResults: [], deepScanResult: null, exitCode: 0 };
+
+  if (plan.installSkills || (plan.command === 'connect' && plan.installMissing && plan.preflight.skills.missing.length > 0)) {
+    result.skillResults = installSkills(plan.skillsDir, {
+      force: plan.forceSkills ?? plan.force,
+      allowUnmanagedOverwrite: plan.allowUnmanagedSkillOverwrite,
+      skillSet: plan.skillNames ?? plan.skillSet,
+    });
+    if (result.skillResults.some((item) => ['skipped-unmanaged-different', 'invalid-manifest'].includes(item.status))) {
+      result.exitCode = EXIT_CONFIG_FAILURE;
+      return result;
+    }
+  }
+
+  if (plan.writeProfile && plan.repoRoot) result.profileResult = writeProfile(plan.repoRoot, { force: plan.force, lineLimit: plan.lineLimit });
+  if (plan.writeBridge && plan.repoRoot) result.bridgeResults = bridgeTargetNames(plan).map((name) => writeManagedBridge(plan.repoRoot, name));
+  if (plan.hooks.length && plan.repoRoot) {
+    result.hookResults = plan.hooks.map((hook) => installHookTarget(plan.repoRoot, hook));
+    if (result.hookResults.some((hook) => hook.mode === 'blocking' && ['failed', 'skipped-non-managed'].includes(hook.status))) result.exitCode = EXIT_CONFIG_FAILURE;
+  }
+  if (plan.deepScan && plan.repoRoot) {
+    const scan = spawnSync(process.execPath, [path.join(KIT_ROOT, 'cli', 'deep-scan.mjs'), '--repo', plan.repoRoot], { stdio: 'inherit', timeout: 5 * 60 * 1000 });
+    if (scan.error) result.deepScanResult = { status: 'warning', reason: scan.error.message };
+    else if ((scan.status ?? 1) !== 0) result.deepScanResult = { status: 'warning', exitCode: scan.status ?? 1 };
+    else result.deepScanResult = { status: 'completed' };
+  }
+  return result;
+}

package/cli/install-actions/bridge-writer.mjs

@@ -0,0 +1,52 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { BRIDGE_BLOCK, BRIDGE_END, BRIDGE_START, MANAGED_BRIDGE_BLOCK, readIfExists } from '../shared.mjs';
+
+function escapeRegExp(value) {
+  return String(value).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+export function bridgeTargetNames(plan) {
+  if (!plan.writeBridge || !plan.repoRoot) return [];
+  const names = ['AGENTS.md', 'CLAUDE.md'];
+  const existing = names.filter((name) => fs.existsSync(path.join(plan.repoRoot, name)));
+  return existing.length ? existing : ['AGENTS.md'];
+}
+
+export function bridgeStatus(repoRoot, fileName) {
+  const target = path.join(repoRoot, fileName);
+  const existing = readIfExists(target);
+  if (existing === null) return { fileName, path: target, status: 'will-create' };
+  if (existing.includes(BRIDGE_START) && existing.includes(BRIDGE_END)) {
+    return existing.includes(MANAGED_BRIDGE_BLOCK)
+      ? { fileName, path: target, status: 'already-managed' }
+      : { fileName, path: target, status: 'will-update-managed' };
+  }
+  if (existing.includes(BRIDGE_BLOCK)) return { fileName, path: target, status: 'will-migrate-legacy' };
+  if (/^##\s+Agent skills\s*$/m.test(existing) || /jhste skills/i.test(existing)) return { fileName, path: target, status: 'manual-review' };
+  return { fileName, path: target, status: 'will-append-managed' };
+}
+
+export function writeManagedBridge(repoRoot, fileName) {
+  const target = path.join(repoRoot, fileName);
+  const existing = readIfExists(target);
+  if (existing === null) {
+    fs.writeFileSync(target, `${MANAGED_BRIDGE_BLOCK}\n`);
+    return { status: 'created', path: target };
+  }
+  if (existing.includes(BRIDGE_START) && existing.includes(BRIDGE_END)) {
+    const pattern = new RegExp(`${escapeRegExp(BRIDGE_START)}[\\s\\S]*?${escapeRegExp(BRIDGE_END)}`);
+    const updated = existing.replace(pattern, MANAGED_BRIDGE_BLOCK);
+    if (updated === existing) return { status: 'unchanged', path: target };
+    fs.writeFileSync(target, updated);
+    return { status: 'updated-managed', path: target };
+  }
+  if (existing.includes(BRIDGE_BLOCK)) {
+    fs.writeFileSync(target, existing.replace(BRIDGE_BLOCK, MANAGED_BRIDGE_BLOCK));
+    return { status: 'migrated-legacy', path: target };
+  }
+  if (/^##\s+Agent skills\s*$/m.test(existing) || /jhste skills/i.test(existing)) return { status: 'manual-review', path: target, snippet: MANAGED_BRIDGE_BLOCK };
+  const prefix = existing.endsWith('\n') ? existing : `${existing}\n`;
+  fs.writeFileSync(target, `${prefix}\n${MANAGED_BRIDGE_BLOCK}\n`);
+  return { status: 'appended-managed', path: target };
+}

package/cli/install-actions/output.mjs

@@ -0,0 +1,45 @@
+import path from 'node:path';
+import { relativeDisplay } from '../shared.mjs';
+
+function summarizeStatuses(results) {
+  return results.reduce((acc, item) => {
+    acc[item.status] = (acc[item.status] || 0) + 1;
+    return acc;
+  }, {});
+}
+
+export function printApplyResult(plan, result) {
+  const labels = { connect: 'Connection', install: 'Install', sync: 'Sync', update: 'Update' };
+  console.log(`\n${labels[plan.command] || 'Run'} completed.`);
+  if (result.skillResults.length) {
+    const summary = summarizeStatuses(result.skillResults);
+    console.log(`- Skills: ${Object.entries(summary).map(([k, v]) => `${k}=${v}`).join(', ') || 'none'}`);
+    for (const skill of result.skillResults.filter((item) => item.reason)) console.log(`  - ${skill.status}: ${skill.reason}`);
+  } else {
+    console.log('- Skills: no changes');
+  }
+  if (result.profileResult) console.log(`- Profile: ${result.profileResult.status} (${relativeDisplay(plan.repoRoot, result.profileResult.path)})`);
+  else console.log('- Profile: no changes');
+  for (const bridge of result.bridgeResults) {
+    console.log(`- Bridge: ${path.basename(bridge.path)} ${bridge.status}`);
+    if (bridge.status === 'manual-review') {
+      console.log('  Manual snippet:');
+      console.log(bridge.snippet.split('\n').map((line) => `  ${line}`).join('\n'));
+    }
+  }
+  for (const hook of result.hookResults) {
+    const reason = hook.reason ? ` - ${hook.reason}` : '';
+    const failOn = hook.failOn && hook.failOn !== 'none' ? `, fail-on=${hook.failOn}` : '';
+    console.log(`- Hook ${hook.target}: ${hook.status}${hook.mode ? ` (${hook.mode}${failOn})` : ''}${reason}`);
+  }
+  if (result.deepScanResult) {
+    if (result.deepScanResult.status === 'completed') console.log('- Deep scan: completed');
+    else console.log(`- Deep scan: warning${result.deepScanResult.reason ? ` (${result.deepScanResult.reason})` : result.deepScanResult.exitCode ? ` (exit ${result.deepScanResult.exitCode})` : ''}`);
+  }
+  console.log('- CI/package.json/lockfile/source code: unchanged by installer');
+  console.log('- Non-managed hooks: never overwritten');
+  if (!plan.deepScan) {
+    console.log('\nTo run deep scan later:');
+    console.log('  npx jhste-skills deep-scan');
+  }
+}

package/cli/install-actions/preflight.mjs

@@ -0,0 +1,58 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { preflightHookTarget } from '../hook-utils.mjs';
+import { bridgeStatus, bridgeTargetNames } from './bridge-writer.mjs';
+import { installedSkillStatus, selectedSkillNames } from './skills.mjs';
+
+function preflightSkills(plan) {
+  const status = installedSkillStatus(plan.skillsDir, selectedSkillNames(plan));
+  if (plan.installSkills) return { enabled: true, skillSet: plan.skillSet, expected: status.expected.length, missing: status.missing, action: 'install-or-refresh' };
+  if (plan.command === 'connect') {
+    return {
+      enabled: false,
+      skillSet: plan.skillSet,
+      expected: status.expected.length,
+      missing: status.missing,
+      action: status.missing.length ? (plan.installMissing ? 'install-missing' : 'require-existing') : 'reuse-existing',
+    };
+  }
+  return { enabled: false, skillSet: plan.skillSet, expected: status.expected.length, missing: status.missing, action: 'none' };
+}
+
+function preflightProfile(plan) {
+  if (!plan.writeProfile || !plan.repoRoot) return { enabled: false, status: 'skipped' };
+  const profilePath = path.join(plan.repoRoot, '.jhste', 'profile.yaml');
+  if (!fs.existsSync(profilePath)) return { enabled: true, status: 'will-create', path: profilePath };
+  return { enabled: true, status: plan.force ? 'will-overwrite-managed' : 'will-keep-existing', path: profilePath };
+}
+
+function preflightBridges(plan) {
+  if (!plan.writeBridge || !plan.repoRoot) return [];
+  return bridgeTargetNames(plan).map((name) => bridgeStatus(plan.repoRoot, name));
+}
+
+function preflightHooks(plan) {
+  if (!plan.connectRepo || !plan.repoRoot || plan.hooks.length === 0) return [];
+  return plan.hooks.map((hook) => ({ ...hook, ...preflightHookTarget(plan.repoRoot, hook.target) }));
+}
+
+function preflightDeepScan(plan) {
+  if (!plan.deepScan) return { enabled: false, status: 'skipped' };
+  if (!plan.repoRoot) return { enabled: false, status: 'skipped-no-repo' };
+  return {
+    enabled: true,
+    status: 'will-run',
+    report: path.join(plan.repoRoot, '.jhste', 'deep-scan-report.md'),
+    recommendedProfile: path.join(plan.repoRoot, '.jhste', 'profile.recommended.yaml'),
+  };
+}
+
+export function preflightPlan(plan) {
+  return {
+    skills: preflightSkills(plan),
+    profile: preflightProfile(plan),
+    bridges: preflightBridges(plan),
+    hooks: preflightHooks(plan),
+    deepScan: preflightDeepScan(plan),
+  };
+}

package/cli/install-actions/profile-writer.mjs

@@ -0,0 +1,21 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { DEFAULT_PROFILE, ensureDir, nowIso } from '../shared.mjs';
+
+function renderProfile(lineLimit) {
+  const base = DEFAULT_PROFILE.replace('<installed_at>', nowIso());
+  const limit = lineLimit || { enabled: true, maxLines: 300, enforcement: 'advisory' };
+  const fileSizeBlock = limit.enabled
+    ? `  file_size_advisory:\n    mode: advisory\n    source_file_warning_lines: ${limit.maxLines}\n    source_file_review_lines: ${limit.maxLines}`
+    : `  file_size_advisory:\n    mode: off`;
+  return base.replace(/  file_size_advisory:\n(?:    .+\n){2,3}/, `${fileSizeBlock}\n`);
+}
+
+export function writeProfile(repoRoot, { force = false, lineLimit = null } = {}) {
+  const profilePath = path.join(repoRoot, '.jhste', 'profile.yaml');
+  if (fs.existsSync(profilePath) && !force) return { status: 'skipped-existing', path: profilePath };
+  const existed = fs.existsSync(profilePath);
+  ensureDir(path.dirname(profilePath));
+  fs.writeFileSync(profilePath, renderProfile(lineLimit));
+  return { status: existed ? 'overwritten-managed' : 'created', path: profilePath };
+}