claude-git-hooks 2.66.1 → 2.68.0

package/lib/utils/skill-registry/index.js

@@ -0,0 +1,254 @@
+/**
+ * File: skill-registry/index.js
+ * Purpose: Public API (facade) for the mscope automation-skills integration.
+ *
+ * Integration entry points — consumers should only need these three:
+ *   - runSkillChecks(...)      — freshness + registry load + line-level checks
+ *                                + display + blockOn gating decision.
+ *   - getCatalogueSection(...) — rendered rule catalogue for the analysis
+ *                                prompt (memoized registry load).
+ *   - recordSkillGaps(...)     — append unclassified AI findings to the
+ *                                skill repo's skill-feedback.md.
+ *
+ * Lower-level building blocks remain exported for tests and advanced use:
+ *   - loadRegistry()        — parse the JBE/UIK rule catalogue.
+ *   - runRules(...)         — line-level pre-commit checks against staged files.
+ *   - displayFindings(...)  — formatted console output.
+ *   - checkFreshness()      — non-blocking call to `automation-skills check`.
+ *
+ * Designed so the pre-commit hook can do:
+ *
+ *     import * as skill from '../utils/skill-registry/index.js';
+ *     const check = skill.runSkillChecks(stagedAbsPaths, { repoRoot, config });
+ *     if (check.shouldBlock) process.exit(1);   // exit stays in the hook
+ *
+ * Failure mode is always "silent skip" — if the skill repo isn't found, or
+ * the registry is malformed, the hook continues without these checks. The
+ * mscope skill is a value-add, not a hard dependency of this repo.
+ *
+ * No function in this module calls process.exit() — utils return decisions,
+ * the CLI/hook layer acts on them (repo convention).
+ */
+
+export { resolveSkillRepoRoot, loadRegistry, SCOPE_BY_EXT } from './parser.js';
+export { runRules } from './runner.js';
+
+import { spawnSync } from 'child_process';
+import { loadRegistry } from './parser.js';
+import { runRules } from './runner.js';
+import { renderCatalogue } from './catalogue.js';
+import { writeSkillGapCandidates } from './feedback-writer.js';
+import logger from '../logger.js';
+
+/**
+ * Severity rank used by the blockOn gate. Lower = more severe.
+ * 'never' (or any unknown value) disables gating.
+ */
+const SEVERITY_RANK = { critical: 0, high: 1, medium: 2, low: 3 };
+
+/**
+ * Process-lifetime cache of registry loads, keyed by the workingRepoRoot
+ * used for resolution. Lets runSkillChecks and getCatalogueSection share
+ * a single filesystem pass per commit.
+ */
+const registryCache = new Map();
+
+function loadRegistryCached(workingRepoRoot) {
+    const key = workingRepoRoot || '';
+    if (!registryCache.has(key)) {
+        registryCache.set(key, loadRegistry(null, workingRepoRoot));
+    }
+    return registryCache.get(key);
+}
+
+/**
+ * Test hook — clears the memoized registry. Not for production use.
+ */
+export function _resetRegistryCache() {
+    registryCache.clear();
+}
+
+/**
+ * One-call integration point for the pre-commit hook: freshness warning,
+ * registry load (memoized), rule run, console display, and the blockOn
+ * gating decision.
+ *
+ * Never calls process.exit — returns `shouldBlock` and lets the hook decide.
+ * Throws only on unexpected internal errors (callers wrap in try/catch).
+ *
+ * @param {string[]} absPaths - Absolute paths of staged files to check.
+ * @param {object} options
+ * @param {string} options.repoRoot - Working repo root (for sibling resolution + relative display).
+ * @param {object} options.config - Merged config; reads config.skillRegistry.blockOn.
+ * @returns {{ skillRoot: string|null, rules: Array, findings: Array,
+ *             totalFindings: number, shouldBlock: boolean, triggeringCount: number }}
+ */
+export function runSkillChecks(absPaths, { repoRoot, config } = {}) {
+    const freshness = checkFreshness();
+    if (freshness.status === 'stale') {
+        logger.warning(`📚 mscope skill is behind: installed v${freshness.installed}, latest v${freshness.latest}. Run: automation-skills update`);
+    }
+
+    const { rules, skillRoot } = loadRegistryCached(repoRoot);
+    if (!skillRoot || rules.length === 0) {
+        if (!skillRoot) {
+            logger.debug('skill-registry - runSkillChecks', 'Skill registry not found — skipping skill-driven checks');
+        }
+        return { skillRoot, rules: rules || [], findings: [], totalFindings: 0, shouldBlock: false, triggeringCount: 0 };
+    }
+
+    const result = runRules(rules, absPaths, { repoRoot });
+    displayFindings(result);
+
+    // Optional gating: blockOn = 'critical' | 'high' | 'medium' | 'low' | 'never'
+    // (default: 'never' — warn-only for incremental adoption).
+    const blockOn = config?.skillRegistry?.blockOn || 'never';
+    const threshold = SEVERITY_RANK[blockOn] ?? -1;
+    const triggering = threshold >= 0
+        ? result.findings.filter((f) => (SEVERITY_RANK[f.severity] ?? 99) <= threshold)
+        : [];
+
+    return {
+        skillRoot,
+        rules,
+        findings: result.findings,
+        totalFindings: result.totalFindings,
+        shouldBlock: triggering.length > 0,
+        triggeringCount: triggering.length,
+    };
+}
+
+/**
+ * Rendered `=== PLATFORM ANTIPATTERN CATALOGUE ===` body for injection into
+ * the Claude analysis prompt. Uses the memoized registry load, so calling
+ * this after runSkillChecks costs nothing.
+ *
+ * Never throws — the catalogue is value-add; on any failure returns null.
+ *
+ * @param {object} options
+ * @param {string} options.repoRoot - Working repo root for sibling resolution.
+ * @returns {string|null} Markdown catalogue, or null if unavailable/empty.
+ */
+export function getCatalogueSection({ repoRoot } = {}) {
+    try {
+        const { rules, skillRoot } = loadRegistryCached(repoRoot);
+        if (!skillRoot || rules.length === 0) return null;
+        return renderCatalogue(rules) || null;
+    } catch (err) {
+        logger.debug('skill-registry - getCatalogueSection', 'Catalogue unavailable', { error: err?.message });
+        return null;
+    }
+}
+
+/**
+ * Append skill-gap candidates (AI findings with no catalogue rule ID) to the
+ * skill repo's skill-feedback.md. Thin wrapper over writeSkillGapCandidates;
+ * throws on write failure (caller decides how loud to be).
+ *
+ * @param {object} aiResult - Result from analysis-engine.runAnalysis.
+ * @param {object} context - { skillRoot, branch, repoName }
+ * @returns {{ written: number, skippedDuplicate: number, skippedClassified: number }}
+ */
+export function recordSkillGaps(aiResult, context) {
+    return writeSkillGapCandidates(aiResult, context);
+}
+
+/**
+ * Run `automation-skills check --json` to find out if the installed skill
+ * is behind the latest. Returns:
+ *   { status: 'fresh' | 'stale' | 'unknown', installed, latest }
+ *
+ * Never throws; never blocks the hook. If the CLI isn't installed or the
+ * check fails, returns { status: 'unknown' }.
+ */
+export function checkFreshness({ timeoutMs = 3000 } = {}) {
+    try {
+        const res = spawnSync('automation-skills', ['check', '--json'], {
+            timeout: timeoutMs,
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        if (res.error || (res.status !== 0 && res.status !== 1)) {
+            return { status: 'unknown' };
+        }
+        const line = (res.stdout || '').toString().trim();
+        if (!line) return { status: 'unknown' };
+        const parsed = JSON.parse(line);
+        return {
+            status: parsed.status === 'stale' ? 'stale'
+                : parsed.status === 'fresh' ? 'fresh'
+                    : parsed.status === 'ahead' ? 'ahead'
+                        : 'unknown',
+            installed: parsed.installed,
+            latest: parsed.latest,
+        };
+    } catch {
+        return { status: 'unknown' };
+    }
+}
+
+/**
+ * Print a formatted summary of pre-commit findings (from runRules) to
+ * stdout. Returns nothing.
+ *
+ * Format intentionally mirrors the existing hook's `displayResults` style
+ * so it slots in naturally.
+ *
+ *   📚 mscope skill registry — 2 findings (1 high, 1 medium)
+ *
+ *     [JBE-016] medium  Wildcard import (`import x.*;`)
+ *       file.java:12   import jakarta.persistence.*;
+ *       → see automation-standards-backend/docs/improvement-registry.md#jbe-016
+ */
+export function displayFindings({ totalFindings, findings, bySeverity }) {
+    if (totalFindings === 0) {
+        logger.info('📚 mscope skill registry — no rule violations in staged files.');
+        return;
+    }
+
+    const sev = bySeverity || {};
+    const sevParts = [];
+    if (sev.critical) sevParts.push(`${sev.critical} 🔴 critical`);
+    if (sev.high)     sevParts.push(`${sev.high} 🟠 high`);
+    if (sev.medium)   sevParts.push(`${sev.medium} 🟡 medium`);
+    if (sev.low)      sevParts.push(`${sev.low} 🟢 low`);
+
+    logger.info(`📚 mscope skill registry — ${totalFindings} finding${totalFindings === 1 ? '' : 's'}${ 
+        sevParts.length ? ` (${sevParts.join(', ')})` : ''}`);
+    logger.info('');
+
+    // Group findings by rule for compact output.
+    const byRule = {};
+    for (const f of findings) {
+        (byRule[f.ruleId] ||= { rule: f, occurrences: [] }).occurrences.push(f);
+    }
+    const rulesSorted = Object.keys(byRule).sort((a, b) => {
+        // High severity first, then by rule id.
+        const order = { critical: 0, high: 1, medium: 2, low: 3, unknown: 4 };
+        const sa = order[byRule[a].rule.severity] ?? 99;
+        const sb = order[byRule[b].rule.severity] ?? 99;
+        if (sa !== sb) return sa - sb;
+        return a.localeCompare(b);
+    });
+
+    for (const ruleId of rulesSorted) {
+        const { rule, occurrences } = byRule[ruleId];
+        const sevTag = sevTagFor(rule.severity);
+        logger.info(`  [${ruleId}] ${sevTag} ${rule.title}`);
+        for (const occ of occurrences.slice(0, 5)) {
+            logger.info(`    ${occ.file}:${occ.line}   ${occ.lineText.slice(0, 100)}`);
+        }
+        if (occurrences.length > 5) {
+            logger.info(`    … and ${occurrences.length - 5} more occurrence${occurrences.length - 5 === 1 ? '' : 's'}`);
+        }
+        logger.info(`    → see ${rule.scope}/improvement-registry.md → ${ruleId}`);
+        logger.info('');
+    }
+}
+
+function sevTagFor(sev) {
+    if (sev === 'critical') return '🔴 critical';
+    if (sev === 'high') return '🟠 high';
+    if (sev === 'medium') return '🟡 medium';
+    if (sev === 'low') return '🟢 low';
+    return `⚪ ${  sev}`;
+}

package/lib/utils/skill-registry/parser.js

@@ -0,0 +1,311 @@
+/**
+ * File: skill-registry/parser.js
+ * Purpose: Parse @mscope/automation-skills improvement-registry.md files into
+ *          a structured rule index that the pre-commit hook can run grep
+ *          patterns against.
+ *
+ * Why this exists: the mscope skill repo
+ * (https://github.com/mscope-S-L/automation-skills) maintains canonical
+ * antipattern catalogues (JBE-NNN for backend, UIK-NNN/STR-NNN/etc. for
+ * frontend). Each registry entry includes a `Verify:` grep command that
+ * detects the antipattern. We parse those entries here so the pre-commit
+ * hook can run them against staged files automatically — turning the
+ * skill from descriptive (lives in docs) into prescriptive (blocks bad
+ * commits with the documented rule ID + fix).
+ *
+ * Skill repo location resolution (in order):
+ *   1. CLAUDE_HOOKS_SKILL_REPO env var
+ *   2. AUTOMATION_SKILLS_REPO env var (matches the skill repo's own convention)
+ *   3. ~/.claude/skills/automation-standards/.installed-version → walks back
+ *      to find the source clone (when installed via `automation-skills install`)
+ *   4. Returns null — the caller decides whether to skip silently or warn
+ */
+
+import { readFileSync, existsSync } from 'fs';
+import { dirname, join } from 'path';
+
+const SKILL_PATHS = [
+    {
+        key: 'backend',
+        relPath: 'skills/backend/automation-standards-backend/docs/improvement-registry.md',
+    },
+    {
+        key: 'frontend',
+        relPath: 'skills/frontend/automation-standards/docs/improvement-registry.md',
+    },
+];
+
+/**
+ * Single source of truth for file-extension → skill-scope mapping.
+ * Adding a new extension here propagates to every consumer (runner,
+ * feedback-writer, future modules). Avoids the duplicate-map drift the
+ * reviewer flagged on the v1 PR.
+ */
+export const SCOPE_BY_EXT = Object.freeze({
+    // Backend (Java + SQL — both owned by the backend skill)
+    '.java': 'backend',
+    '.sql': 'backend',
+    // Frontend (React / styling)
+    '.jsx': 'frontend',
+    '.tsx': 'frontend',
+    '.js': 'frontend',
+    '.ts': 'frontend',
+    '.css': 'frontend',
+    '.scss': 'frontend',
+});
+
+/**
+ * Resolve the skill repo root.
+ *
+ * Resolution order:
+ *   1. `CLAUDE_HOOKS_SKILL_REPO` env var (most explicit per-machine override).
+ *   2. `AUTOMATION_SKILLS_REPO` env var (matches the skill repo's own
+ *      CLI convention; lets a teammate set one variable for both repos).
+ *   3. Sibling of the working repo: if the hook is running on a commit in
+ *      e.g. `<parent>/mscope-gateway/`, check `<parent>/automation-skills/`.
+ *      This is the mscope canonical layout (all repos as siblings under one
+ *      parent, folder name matching the GitHub repo name) and requires no
+ *      env-var setup for teammates following convention.
+ *   4. Return null — silent skip in the hook. The skill is value-add,
+ *      not a hard dep of claude-git-hooks.
+ *
+ * No hardcoded absolute paths and no homedir-relative guesses (those
+ * leaked personal layouts and never matched on the canonical mscope
+ * `<parent>/mscope-*` setup — see PR #180 review comment 4).
+ *
+ * @param {string} [workingRepoRoot] - Absolute path of the repo whose
+ *   commit triggered the hook (passed from pre-commit.js).
+ * @returns {string|null} Absolute path of the skill repo, or null.
+ */
+export function resolveSkillRepoRoot(workingRepoRoot = null) {
+    const candidates = [
+        process.env.CLAUDE_HOOKS_SKILL_REPO,
+        process.env.AUTOMATION_SKILLS_REPO,
+    ].filter(Boolean);
+
+    for (const c of candidates) {
+        if (isSkillRepoRoot(c)) return c;
+    }
+
+    if (workingRepoRoot) {
+        const parent = dirname(workingRepoRoot);
+        const guess = join(parent, 'automation-skills');
+        if (isSkillRepoRoot(guess)) return guess;
+    }
+
+    return null;
+}
+
+function isSkillRepoRoot(dir) {
+    if (!dir) return false;
+    try {
+        const pkgPath = join(dir, 'package.json');
+        if (!existsSync(pkgPath)) return false;
+        const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+        return pkg.name === '@mscope/automation-skills';
+    } catch {
+        return false;
+    }
+}
+
+/**
+ * Load all rule entries from both registries. Returns:
+ *   [
+ *     { id: 'JBE-001', severity: 'high', symptom: '…',
+ *       fix: '…', verify: 'grep -rn …', scope: 'backend', skillRel: '…' },
+ *     …
+ *   ]
+ * If the skill repo isn't found, returns []. Caller can decide how to surface.
+ */
+export function loadRegistry(skillRepoRoot = null, workingRepoRoot = null) {
+    const root = skillRepoRoot || resolveSkillRepoRoot(workingRepoRoot);
+    if (!root) return { rules: [], skillRoot: null };
+
+    const rules = [];
+    for (const { key, relPath } of SKILL_PATHS) {
+        const fullPath = join(root, relPath);
+        if (!existsSync(fullPath)) continue;
+        const content = readFileSync(fullPath, 'utf8');
+        const parsed = parseRegistryMarkdown(content, key, relPath);
+        rules.push(...parsed);
+    }
+    return { rules, skillRoot: root };
+}
+
+/**
+ * Parse a single registry markdown file. Returns an array of rule objects.
+ * Each registry entry follows the shape:
+ *
+ *   ### <RULE-ID> — <title>
+ *   **Severity:** <emoji + label>
+ *   **Symptom:** <description or fenced code>
+ *   **Fix:** <description or fenced code>
+ *   **Verify:** <inline command, or fenced code with `grep -rn …`>
+ *   **Seen in:** …
+ *   **Established in:** …
+ *
+ *   ---
+ *
+ * The parser is lenient — missing fields default to null. Entries without a
+ * usable Verify command are still indexed (so other features can reference
+ * them by ID) but won't fire pre-commit alarms.
+ */
+export function parseRegistryMarkdown(content, scope, sourceRel) {
+    const sections = content.split(/^### /m).slice(1);
+    const out = [];
+    for (const sec of sections) {
+        const newlineIdx = sec.indexOf('\n');
+        const header = newlineIdx === -1 ? sec : sec.slice(0, newlineIdx);
+        const body = newlineIdx === -1 ? '' : sec.slice(newlineIdx + 1);
+        // Header: "<RULE-ID> — <title>" or "<RULE-ID>: <title>" or "<RULE-ID> - <title>"
+        const idMatch = header.match(/^([A-Z][A-Z0-9]{1,7}-\d{3})\s*[—:–-]\s*(.+?)\s*$/);
+        if (!idMatch) continue;
+        const id = idMatch[1];
+        const title = idMatch[2];
+
+        const fields = extractFields(body);
+        if (!fields) continue;
+
+        const verifies = parseVerifyField(fields.verify);
+
+        out.push({
+            id,
+            title,
+            severity: classifySeverity(fields.severity),
+            severityRaw: fields.severity || '',
+            symptom: fields.symptom || null,
+            fix: fields.fix || null,
+            verifies,
+            seenIn: fields.seenIn || null,
+            establishedIn: fields.establishedIn || null,
+            knownEdgeCases: fields.knownEdgeCases || null,
+            scope,
+            source: sourceRel,
+        });
+    }
+    return out;
+}
+
+/**
+ * Extract the standard fields (Severity / Symptom / Fix / Verify / Seen in
+ * / Established in / Known edge cases) from a registry-entry body.
+ *
+ * Each field can be a single line OR span multiple lines including fenced
+ * code blocks. We slice on `**FieldName:**` boundaries.
+ */
+function extractFields(body) {
+    const FIELD_ORDER = [
+        ['severity', /\*\*Severity:\*\*/i],
+        ['symptom', /\*\*Symptom:\*\*/i],
+        ['fix', /\*\*Fix:\*\*/i],
+        ['verify', /\*\*Verify:\*\*/i],
+        ['seenIn', /\*\*Seen in:\*\*/i],
+        ['establishedIn', /\*\*Established in:\*\*/i],
+        ['knownEdgeCases', /\*\*Known edge cases:\*\*/i],
+    ];
+
+    // Find each field's start position; the field value runs to the next
+    // field start (or to a `---` divider / end of body).
+    const found = [];
+    for (const [name, re] of FIELD_ORDER) {
+        const m = body.match(re);
+        if (m) found.push({ name, start: m.index, headerEnd: m.index + m[0].length });
+    }
+    if (found.length === 0) return null;
+    found.sort((a, b) => a.start - b.start);
+
+    const dividerIdx = body.search(/^---\s*$/m);
+    const out = {};
+    for (let i = 0; i < found.length; i++) {
+        const cur = found[i];
+        const next = found[i + 1];
+        const stopAt = next
+            ? next.start
+            : dividerIdx >= 0 && dividerIdx > cur.start
+                ? dividerIdx
+                : body.length;
+        out[cur.name] = body.slice(cur.headerEnd, stopAt).trim();
+    }
+    return out;
+}
+
+/**
+ * Extract one-or-more runnable grep/find commands from a Verify field value.
+ *
+ * Verify field shapes seen in the registry:
+ *   - Inline: `**Verify:** grep -rn "printStackTrace()" src/main/java/`
+ *   - Fenced bash:
+ *       ```bash
+ *       grep -l "ALTER TABLE" BBDD/*.sql | xargs grep -L "IF NOT EXISTS"
+ *       ```
+ *   - Prose ("manual review") — returns []
+ *
+ * Returns an array of { command, kind } where kind ∈ { 'grep', 'find', 'other' }.
+ * Multi-command (piped) verifies are kept as a single entry — the runner shells out.
+ */
+function parseVerifyField(raw) {
+    if (!raw) return [];
+    const out = [];
+
+    // Fenced code blocks first.
+    const fenceRe = /```(?:[a-z]*)?\n([\s\S]*?)\n```/g;
+    let m;
+    while ((m = fenceRe.exec(raw)) !== null) {
+        const block = m[1];
+        for (const line of block.split('\n')) {
+            const cmd = line.trim();
+            if (isRunnableCommand(cmd)) out.push(toRule(cmd));
+        }
+    }
+
+    // Inline backtick command (single-line `cmd`).
+    const inlineRe = /`([^`\n]+)`/g;
+    while ((m = inlineRe.exec(raw)) !== null) {
+        const cmd = m[1].trim();
+        if (isRunnableCommand(cmd)) out.push(toRule(cmd));
+    }
+
+    // Plain (no backticks) — a single line beginning with grep/find/rg.
+    if (out.length === 0) {
+        for (const line of raw.split('\n')) {
+            const t = line.trim().replace(/^[-*]\s*/, '');
+            if (isRunnableCommand(t)) out.push(toRule(t));
+        }
+    }
+
+    return dedupe(out);
+}
+
+function isRunnableCommand(s) {
+    if (!s) return false;
+    if (s.length < 5 || s.length > 800) return false;
+    return /^(grep|rg|find|git\s+grep)\b/.test(s);
+}
+
+function toRule(command) {
+    let kind = 'other';
+    if (/^grep\b/.test(command)) kind = 'grep';
+    else if (/^rg\b/.test(command)) kind = 'grep';
+    else if (/^find\b/.test(command)) kind = 'find';
+    else if (/^git\s+grep\b/.test(command)) kind = 'grep';
+    return { command, kind };
+}
+
+function dedupe(arr) {
+    const seen = new Set();
+    return arr.filter((x) => {
+        if (seen.has(x.command)) return false;
+        seen.add(x.command);
+        return true;
+    });
+}
+
+function classifySeverity(raw) {
+    if (!raw) return 'unknown';
+    const lower = raw.toLowerCase();
+    if (lower.includes('critical') || lower.includes('🔴')) return 'critical';
+    if (lower.includes('high') || lower.includes('🟠')) return 'high';
+    if (lower.includes('medium') || lower.includes('🟡')) return 'medium';
+    if (lower.includes('low') || lower.includes('🟢')) return 'low';
+    return 'unknown';
+}

package/lib/utils/skill-registry/resume.js

@@ -0,0 +1,81 @@
+/**
+ * File: skill-registry/resume.js
+ * Purpose: Lessons-learned handover — invokes `automation-skills resume`
+ *          so the developer can record what they learned on the branch to
+ *          the mscope skill repo's implementation-history.md.
+ *
+ * Invoked from create-pr (knowledge-capture step, alongside gotcha
+ * solicitation) at the natural "branch done, about to publish" moment.
+ * The mscope `automation-skills resume` command analyses
+ * `git log <trunk>..HEAD`, prompts interactively for lessons, and appends
+ * them to the skill repo. We hand over stdio so the prompt works.
+ *
+ * Branch preconditions (feature branch, commits ahead of trunk) are
+ * guaranteed by the create-pr context, so no git validation happens here.
+ *
+ * Never throws and never blocks the caller's flow — the integration is
+ * value-add, not a hard dependency. The CLI not being installed is a
+ * silent skip (callers can check isResumeCliAvailable() first to decide
+ * whether to announce the handover).
+ */
+
+import { spawnSync } from 'child_process';
+import logger from '../logger.js';
+
+/** Process-lifetime cache of the CLI availability probe. */
+let _cliAvailable = null;
+
+/**
+ * Test hook — clears the memoized CLI availability. Not for production use.
+ */
+export function _resetCliAvailabilityCache() {
+    _cliAvailable = null;
+}
+
+/**
+ * Probe whether the `automation-skills` CLI is reachable on PATH (memoized
+ * for the process lifetime — one spawn per run). Lets callers announce the
+ * interactive handover only when it will actually happen.
+ *
+ * @returns {boolean}
+ */
+export function isResumeCliAvailable() {
+    if (_cliAvailable !== null) return _cliAvailable;
+    const res = spawnSync('automation-skills', ['--version'], {
+        stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    _cliAvailable = !res.error && res.status === 0;
+    return _cliAvailable;
+}
+
+/**
+ * Hand control to `automation-skills resume [skill] [--trunk <branch>]`
+ * with inherited stdio (interactive prompt).
+ *
+ * @param {object} options
+ * @param {string} options.repoRoot - Working repo root (cwd for the subcommand).
+ * @param {string|null} options.skill - Optional skill hint (frontend|backend|fe|be).
+ * @param {string|null} options.trunk - Optional trunk override passed through.
+ * @returns {{ ran: boolean, reason?: string, exitCode?: number }}
+ */
+export function runResumeFlow({ repoRoot, skill = null, trunk = null } = {}) {
+    if (!isResumeCliAvailable()) {
+        logger.debug('skill-registry - runResumeFlow', 'automation-skills CLI not on PATH — skipping lessons capture');
+        return { ran: false, reason: 'cli-missing' };
+    }
+
+    const resumeArgs = ['resume'];
+    if (skill) resumeArgs.push(skill);
+    if (trunk) resumeArgs.push('--trunk', trunk);
+
+    const proc = spawnSync('automation-skills', resumeArgs, {
+        stdio: 'inherit',
+        cwd: repoRoot,
+    });
+
+    if (proc.error) {
+        logger.debug('skill-registry - runResumeFlow', 'resume spawn failed', { error: proc.error.message });
+        return { ran: false, reason: 'spawn-error' };
+    }
+    return { ran: true, exitCode: proc.status ?? 0 };
+}