peaks-loop 4.0.0-beta.8 → 4.0.0-beta.9

package/dist/services/skills/hooks-settings-service.js

@@ -0,0 +1,396 @@
+import { existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { resolve } from 'node:path';
+import { assertSafeSettingsFile } from '../ide/shared/safe-path.js';
+import { atomicWriteJson, readJsonObjectFile } from '../ide/shared/atomic-json.js';
+import { getAdapter } from '../ide/ide-registry.js';
+// --- Module-level defaults (claude-code) -----------------------------------
+// These exports remain for backward compat — tests and downstream callers
+// that only care about Claude Code can keep importing them. The per-IDE
+// values are computed lazily inside each public function call.
+/** Sentinel substring identifying a Claude-Code gate-enforce hook entry. */
+export const HOOK_ENFORCE_SENTINEL = 'peaks gate enforce';
+/** Default (claude-code) hook command — kept as a stable export for tests. */
+export const HOOK_ENFORCE_COMMAND = `peaks gate enforce --project "\${CLAUDE_PROJECT_DIR}"`;
+/**
+ * Per-IDE hook command + sentinel. The default (Claude Code) uses the
+ * legacy `peaks gate enforce` surface; Trae / Cursor / Codex (Cursor-style
+ * siblings with `before*` / `pre_*` hook events) use `peaks hook handle`,
+ * the new dispatcher. New adapters register by adding a single line here.
+ *
+ * Slice #12 + #13 (2.4.0) honor the framework's "fill the table" promise
+ * — adding a new IDE does NOT require editing this function's control
+ * flow, only adding a line to this table.
+ */
+const HOOK_COMMAND_BY_IDE = {
+    'claude-code': { command: 'peaks gate enforce', sentinel: 'peaks gate enforce' },
+    'trae': { command: 'peaks hook handle', sentinel: 'peaks hook handle' },
+    'cursor': { command: 'peaks hook handle', sentinel: 'peaks hook handle' },
+    'codex': { command: 'peaks hook handle', sentinel: 'peaks hook handle' },
+    'hermes': { command: 'peaks gate enforce', sentinel: 'peaks gate enforce' },
+    'openclaw': { command: 'peaks gate enforce', sentinel: 'peaks gate enforce' },
+    // qoder / tongyi-lingma are reserved IdeIds (slice #1) but not yet
+    // registered. When a slice adds them, add a HOOK_COMMAND_BY_IDE entry
+    // here — the function below fail-closes on missing entries.
+};
+function resolveHookSpec(ide) {
+    // getAdapter throws on unregistered IDEs — the registry is the source of truth.
+    const adapter = getAdapter(ide);
+    const spec = HOOK_COMMAND_BY_IDE[ide];
+    if (!spec) {
+        // Defensive fallback: if an adapter is added to the registry without a
+        // HOOK_COMMAND_BY_IDE entry, fail-closed with a clear error instead of
+        // silently writing a Claude-shaped entry to a non-Claude settings.json.
+        throw new Error(`peaks hooks install: unsupported IDE '${ide}' (no HOOK_COMMAND_BY_IDE entry; add one to hooks-settings-service.ts)`);
+    }
+    return {
+        hookEnforceCommand: `${spec.command} --project "\${${adapter.envVar}}"`,
+        hookEnforceSentinel: spec.sentinel,
+        hookEnforceMatcher: adapter.toolMatcher,
+        hookEnforceEvent: adapter.hookEvent
+    };
+}
+function resolveIde(options) {
+    return options?.ide ?? 'claude-code';
+}
+/** Slice #013: read the skipProgress opt-in flag. Slice #014: the underlying install no longer emits the progress-start entry, so the flag is effectively a no-op (kept for API stability). */
+function resolveSkipProgress(options) {
+    return options?.skipProgress === true;
+}
+/** Resolve settings root dir for a scope. */
+function resolveSettingsRoot(scope, projectRoot) {
+    if (scope === 'global')
+        return resolve(homedir());
+    if (!projectRoot) {
+        throw new Error('Project scope requires a project root');
+    }
+    return resolve(projectRoot);
+}
+function resolveSettingsPath(scope, ide, projectRoot) {
+    const root = resolveSettingsRoot(scope, projectRoot);
+    const adapter = getAdapter(ide);
+    return adapter.settings.resolveSettingsFile(scope, scope === 'global' ? homedir() : projectRoot);
+}
+function assertSafeSettingsPathCompat(scope, ide, root, settingsPath) {
+    const adapter = getAdapter(ide);
+    assertSafeSettingsFile(scope, root, adapter.settings.dirName, adapter.settings.settingsFileName);
+    // The compat path receives the already-computed settingsPath; double-check
+    // that the computed path matches what assertSafeSettingsFile would have
+    // produced. This guards against drift between the two resolvers.
+    const expected = adapter.settings.resolveSettingsFile(scope, scope === 'global' ? homedir() : root);
+    if (expected !== settingsPath) {
+        throw new Error(`settings path drift: ${expected} vs ${settingsPath}`);
+    }
+}
+/** Read the existing hook array entries for the adapter's hookEvent (tolerant of any prior shape). */
+function readHookEventEntries(settings, eventKey) {
+    const hooks = settings.hooks;
+    if (!hooks || typeof hooks !== 'object' || Array.isArray(hooks))
+        return [];
+    const arr = hooks[eventKey];
+    return Array.isArray(arr) ? arr : [];
+}
+/** Read the existing hook array entries from a `settings.hooks` object (already extracted). */
+function readHookEntriesFromHooks(hooks, eventKey) {
+    const arr = hooks[eventKey];
+    return Array.isArray(arr) ? arr : [];
+}
+/** True when every command handler in the entry matches a known peaks sentinel for the given IDE. */
+function entryIsPeaksManaged(entry, sentinels) {
+    const handlers = Array.isArray(entry?.hooks) ? entry.hooks : [];
+    if (handlers.length === 0)
+        return false;
+    return handlers.every((h) => {
+        if (typeof h?.command !== 'string')
+            return false;
+        const cmd = h.command;
+        return sentinels.some((sentinel) => cmd.includes(sentinel));
+    });
+}
+/**
+ * Slice #014: read the *actually-installed* peaks-managed hook entries
+ * from a settings object. Replaces the pre-#014 `listInstalledEntriesForIde`
+ * helper in `hooks-commands.ts`, which returned the IDE-EXPECTED list
+ * (a hardcoded 2-entry array per adapter) rather than what was on disk.
+ * That bug surfaced when slice #013's local cleanup installed
+ * `peaks hooks install --no-progress` (gate-enforce only), but the
+ * status command still reported `entries: [Bash, Task]` because the
+ * helper didn't read the file.
+ *
+ * The new helper:
+ *   1. reads each `hooks.<event>` array,
+ *   2. filters to entries that are peaks-managed for the given IDE
+ *      (matches the legacy sentinel set: gate-enforce + the no-longer-
+ *      installed progress-start),
+ *   3. returns one `{ matcher, sentinel }` row per entry, taking the
+ *      FIRST matching sentinel per entry (entries have a single command
+ *      handler in practice, but the loop tolerates multi-handler
+ *      entries by taking the first match).
+ *
+ * Pre-#014 settings.json files that have a stale progress-start entry
+ * will see it surface in the result. This is intentional: the status
+ * command is the user's tool for "what is on disk right now", and
+ * surfacing a stale entry is the only way the user can know to run
+ * `peaks hooks install` (which now strips it) or `peaks hooks
+ * uninstall` (which removes it).
+ */
+export function readInstalledEntriesFromSettings(settings, ide) {
+    const sentinels = resolveLegacySentinels(ide);
+    // Walk every event key the settings file has, not just the
+    // adapter-declared one. A pre-#014 install could have left a
+    // progress-start entry on a different event than the gate-enforce
+    // entry (Trae: both on beforeToolCall, but a stale install on a
+    // future IDE could split them).
+    const hooksRoot = settings.hooks;
+    if (!hooksRoot || typeof hooksRoot !== 'object' || Array.isArray(hooksRoot))
+        return [];
+    const result = [];
+    for (const eventKey of Object.keys(hooksRoot)) {
+        const entries = readHookEntriesFromHooks(hooksRoot, eventKey);
+        for (const entry of entries) {
+            if (!entryIsPeaksManaged(entry, sentinels))
+                continue;
+            const matcher = typeof entry.matcher === 'string' ? entry.matcher : '';
+            // Find the first matching sentinel inside the entry's command
+            // handlers. For each handler, find the first sentinel substring
+            // it contains. We pick the first handler's first matching
+            // sentinel (entries have a single command in practice).
+            const firstHandler = Array.isArray(entry.hooks) ? entry.hooks[0] : undefined;
+            const cmd = typeof firstHandler?.command === 'string' ? firstHandler.command : '';
+            const sentinel = sentinels.find((s) => cmd.includes(s));
+            if (matcher === '' || sentinel === undefined)
+                continue;
+            result.push({ matcher, sentinel });
+        }
+    }
+    return result;
+}
+/**
+ * Compute the per-IDE peaks hook entries to merge into the settings file.
+ * Replaces the slice #1 hardcoded `PEAKS_HOOK_ENTRIES` constant; the constant
+ * remains exported (computed for claude-code) for backward compat.
+ *
+ * Slice #013 (`--no-progress` flag): when `skipProgress` is true, the
+ * progress-start entry is omitted from the returned list. Install with this
+ * flag will (a) NOT emit the progress hook entry, and (b) will idempotently
+ * remove any previously-installed progress entry (sentinel-based merge).
+ *
+ * Slice #014 (refactor — full removal): only the gate-enforce entry is
+ * ever emitted. The `skipProgress` parameter is kept for API stability
+ * but is a no-op — the returned list is always single-entry. The progress
+ * entry's sentinel is included in the legacy sentinel set so uninstall
+ * can find + remove any stale progress-start entry that an older
+ * `peaks hooks install` may have written before this slice.
+ */
+function resolveHookEntries(ide, _skipProgress = false) {
+    const spec = resolveHookSpec(ide);
+    return [
+        { sentinel: spec.hookEnforceSentinel, matcher: spec.hookEnforceMatcher, command: spec.hookEnforceCommand, event: spec.hookEnforceEvent }
+    ];
+}
+/**
+ * Legacy sentinel set used by uninstall + status to find and remove stale
+ * progress-start entries written by pre-#014 installs. The progress-start
+ * sentinel is the literal substring that older installs emitted.
+ */
+const LEGACY_PROGRESS_START_SENTINEL = 'peaks progress start';
+function resolveLegacySentinels(ide) {
+    if (ide === 'trae') {
+        return ['peaks hook handle', LEGACY_PROGRESS_START_SENTINEL];
+    }
+    return [HOOK_ENFORCE_SENTINEL, LEGACY_PROGRESS_START_SENTINEL];
+}
+/** Default (claude-code) peaks-managed hook entries — kept as a stable export for tests. Slice #014: only the gate-enforce entry. */
+export const PEAKS_HOOK_ENTRIES = (() => {
+    const spec = resolveHookSpec('claude-code');
+    return [
+        { sentinel: spec.hookEnforceSentinel, matcher: spec.hookEnforceMatcher, command: spec.hookEnforceCommand, event: spec.hookEnforceEvent }
+    ];
+})();
+function isInstalledForIde(settings, ide) {
+    const entries = resolveHookEntries(ide);
+    const sentinels = entries.map((e) => e.sentinel);
+    // Check every distinct event key our entries could be on.
+    const eventKeys = new Set(entries.map((e) => e.event));
+    for (const eventKey of eventKeys) {
+        if (readHookEventEntries(settings, eventKey).some((e) => entryIsPeaksManaged(e, sentinels))) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Slice #014: detect the "stale progress entry after pre-#014 install"
+ * case. The desired shape is gate-enforce-only. If the file currently
+ * has a peaks-managed progress-start entry (left behind by a pre-#014
+ * install), the install is NOT a no-op — it must strip the stale
+ * entry. This helper returns true exactly when the desired shape is
+ * fully reflected on disk: gate-enforce present AND no legacy
+ * progress-start present.
+ */
+function shapeMatchesDesired(settings, ide) {
+    const desiredEntries = resolveHookEntries(ide);
+    const desiredSentinels = new Set(desiredEntries.map((e) => e.sentinel));
+    const allPeaksSentinels = resolveLegacySentinels(ide);
+    const eventKeys = new Set(resolveHookEntries(ide).map((e) => e.event));
+    for (const eventKey of eventKeys) {
+        const present = readHookEventEntries(settings, eventKey);
+        const peaksPresent = present.filter((e) => entryIsPeaksManaged(e, allPeaksSentinels));
+        // (a) every peaks-managed entry currently on disk must match the
+        //     desired sentinel set (no stale entries the caller wants removed).
+        for (const entry of peaksPresent) {
+            const entrySentinels = (entry.hooks ?? []).map((h) => allPeaksSentinels.find((s) => String(h.command ?? '').includes(s))).filter((s) => Boolean(s));
+            if (entrySentinels.some((s) => !desiredSentinels.has(s))) {
+                return false;
+            }
+        }
+        // (b) every desired entry must be on disk.
+        for (const sentinel of desiredSentinels) {
+            const has = peaksPresent.some((entry) => (entry.hooks ?? []).some((h) => String(h.command ?? '').includes(sentinel)));
+            if (!has)
+                return false;
+        }
+    }
+    return true;
+}
+export function planHookInstall(scope, projectRoot, options) {
+    const ide = resolveIde(options);
+    const _skipProgress = resolveSkipProgress(options);
+    const root = resolveSettingsRoot(scope, projectRoot);
+    const settingsPath = resolveSettingsPath(scope, ide, projectRoot);
+    assertSafeSettingsPathCompat(scope, ide, root, settingsPath);
+    const exists = existsSync(settingsPath);
+    const settings = exists ? readJsonObjectFile(settingsPath) : {};
+    const spec = resolveHookSpec(ide);
+    return {
+        scope,
+        settingsPath,
+        exists,
+        alreadyInstalled: isInstalledForIde(settings, ide),
+        desiredCommand: spec.hookEnforceCommand,
+        sentinel: spec.hookEnforceSentinel,
+        matcher: spec.hookEnforceMatcher
+    };
+}
+/** Merge all peaks-managed hook entries into settings, preserving all other keys and hooks. */
+function withHooksInstalledForIde(settings, ide, _skipProgress = false) {
+    const existingHooks = (settings.hooks && typeof settings.hooks === 'object' && !Array.isArray(settings.hooks))
+        ? settings.hooks
+        : {};
+    // Per-IDE entries may map to different events (Trae: gate-enforce on
+    // beforeToolCall; Claude: gate-enforce on PreToolUse). Group by event
+    // so each event array is independently merged.
+    const ourByEvent = new Map();
+    for (const spec of resolveHookEntries(ide)) {
+        const list = ourByEvent.get(spec.event) ?? [];
+        list.push(spec);
+        ourByEvent.set(spec.event, list);
+    }
+    // Slice #014: the legacy sentinel set includes the progress-start
+    // sentinel so a pre-#014 install's stale progress-start entry is
+    // stripped by the filter (the file converges on the new
+    // gate-enforce-only shape, idempotently). The desired set (passed
+    // in below) only contains the gate-enforce sentinel.
+    const allSentinels = resolveLegacySentinels(ide);
+    const nextHooks = { ...existingHooks };
+    for (const [eventKey, ourEntries] of ourByEvent) {
+        const existing = readHookEntriesFromHooks(nextHooks, eventKey);
+        const nonPeaks = existing.filter((entry) => !entryIsPeaksManaged(entry, allSentinels));
+        const ourFormatted = ourEntries.map((spec) => ({
+            matcher: spec.matcher,
+            hooks: [{ type: 'command', command: spec.command }]
+        }));
+        const merged = [...nonPeaks, ...ourFormatted];
+        if (merged.length > 0) {
+            nextHooks[eventKey] = merged;
+        }
+        else {
+            delete nextHooks[eventKey];
+        }
+    }
+    return {
+        ...settings,
+        hooks: nextHooks
+    };
+}
+export function applyHookInstall(scope, projectRoot, options) {
+    const ide = resolveIde(options);
+    const _skipProgress = resolveSkipProgress(options);
+    const root = resolveSettingsRoot(scope, projectRoot);
+    const settingsPath = resolveSettingsPath(scope, ide, projectRoot);
+    assertSafeSettingsPathCompat(scope, ide, root, settingsPath);
+    const exists = existsSync(settingsPath);
+    const settings = exists ? readJsonObjectFile(settingsPath) : {};
+    const spec = resolveHookSpec(ide);
+    // Slice #014: `alreadyInstalled` reflects the FULL desired shape
+    // (gate-enforce-only + no stale progress-start entry). Pre-#014
+    // installs that left a progress-start entry behind will be treated
+    // as not-yet-installed, so the merge strips the stale entry on the
+    // next install call. This is the only path that converges the file
+    // on the new shape; pure presence-checks are insufficient.
+    const alreadyInstalled = shapeMatchesDesired(settings, ide);
+    const baseResult = {
+        scope,
+        settingsPath,
+        exists,
+        alreadyInstalled,
+        desiredCommand: spec.hookEnforceCommand,
+        sentinel: spec.hookEnforceSentinel,
+        matcher: spec.hookEnforceMatcher
+    };
+    if (baseResult.alreadyInstalled) {
+        return { ...baseResult, applied: false };
+    }
+    atomicWriteJson(settingsPath, withHooksInstalledForIde(settings, ide));
+    return { ...baseResult, alreadyInstalled: false, applied: true };
+}
+export function removeHookInstall(scope, projectRoot, options) {
+    const ide = resolveIde(options);
+    const root = resolveSettingsRoot(scope, projectRoot);
+    const settingsPath = resolveSettingsPath(scope, ide, projectRoot);
+    assertSafeSettingsPathCompat(scope, ide, root, settingsPath);
+    if (!existsSync(settingsPath)) {
+        return { scope, settingsPath, removed: false };
+    }
+    const settings = readJsonObjectFile(settingsPath);
+    const existingHooks = settings.hooks ?? {};
+    // Slice #014: uninstall must remove the gate-enforce entry AND any
+    // legacy progress-start entry that a pre-#014 install left behind.
+    // The legacy sentinel set covers both shapes so the uninstall
+    // converges the file on "no peaks-managed entries", regardless of
+    // what shape the file was in when the user ran uninstall.
+    const sentinels = resolveLegacySentinels(ide);
+    const eventKeys = new Set(resolveHookEntries(ide).map((e) => e.event));
+    let removedAny = false;
+    const nextHooks = { ...existingHooks };
+    for (const eventKey of eventKeys) {
+        const entries = readHookEntriesFromHooks(nextHooks, eventKey);
+        const kept = entries.filter((entry) => !entryIsPeaksManaged(entry, sentinels));
+        if (kept.length !== entries.length)
+            removedAny = true;
+        if (kept.length > 0) {
+            nextHooks[eventKey] = kept;
+        }
+        else {
+            delete nextHooks[eventKey];
+        }
+    }
+    const nextSettings = { ...settings };
+    if (Object.keys(nextHooks).length > 0) {
+        nextSettings.hooks = nextHooks;
+    }
+    else {
+        delete nextSettings.hooks;
+    }
+    atomicWriteJson(settingsPath, nextSettings);
+    return { scope, settingsPath, removed: removedAny };
+}
+export function readHookStatus(scope, projectRoot, options) {
+    const ide = resolveIde(options);
+    const root = resolveSettingsRoot(scope, projectRoot);
+    const settingsPath = resolveSettingsPath(scope, ide, projectRoot);
+    assertSafeSettingsPathCompat(scope, ide, root, settingsPath);
+    const exists = existsSync(settingsPath);
+    const settings = exists ? readJsonObjectFile(settingsPath) : {};
+    return { scope, settingsPath, exists, installed: isInstalledForIde(settings, ide) };
+}

package/dist/services/skills/skill-conformance-service.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Skill-conformance audit (Slice #12) — checks every peaks-* SKILL.md
+ * against the 5 standards from the L1+L2+L3 redesign §5.4 Slice #12:
+ *
+ *   1. task-level frontmatter (all 12 skills must declare one)
+ *   2. CLI-back 注解 coverage (each skill body must document which
+ *      `peaks <cmd>` commands it composes; the absence is a SKILL.md
+ *      anti-pattern — it means the LLM has to discover the CLI
+ *      primitives by accident)
+ *   3. loadStrategy on-demand 标注 (skills should declare when they
+ *      load — `eager` for always-loaded, `on-demand` for invoked)
+ *   4. 800-line cap (Karpathy limit per spec §2.3)
+ *   5. outputStyle: peaks-concise-v1 frontmatter (peak-cli display
+ *      style for the skill's user-visible output)
+ *
+ * Plus 1 derived check:
+ *   6. CLI primitives declared in references/audit/ (Skill must
+ *      surface every peaks <cmd> it composes in the references/ subdir;
+ *      this is the "CLI-back 注解 100% 覆盖" check)
+ */
+export type LoadStrategy = 'eager' | 'on-demand';
+export type ConformanceLevel = 'pass' | 'warn' | 'fail';
+export interface ConformanceCheck {
+    readonly id: string;
+    readonly skill: string;
+    readonly level: ConformanceLevel;
+    readonly message: string;
+}
+export interface ConformanceReport {
+    readonly checked: number;
+    readonly passed: number;
+    readonly warned: number;
+    readonly failed: number;
+    readonly checks: readonly ConformanceCheck[];
+    readonly summary: string;
+}
+export interface SkillConformanceInput {
+    readonly projectRoot: string;
+}
+export declare function auditSkillConformance(input: SkillConformanceInput): ConformanceReport;

package/dist/services/skills/skill-conformance-service.js

@@ -0,0 +1,139 @@
+/**
+ * Skill-conformance audit (Slice #12) — checks every peaks-* SKILL.md
+ * against the 5 standards from the L1+L2+L3 redesign §5.4 Slice #12:
+ *
+ *   1. task-level frontmatter (all 12 skills must declare one)
+ *   2. CLI-back 注解 coverage (each skill body must document which
+ *      `peaks <cmd>` commands it composes; the absence is a SKILL.md
+ *      anti-pattern — it means the LLM has to discover the CLI
+ *      primitives by accident)
+ *   3. loadStrategy on-demand 标注 (skills should declare when they
+ *      load — `eager` for always-loaded, `on-demand` for invoked)
+ *   4. 800-line cap (Karpathy limit per spec §2.3)
+ *   5. outputStyle: peaks-concise-v1 frontmatter (peak-cli display
+ *      style for the skill's user-visible output)
+ *
+ * Plus 1 derived check:
+ *   6. CLI primitives declared in references/audit/ (Skill must
+ *      surface every peaks <cmd> it composes in the references/ subdir;
+ *      this is the "CLI-back 注解 100% 覆盖" check)
+ */
+import { readFileSync, statSync } from 'node:fs';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+const SKILL_NAMES = [
+    'peaks-ide',
+    'peaks-prd',
+    'peaks-ui',
+    'peaks-rd',
+    'peaks-qa',
+    'peaks-sc',
+    'peaks-code',
+    'peaks-resume',
+    'peaks-status',
+    'peaks-test',
+    'peaks-sop',
+    'peaks-txt',
+    'peaks-doctor'
+];
+const REQUIRED_FRONTMATTER_FIELDS = ['name', 'description'];
+const OPTIONAL_FRONTMATTER_FIELDS = ['task-level', 'loadStrategy', 'outputStyle'];
+const MAX_LINE_COUNT = 800;
+const CLI_BACK_PATTERNS = [
+    /`peaks\s+[a-z][a-z0-9-]+(?:\s+[a-z][a-z0-9-]+)*`/g,
+    /`peaks\s+[a-z][a-z0-9-]+/g,
+];
+function readSkillFrontmatter(skillPath) {
+    if (!existsSync(skillPath))
+        return null;
+    const content = readFileSync(skillPath, 'utf-8');
+    const match = /^---\n([\s\S]*?)\n---\n/.exec(content);
+    if (match === null)
+        return { raw: content, fields: {} };
+    const raw = match[1] ?? '';
+    const fields = {};
+    for (const line of raw.split('\n')) {
+        const colonIdx = line.indexOf(':');
+        if (colonIdx === -1)
+            continue;
+        const key = line.slice(0, colonIdx).trim();
+        const value = line.slice(colonIdx + 1).trim();
+        if (key.length > 0)
+            fields[key] = value;
+    }
+    return { raw, fields };
+}
+function lineCount(filePath) {
+    try {
+        return statSync(filePath).size > 0 ? readFileSync(filePath, 'utf-8').split(/\r?\n/).length : 0;
+    }
+    catch {
+        return 0;
+    }
+}
+function countCliBackReferences(content) {
+    let count = 0;
+    for (const pattern of CLI_BACK_PATTERNS) {
+        pattern.lastIndex = 0;
+        const matches = content.match(pattern);
+        if (matches)
+            count += matches.length;
+    }
+    return count;
+}
+export function auditSkillConformance(input) {
+    const skillsDir = join(input.projectRoot, 'skills');
+    const checks = [];
+    for (const skillName of SKILL_NAMES) {
+        // LLM-internal skills live under `skills/bee/<name>/` per spec 2026-07-05.
+        const topPath = join(skillsDir, skillName, 'SKILL.md');
+        const beePath = join(skillsDir, 'bee', skillName, 'SKILL.md');
+        const skillPath = existsSync(topPath) ? topPath : beePath;
+        const fm = readSkillFrontmatter(skillPath);
+        // 1. task-level frontmatter
+        if (fm === null) {
+            checks.push({ id: 'frontmatter:present', skill: skillName, level: 'fail', message: 'SKILL.md missing' });
+        }
+        else {
+            for (const required of REQUIRED_FRONTMATTER_FIELDS) {
+                if (fm.fields[required] === undefined) {
+                    checks.push({ id: `frontmatter:${required}`, skill: skillName, level: 'fail', message: `frontmatter missing required field "${required}"` });
+                }
+            }
+        }
+        // 2. CLI-back annotation
+        if (fm !== null) {
+            const content = readFileSync(skillPath, 'utf-8');
+            const cliCount = countCliBackReferences(content);
+            if (cliCount === 0) {
+                checks.push({ id: 'cli-back:present', skill: skillName, level: 'warn', message: 'no `peaks <cmd>` references in SKILL.md body; consider documenting which CLI primitives the skill composes' });
+            }
+        }
+        // 3. loadStrategy on-demand 标注
+        if (fm !== null && fm.fields['loadStrategy'] === undefined) {
+            checks.push({ id: 'loadStrategy:declared', skill: skillName, level: 'warn', message: 'loadStrategy not declared in frontmatter (eager | on-demand)' });
+        }
+        // 4. 800-line cap
+        if (fm !== null) {
+            const lines = lineCount(skillPath);
+            if (lines > MAX_LINE_COUNT) {
+                checks.push({ id: 'line-count:cap', skill: skillName, level: 'fail', message: `${lines} lines > ${MAX_LINE_COUNT} cap (Karpathy)` });
+            }
+        }
+        // 5. outputStyle: peaks-concise-v1
+        if (fm !== null && fm.fields['outputStyle'] === undefined) {
+            checks.push({ id: 'outputStyle:declared', skill: skillName, level: 'warn', message: 'outputStyle not declared in frontmatter' });
+        }
+    }
+    const failed = checks.filter((c) => c.level === 'fail').length;
+    const warned = checks.filter((c) => c.level === 'warn').length;
+    const passed = checks.filter((c) => c.level === 'pass').length;
+    return {
+        checked: checks.length,
+        passed,
+        warned,
+        failed,
+        checks,
+        summary: failed === 0 ? 'all hard checks pass; warnings are advisory' : `${failed} hard failure(s); fix before shipping`,
+    };
+}