peaks-loop 3.0.0

package/dist/src/services/audit/enforcers/lint-output-style.js

@@ -0,0 +1,94 @@
+/**
+ * P2-a Theme C — output style enforcers.
+ *
+ * The peaks-cli dogfood rule: every skill response carries a status
+ * header (`Peaks-Cli Skill: <name> | Peaks-Cli Gate: <gate> | Next:
+ * <action>`), the SKILL.md body has no greeting/closing-prompt
+ * flattery, and the status header is detectable in the recent
+ * session transcript (test-only fixture).
+ *
+ * The status-header detection is a real check on the fixture's
+ * most-recent session file; the no-fluff and no-closing-prompt
+ * checks are static pattern scans of the skill's SKILL.md.
+ */
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+const FLUFF_GREETINGS = [
+    /\b你好[！!。，,.]?\s*$/m,
+    /^\s*你好[！!。，,.]?\s*$/m,
+    /\bHello[,，]?\s*I am\b/i,
+    /\bI am (an? )?(helpful )?assistant\b/i,
+    /\b作为一个 AI\b/,
+    /\b我是 (一个 )?AI\b/,
+    /\b作为一个\b/,
+    /\b我是(助手|模型|AI)/i
+];
+const CLOSING_PROMPTS = [
+    /\bLet me know if you need\b/i,
+    /\b如有(任何)?需要\b/,
+    /\b如有需要\b/,
+    /\bfeel free to ask\b/i,
+    /\bdo not hesitate to\b/i,
+    /\b随时(欢迎)?(联系|提问)/i,
+    /\b随时 (欢迎 )?(联系|提问)/i
+];
+const STATUS_HEADER_PATTERN = /Peaks-Cli Skill:\s*peaks-[a-z0-9-]+\s*\|\s*Peaks-Cli Gate:\s*[A-Za-z0-9_.-]+\s*\|\s*Next:\s*\S/;
+export function lintNoFluff(skill) {
+    const hits = [];
+    for (const pattern of FLUFF_GREETINGS) {
+        const lineIdx = skill.lines.findIndex((l) => pattern.test(l));
+        if (lineIdx !== -1) {
+            hits.push({
+                catalogId: 'rl-output-style-no-fluff-001',
+                rule: 'no greeting / persona fluff in SKILL.md',
+                file: skill.path,
+                line: lineIdx + 1,
+                matchedText: (skill.lines[lineIdx] ?? '').trim()
+            });
+        }
+    }
+    return hits;
+}
+export function lintNoClosingPrompt(skill) {
+    const hits = [];
+    for (const pattern of CLOSING_PROMPTS) {
+        const lineIdx = skill.lines.findIndex((l) => pattern.test(l));
+        if (lineIdx !== -1) {
+            hits.push({
+                catalogId: 'rl-output-style-no-closing-prompt-001',
+                rule: 'no closing-prompt flattery',
+                file: skill.path,
+                line: lineIdx + 1,
+                matchedText: (skill.lines[lineIdx] ?? '').trim()
+            });
+        }
+    }
+    return hits;
+}
+/**
+ * Status header detection: scan the most-recent session log for the
+ * canonical header line. The session log is read from the project's
+ * `.peaks/_runtime/<sid>/session.log` (or the audit's per-test
+ * fixture). For static analysis (no session), the lint returns an
+ * empty array (the runtime check is elsewhere).
+ */
+export function lintStatusHeader(projectRoot, sessionId) {
+    const logPath = join(projectRoot, '.peaks', '_runtime', sessionId, 'session.log');
+    let body;
+    try {
+        body = readFileSync(logPath, 'utf8');
+    }
+    catch {
+        return [];
+    }
+    if (!STATUS_HEADER_PATTERN.test(body)) {
+        return [{
+                catalogId: 'rl-output-style-status-header-001',
+                rule: 'Peaks-Cli status header on every response',
+                file: logPath,
+                line: 1,
+                matchedText: '(no Peaks-Cli Skill / Gate / Next header found in session.log)'
+            }];
+    }
+    return [];
+}

package/dist/src/services/audit/enforcers/lint-reference-integrity.d.ts

@@ -0,0 +1,6 @@
+import type { LintHit, SkillFile } from './lint-style.js';
+/** Theme E — reference integrity. */
+export declare function lintRefPathResolves(skillsRoot: string, name: string, refs: readonly string[]): readonly LintHit[];
+export declare function lintNoBrokenMkdir(skill: SkillFile): readonly LintHit[];
+export declare function lintNoPwdSymlinkJumps(skill: SkillFile): readonly LintHit[];
+export declare function lintNoRelativeArchivePaths(skill: SkillFile): readonly LintHit[];

package/dist/src/services/audit/enforcers/lint-reference-integrity.js

@@ -0,0 +1,83 @@
+/**
+ * P2-a Theme E — reference integrity enforcers.
+ *
+ * Static pattern scans of skill bodies + references/ for inline
+ * shell snippets that violate the project's "no
+ * mkdir-outside-project" / "no /tmp cp" / "no cd .." rules.
+ *
+ * These are pattern-based: the audit framework invokes the helper
+ * with a skill's body and the helper returns lint hits.
+ */
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+const MKDIR_PATTERN = /\bmkdir\s+(?:-p\s+)?(\/[^\s'`"]+|[A-Z]:[^\s'`"]+)/g;
+const CD_OUT_PATTERN = /\bcd\s+(\.\.[\\/]|[A-Z]:[\\/])/g;
+const CP_MV_LN_TMP_PATTERN = /\b(cp|mv|ln)\b[^\n]*\/tmp\b/g;
+/** Theme E — reference integrity. */
+export function lintRefPathResolves(skillsRoot, name, refs) {
+    const hits = [];
+    for (const ref of refs) {
+        const path = join(skillsRoot, name, 'references', ref);
+        if (!existsSync(path)) {
+            hits.push({
+                catalogId: 'rl-ref-path-resolves-001',
+                rule: 'every references/<file>.md link resolves',
+                file: join(skillsRoot, name, 'SKILL.md'),
+                line: 1,
+                matchedText: ref
+            });
+        }
+    }
+    return hits;
+}
+export function lintNoBrokenMkdir(skill) {
+    const hits = [];
+    for (let i = 0; i < skill.lines.length; i += 1) {
+        const line = skill.lines[i] ?? '';
+        if (MKDIR_PATTERN.test(line)) {
+            hits.push({
+                catalogId: 'rl-ref-no-broken-mkdir-001',
+                rule: 'no `mkdir -p` outside the project root',
+                file: skill.path,
+                line: i + 1,
+                matchedText: line.trim()
+            });
+        }
+        MKDIR_PATTERN.lastIndex = 0;
+    }
+    return hits;
+}
+export function lintNoPwdSymlinkJumps(skill) {
+    const hits = [];
+    for (let i = 0; i < skill.lines.length; i += 1) {
+        const line = skill.lines[i] ?? '';
+        if (CD_OUT_PATTERN.test(line)) {
+            hits.push({
+                catalogId: 'rl-ref-no-pwd-symlink-jumps-001',
+                rule: 'no `cd ..` chain jumping outside the project',
+                file: skill.path,
+                line: i + 1,
+                matchedText: line.trim()
+            });
+        }
+        CD_OUT_PATTERN.lastIndex = 0;
+    }
+    return hits;
+}
+export function lintNoRelativeArchivePaths(skill) {
+    const hits = [];
+    for (let i = 0; i < skill.lines.length; i += 1) {
+        const line = skill.lines[i] ?? '';
+        if (CP_MV_LN_TMP_PATTERN.test(line)) {
+            hits.push({
+                catalogId: 'rl-ref-no-relative-archive-paths-001',
+                rule: 'no `cp`/`mv`/`ln` to absolute /tmp paths',
+                file: skill.path,
+                line: i + 1,
+                matchedText: line.trim()
+            });
+        }
+        CP_MV_LN_TMP_PATTERN.lastIndex = 0;
+    }
+    return hits;
+}

package/dist/src/services/audit/enforcers/lint-reference-shape.d.ts

@@ -0,0 +1,30 @@
+import type { LintHit, SkillFile } from './lint-style.js';
+export interface ReferenceFile {
+    readonly skill: string;
+    readonly name: string;
+    readonly path: string;
+    readonly body: string;
+    readonly lines: readonly string[];
+}
+export declare function lintH1TitleRequired(ref: ReferenceFile): readonly LintHit[];
+export declare function lintApplicableTaskLevels(ref: ReferenceFile): readonly LintHit[];
+export declare function lintSeeAlsoSection(ref: ReferenceFile): readonly LintHit[];
+export declare function lintCrossRefResolves(ref: ReferenceFile, refsDir: string, siblings: readonly string[]): readonly LintHit[];
+export declare function lintNoSelfReference(ref: ReferenceFile): readonly LintHit[];
+export declare function lintNoOrphanLink(ref: ReferenceFile): readonly LintHit[];
+export declare function lintLineCountLe800(ref: ReferenceFile): readonly LintHit[];
+export declare function lintH2CountLe12(ref: ReferenceFile): readonly LintHit[];
+export declare function lintOverviewNearTop(ref: ReferenceFile): readonly LintHit[];
+export declare function lintLoadStrategyOnDemandFallback(ref: ReferenceFile): readonly LintHit[];
+export declare function lintLoadStrategyAlwaysCacheable(ref: ReferenceFile): readonly LintHit[];
+export declare function lintNoBashHeredoc(ref: ReferenceFile): readonly LintHit[];
+export declare function lintNoSudo(ref: ReferenceFile): readonly LintHit[];
+export declare function lintNoCurlPipeBash(ref: ReferenceFile): readonly LintHit[];
+export declare function lintCodeBlockLanguage(ref: ReferenceFile): readonly LintHit[];
+export declare function lintNoFakePrompt(ref: ReferenceFile): readonly LintHit[];
+export declare function lintNoAbsolutePaths(ref: ReferenceFile): readonly LintHit[];
+export declare function lintNoChmod777(ref: ReferenceFile): readonly LintHit[];
+export declare function lintNoMagicNumbers(ref: ReferenceFile): readonly LintHit[];
+export declare function lintSkillCitesEveryReference(ref: ReferenceFile, skill: SkillFile): readonly LintHit[];
+export declare function lintLoadStrategyMatchesSize(ref: ReferenceFile): readonly LintHit[];
+export declare function readReferenceFiles(skillsRoot: string, skillName: string, refNames: readonly string[]): readonly ReferenceFile[];

package/dist/src/services/audit/enforcers/lint-reference-shape.js

@@ -0,0 +1,272 @@
+/**
+ * P2-b Themes H-K + M-P — references/*.md shape enforcers.
+ *
+ * Slice #7 L2.4. Each enforcer is a pure function that walks
+ * `references/*.md` and returns `readonly LintHit[]`. The audit
+ * service (`red-lines-service.ts`) is responsible for the
+ * walk; this file is pattern-only.
+ *
+ * Themes covered here:
+ *   H — reference structural shape (3 enforcers)
+ *   I — reference cross-references (3 enforcers)
+ *   J — reference size + structure (3 enforcers)
+ *   K — loadStrategy behavior (2 enforcers)
+ *   M — inline shell patterns (3 enforcers)
+ *   N — code blocks (3 enforcers)
+ *   O — permissions + numbers (2 enforcers)
+ *   P — dogfooding (2 enforcers)
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+const H1_TITLE_PATTERN = /^#\s+\S/m;
+const TASK_LEVELS_PATTERN = /(applicableTaskLevels|task levels:|applies to (L1a|L1b|L2|L3|L4))/i;
+const SEE_ALSO_HEADING = /^##\s+(See also|Related|References)\b/im;
+const H2_HEADING = /^##\s+\S/gm;
+const OVERVIEW_HEADING = /^##\s+Overview\b/im;
+const FALLBACK_PATTERN = /(> Fallback:|^\*\*Fallback\*\*:)/m;
+const TOP_LEVEL_SUDO = /^\s*sudo\s+/m;
+const CURL_PIPE_BASH = /curl[^\n]*\|\s*bash/;
+const HEREDOC_PATTERN = /<<-?\s*\w+/;
+const CHMOD_777 = /chmod\s+777/;
+const FENCED_BLOCK = /```(\w*)\n([\s\S]*?)\n```/g;
+const FENCED_BLOCK_LANG_REQUIRED = /```\w+\n/;
+const FAKE_PROMPT = /^[\s]*(?:#|\$)\s*fake\b/im;
+const ABSOLUTE_PATH_WINDOWS = /[A-Z]:\\[\w\\]/;
+const ABSOLUTE_PATH_UNIX = /\/usr\/(?:local|bin|opt)\b/;
+const MAGIC_NUMBER = /\b(\d{3,})\b/;
+const LOAD_STRATEGY_PATTERN = /loadStrategy:\s*(always|on-demand)/i;
+function findLine(lines, pattern) {
+    for (let i = 0; i < lines.length; i += 1) {
+        if (pattern.test(lines[i] ?? ''))
+            return i + 1;
+    }
+    return -1;
+}
+function hit(catalogId, rule, file, line, matchedText) {
+    return { catalogId, rule, file, line, matchedText };
+}
+// ==================== Theme H — structural shape ====================
+export function lintH1TitleRequired(ref) {
+    if (H1_TITLE_PATTERN.test(ref.body))
+        return [];
+    return [hit('rl-ref-h1-title-required-001', 'every references/*.md starts with `# <title>`', ref.path, 1, '(missing `# <title>` first-line heading)')];
+}
+export function lintApplicableTaskLevels(ref) {
+    if (TASK_LEVELS_PATTERN.test(ref.body))
+        return [];
+    return [hit('rl-ref-applicable-task-levels-declared-001', 'every references/*.md declares applicableTaskLevels', ref.path, 1, '(missing applicableTaskLevels declaration)')];
+}
+export function lintSeeAlsoSection(ref) {
+    if (SEE_ALSO_HEADING.test(ref.body))
+        return [];
+    return [hit('rl-ref-see-also-section-001', 'every references/*.md has a `## See also` section', ref.path, 1, '(missing `## See also` (or `## Related` / `## References`) section)')];
+}
+// ==================== Theme I — cross-references ====================
+export function lintCrossRefResolves(ref, refsDir, siblings) {
+    const hits = [];
+    // Match `../<file>.md` or `references/<file>.md` or `<file>.md` style.
+    const linkPattern = /\[([^\]]+)\]\((?:\.\/|\.\.\/)?(?:references\/)?([\w./-]+\.md)(?:#[\w-]+)?\)/g;
+    let m;
+    while ((m = linkPattern.exec(ref.body)) !== null) {
+        const target = m[2] ?? '';
+        if (!target)
+            continue;
+        const candidates = [
+            join(refsDir, target),
+            join(refsDir, '..', target),
+            join(refsDir, '..', '..', target),
+        ];
+        const exists = candidates.some((c) => existsSync(c)) || siblings.includes(target);
+        if (!exists) {
+            const line = ref.body.slice(0, m.index ?? 0).split('\n').length;
+            hits.push(hit('rl-ref-cross-ref-resolves-001', 'every `../<file>.md` link from a reference resolves', ref.path, line, target));
+        }
+    }
+    return hits;
+}
+export function lintNoSelfReference(ref) {
+    const basename = ref.name;
+    // Match `[text](<basename>)` (exact or with section fragment).
+    const re = new RegExp(`\\]\\(${basename}(?:#[\\w-]+)?\\)`);
+    if (!re.test(ref.body))
+        return [];
+    const line = findLine(ref.lines, re);
+    return [hit('rl-ref-no-self-reference-001', 'no reference file links to itself', ref.path, line === -1 ? 1 : line, `(self-link to ${basename})`)];
+}
+export function lintNoOrphanLink(ref) {
+    // Heuristic: a markdown link to a non-.md URL with no protocol
+    // and no recognized image extension is an orphan. We do a soft
+    // pass here — the strict version is `lintCrossRefResolves`
+    // above; this one is a defensive backstop for paths the strict
+    // version doesn't catch.
+    const hits = [];
+    const linkPattern = /\[([^\]]+)\]\(([\w./-]+)\)/g;
+    let m;
+    while ((m = linkPattern.exec(ref.body)) !== null) {
+        const target = m[2] ?? '';
+        if (!target || target.startsWith('http') || target.startsWith('mailto:'))
+            continue;
+        if (target.endsWith('.md') || target.endsWith('.json') || target.endsWith('.ts'))
+            continue;
+        // Bare word: probably an anchor link; skip.
+        if (!target.includes('/') && !target.includes('.'))
+            continue;
+        const line = ref.body.slice(0, m.index ?? 0).split('\n').length;
+        hits.push(hit('rl-ref-no-orphan-link-001', 'no link to a non-existent file or section', ref.path, line, target));
+    }
+    return hits;
+}
+// ==================== Theme J — size + structure ====================
+export function lintLineCountLe800(ref) {
+    if (ref.lines.length <= 800)
+        return [];
+    return [hit('rl-ref-line-count-le-800-001', 'each reference ≤ 800 lines (Karpathy 4 原则 §2.3)', ref.path, 1, `(line count ${ref.lines.length} > 800)`)];
+}
+export function lintH2CountLe12(ref) {
+    const matches = ref.body.match(H2_HEADING) ?? [];
+    if (matches.length <= 12)
+        return [];
+    return [hit('rl-ref-h2-count-le-12-001', 'at most 12 `## <heading>` per reference', ref.path, 1, `(h2 count ${matches.length} > 12)`)];
+}
+export function lintOverviewNearTop(ref) {
+    if (ref.lines.length <= 200)
+        return [];
+    if (findLine(ref.lines.slice(0, 30), OVERVIEW_HEADING) !== -1)
+        return [];
+    return [hit('rl-ref-overview-section-near-top-001', 'long references (>200 lines) must have `## Overview` within the first 30 lines', ref.path, 1, '(missing `## Overview` near top of long reference)')];
+}
+// ==================== Theme K — loadStrategy behavior ====================
+export function lintLoadStrategyOnDemandFallback(ref) {
+    if (!/loadStrategy:\s*on-demand/i.test(ref.body))
+        return [];
+    if (FALLBACK_PATTERN.test(ref.body))
+        return [];
+    return [hit('rl-ref-loadstrategy-on-demand-fallback-001', 'loadStrategy: on-demand references must declare a fallback path', ref.path, 1, '(missing `> Fallback:` or `**Fallback**:` declaration)')];
+}
+export function lintLoadStrategyAlwaysCacheable(ref) {
+    if (!/loadStrategy:\s*always/i.test(ref.body))
+        return [];
+    // Heuristic: a loadStrategy: always reference must not have a
+    // top-level shell command. This is a soft check — we look at
+    // the first 10 non-frontmatter lines for I/O patterns.
+    const lines = ref.lines.slice(0, 20);
+    for (const line of lines) {
+        if (/^\s*(npm|pnpm|yarn|npx|git|curl|wget|docker)\s+/.test(line)) {
+            return [hit('rl-ref-loadstrategy-always-cacheable-001', 'loadStrategy: always references must not run I/O at top of file', ref.path, 1, `(I/O pattern at top of file: ${line.trim()})`)];
+        }
+    }
+    return [];
+}
+// ==================== Theme M — inline shell patterns ====================
+export function lintNoBashHeredoc(ref) {
+    if (!HEREDOC_PATTERN.test(ref.body))
+        return [];
+    const line = findLine(ref.lines, HEREDOC_PATTERN);
+    return [hit('rl-ref-no-bash-heredoc-001', 'no `cat <<EOF` in inline shell snippets', ref.path, line === -1 ? 1 : line, '(bash heredoc pattern found)')];
+}
+export function lintNoSudo(ref) {
+    if (!TOP_LEVEL_SUDO.test(ref.body))
+        return [];
+    const line = findLine(ref.lines, TOP_LEVEL_SUDO);
+    return [hit('rl-ref-no-sudo-001', 'no `sudo` in inline shell snippets', ref.path, line === -1 ? 1 : line, '(sudo command found)')];
+}
+export function lintNoCurlPipeBash(ref) {
+    if (!CURL_PIPE_BASH.test(ref.body))
+        return [];
+    const line = findLine(ref.lines, CURL_PIPE_BASH);
+    return [hit('rl-ref-no-curl-pipe-bash-001', 'no `curl ... | bash` in inline shell snippets', ref.path, line === -1 ? 1 : line, '(curl-pipe-bash pattern found)')];
+}
+// ==================== Theme N — code blocks ====================
+export function lintCodeBlockLanguage(ref) {
+    const hits = [];
+    // Reset regex state.
+    FENCED_BLOCK.lastIndex = 0;
+    let m;
+    while ((m = FENCED_BLOCK.exec(ref.body)) !== null) {
+        const lang = m[1] ?? '';
+        if (lang === '') {
+            const line = ref.body.slice(0, m.index ?? 0).split('\n').length;
+            hits.push(hit('rl-ref-code-block-language-declared-001', 'every fenced block has a language tag', ref.path, line, '(untyped fenced code block — ` ``` ` without language tag)'));
+        }
+    }
+    return hits;
+}
+export function lintNoFakePrompt(ref) {
+    if (!FAKE_PROMPT.test(ref.body))
+        return [];
+    const line = findLine(ref.lines, FAKE_PROMPT);
+    return [hit('rl-ref-no-fake-prompt-001', 'no `# fake prompt` / `$ fake` markers in code blocks', ref.path, line === -1 ? 1 : line, '(fake-prompt marker found)')];
+}
+export function lintNoAbsolutePaths(ref) {
+    const hits = [];
+    if (ABSOLUTE_PATH_WINDOWS.test(ref.body)) {
+        const line = findLine(ref.lines, ABSOLUTE_PATH_WINDOWS);
+        hits.push(hit('rl-ref-no-absolute-paths-001', 'no `C:\\` or `/usr/local` in code blocks', ref.path, line === -1 ? 1 : line, '(Windows absolute path found)'));
+    }
+    if (ABSOLUTE_PATH_UNIX.test(ref.body)) {
+        const line = findLine(ref.lines, ABSOLUTE_PATH_UNIX);
+        hits.push(hit('rl-ref-no-absolute-paths-001', 'no `C:\\` or `/usr/local` in code blocks', ref.path, line === -1 ? 1 : line, '(Unix absolute path found)'));
+    }
+    return hits;
+}
+// ==================== Theme O — permissions + numbers ====================
+export function lintNoChmod777(ref) {
+    if (!CHMOD_777.test(ref.body))
+        return [];
+    const line = findLine(ref.lines, CHMOD_777);
+    return [hit('rl-ref-no-chmod-777-001', 'no `chmod 777` in inline shell', ref.path, line === -1 ? 1 : line, '(chmod 777 found — security red flag)')];
+}
+export function lintNoMagicNumbers(ref) {
+    // Look at code blocks for unsigned integers ≥ 100. We don't
+    // try to be smart about hex / decimal distinction; the
+    // enforcer is pattern-only.
+    const hits = [];
+    FENCED_BLOCK.lastIndex = 0;
+    let m;
+    while ((m = FENCED_BLOCK.exec(ref.body)) !== null) {
+        const block = m[2] ?? '';
+        const numMatch = block.match(MAGIC_NUMBER);
+        if (!numMatch)
+            continue;
+        const offset = (m.index ?? 0) + (m[0].indexOf(numMatch[0] ?? ''));
+        const line = ref.body.slice(0, offset).split('\n').length;
+        hits.push(hit('rl-ref-no-magic-numbers-001', 'no unsigned integer ≥ 100 that is not a named constant', ref.path, line, `(magic number ${numMatch[0]} in code block)`));
+    }
+    return hits;
+}
+// ==================== Theme P — dogfooding ====================
+export function lintSkillCitesEveryReference(ref, skill) {
+    // A reference IS cited if its name appears anywhere in the
+    // parent SKILL.md body, OR if its content includes a forward
+    // link to the SKILL.md.
+    const refName = ref.name;
+    const skillName = skill.name;
+    const citedInSkill = skill.body.includes(refName) || skill.body.includes(`./references/${refName}`);
+    const citedInRef = ref.body.includes(`../SKILL.md`) || ref.body.includes(`SKILL.md#`);
+    if (citedInSkill || citedInRef)
+        return [];
+    return [hit('rl-ref-skill-cites-every-existing-reference-001', 'every reference IS cited in its parent SKILL.md (or links to it)', ref.path, 1, `(uncited reference ${refName} in skill ${skillName})`)];
+}
+export function lintLoadStrategyMatchesSize(ref) {
+    const sizeBytes = Buffer.byteLength(ref.body, 'utf8');
+    if (sizeBytes <= 5 * 1024)
+        return [];
+    // >5KB file should declare loadStrategy: on-demand (always
+    // is a context-budget bug).
+    const strategy = LOAD_STRATEGY_PATTERN.exec(ref.body);
+    if (strategy && strategy[1]?.toLowerCase() === 'on-demand')
+        return [];
+    return [hit('rl-ref-loadstrategy-matches-size-001', 'loadStrategy: on-demand is required for files > 5KB', ref.path, 1, `(size ${sizeBytes} bytes; loadStrategy must be \`on-demand\`)`)];
+}
+export function readReferenceFiles(skillsRoot, skillName, refNames) {
+    const refsDir = join(skillsRoot, skillName, 'references');
+    const out = [];
+    for (const name of refNames) {
+        const path = join(refsDir, name);
+        if (!existsSync(path))
+            continue;
+        const body = readFileSync(path, 'utf8');
+        out.push({ skill: skillName, name, path, body, lines: body.split(/\r?\n/) });
+    }
+    return out;
+}

package/dist/src/services/audit/enforcers/lint-style.d.ts

@@ -0,0 +1,49 @@
+export interface LintHit {
+    readonly catalogId: string;
+    readonly rule: string;
+    readonly file: string;
+    readonly line: number;
+    readonly matchedText: string;
+}
+export interface SkillFile {
+    readonly name: string;
+    readonly path: string;
+    readonly body: string;
+    readonly lines: readonly string[];
+}
+export declare function readSkillFiles(skillsRoot: string, names: readonly string[]): readonly SkillFile[];
+/** Theme A — section structure. Returns lint hits (positive = rule
+ *  satisfied, so a missing heading fires the lint hit; downstream
+ *  audit service decides whether to WARN or pass). */
+export declare function lintSectionShape(skill: SkillFile): readonly LintHit[];
+/**
+ * ASCII wireframe section-order check (spec §5.4 line 647).
+ *
+ * The "ASCII wireframe" lint hint in the spec means: SKILL.md
+ * follows a canonical section ordering. The first 5 sections
+ * must appear in this fixed order:
+ *
+ *   1. Two-axis naming axiom (top-of-file naming convention callout)
+ *   2. Hard contracts for browser/IO surface (when present)
+ *   3. Mandatory per-request artifact
+ *   4. Default runbook
+ *   5. RD / QA gate index
+ *
+ * If both sections exist but appear in the wrong order, the
+ * enforcer reports a wireframe-violation hit pointing at the
+ * section that came too early.
+ *
+ * If a section is missing, the per-section enforcer (above)
+ * already fires; this one only handles the **order** invariant
+ * (the wireframe shape).
+ */
+export declare function lintSectionOrder(skill: SkillFile): readonly LintHit[];
+/** Theme B — frontmatter shape. Same convention as Theme A. */
+export declare function lintFrontmatterShape(skill: SkillFile): readonly LintHit[];
+/**
+ * Reference loadStrategy: scan every `references/*.md` in the
+ * skill's references/ dir for a `loadStrategy: always | on-demand`
+ * line. The audit is invoked per-skill, so this helper takes a
+ * `referencesRoot` (the skill's `references/` dir).
+ */
+export declare function lintReferenceLoadStrategy(referencesRoot: string, refs: readonly string[]): readonly LintHit[];