peaks-loop 4.0.0-beta.8 → 4.0.1

package/dist/services/audit/enforcers/lint-prd-source-snapshot.d.ts

@@ -0,0 +1,27 @@
+/**
+ * P2-b sweep — PRD source-snapshot placement enforcer.
+ *
+ * Targets the BLOCKING markers around the peaks-prd
+ * "Document snapshot placement" + "Prohibited paths" guidance
+ * (rl-discovered-skills-bee-peaks-prd-skill-md-292 + 301).
+ * The contract: PRD source snapshots from external documents
+ * (Feishu / Lark / wiki / web) MUST go to
+ * `.peaks/_runtime/<sessionId>/prd/source/`, never to the
+ * project root.
+ *
+ * The enforcer pattern-scans the peaks-prd SKILL.md for the
+ * required guidance phrasing. Two hits (placement heading +
+  * prohibited-paths line) are both required for a clean
+ * enforcer pass. A single missing item emits a synthetic hit
+ * pointing at the line the user is most likely to look at
+ * (the placement heading line, or line 1 if missing).
+ *
+ * This is the second prose-only enforcer in the sweep
+ * (after lint-skill-presence-mandatory.ts). It demonstrates
+ * the path for the remaining 65 discovered lines: each
+ * enforcer is small, single-purpose, and has its own catalog
+ * entry. The catalog governance ratio will tick down with
+ * every enforcer shipped.
+ */
+import type { LintHit, SkillFile } from './lint-style.js';
+export declare function lintPrdSourceSnapshot(skill: SkillFile): ReadonlyArray<LintHit>;

package/dist/services/audit/enforcers/lint-prd-source-snapshot.js

@@ -0,0 +1,47 @@
+const PLACEMENT_HEADING = /^##\s+.*Document snapshot placement/im;
+const PROHIBITED_PATHS = /Prohibited paths/im;
+const SOURCE_SUBDIR = /\.peaks\/_runtime\/<session-id>\/prd\/source\//;
+function findPrdSourceSnapshotGuidance(lines) {
+    let placementLine = null;
+    let hasProhibited = false;
+    let hasSubdir = false;
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i] ?? '';
+        if (PLACEMENT_HEADING.test(line)) {
+            placementLine = i + 1;
+            // Look ahead up to 30 lines for the prohibited-paths
+            // line + the source subdir reference.
+            for (let j = i; j < Math.min(i + 30, lines.length); j++) {
+                const next = lines[j] ?? '';
+                if (PROHIBITED_PATHS.test(next))
+                    hasProhibited = true;
+                if (SOURCE_SUBDIR.test(next))
+                    hasSubdir = true;
+            }
+            break;
+        }
+    }
+    return { placementLine, hasProhibited, hasSubdir };
+}
+export function lintPrdSourceSnapshot(skill) {
+    // Scope: peaks-prd only. Other bee skills do not have the
+    // source-snapshot contract.
+    if (skill.name !== 'peaks-prd')
+        return [];
+    const lines = skill.lines.length > 0
+        ? skill.lines
+        : skill.body.split(/\r?\n/);
+    const { placementLine, hasProhibited, hasSubdir } = findPrdSourceSnapshotGuidance(lines);
+    if (placementLine !== null && hasProhibited && hasSubdir)
+        return [];
+    const detail = placementLine === null
+        ? 'missing `## Document snapshot placement` heading'
+        : `placement heading at line ${placementLine} but guidance incomplete (prohibited=${hasProhibited}, subdir=${hasSubdir})`;
+    return [{
+            catalogId: 'rl-prd-source-snapshot-placement-001',
+            rule: 'PRD source-snapshot placement (BLOCKING): external-document snapshots must land in .peaks/_runtime/<sessionId>/prd/source/, never project root',
+            file: skill.path,
+            line: placementLine ?? 1,
+            matchedText: detail
+        }];
+}

package/dist/services/audit/enforcers/lint-qa-gateguard-and-runtime.d.ts

@@ -0,0 +1,19 @@
+/**
+ * P2-b sweep 006 — peaks-qa gateguard + runtime contract.
+ *
+ * Closes four peaks-qa discovered lines:
+ *  - md-26  : "Pre-flight: gateguard-fact-force conflict" (BLOCKING)
+ *  - md-113 : "Transition verification gates" (MANDATORY)
+ *  - md-165 : "if playwright mcp is unavailable, the llm checks" (BLOCKING)
+ *  - md-201 : "when the target repository has openspec/, qa must" (BLOCKING)
+ *
+ * Two enforcers:
+ *  - lintQaGateguardPreflight: peaks-qa only; checks the
+ *    gateguard-fact-force pre-flight heading.
+ *  - lintQaRuntimeContract: peaks-qa only; checks for
+ *    transition gates + playwright mcp handling + openspec
+ *    integration.
+ */
+import type { LintHit, SkillFile } from './lint-style.js';
+export declare function lintQaGateguardPreflight(skill: SkillFile): ReadonlyArray<LintHit>;
+export declare function lintQaRuntimeContract(skill: SkillFile): ReadonlyArray<LintHit>;

package/dist/services/audit/enforcers/lint-qa-gateguard-and-runtime.js

@@ -0,0 +1,47 @@
+const GATEGUARD_HEADING = /Pre-flight:\s*gateguard-fact-force conflict/im;
+const TRANSITION_GATES = /Transition verification gates/im;
+const PLAYWRIGHT_MCP = /if playwright mcp is unavailable/i;
+const OPENSPEC_INTEGRATION = /when the target repository has openspec\//i;
+export function lintQaGateguardPreflight(skill) {
+    if (skill.name !== 'peaks-qa')
+        return [];
+    const lines = skill.lines.length > 0
+        ? skill.lines
+        : skill.body.split(/\r?\n/);
+    const hasGateguard = lines.some((l) => GATEGUARD_HEADING.test(l));
+    if (hasGateguard)
+        return [];
+    return [{
+            catalogId: 'rl-qa-gateguard-preflight-001',
+            rule: 'peaks-qa SKILL.md must declare the `## Pre-flight: gateguard-fact-force conflict (BLOCKING)` section',
+            file: skill.path,
+            line: 1,
+            matchedText: 'missing gateguard pre-flight heading'
+        }];
+}
+export function lintQaRuntimeContract(skill) {
+    if (skill.name !== 'peaks-qa')
+        return [];
+    const lines = skill.lines.length > 0
+        ? skill.lines
+        : skill.body.split(/\r?\n/);
+    const hasTransition = lines.some((l) => TRANSITION_GATES.test(l));
+    const hasPlaywright = lines.some((l) => PLAYWRIGHT_MCP.test(l));
+    const hasOpenSpec = lines.some((l) => OPENSPEC_INTEGRATION.test(l));
+    if (hasTransition && hasPlaywright && hasOpenSpec)
+        return [];
+    const missing = [];
+    if (!hasTransition)
+        missing.push('Transition verification gates');
+    if (!hasPlaywright)
+        missing.push('Playwright MCP unavailability handling');
+    if (!hasOpenSpec)
+        missing.push('OpenSpec integration requirement');
+    return [{
+            catalogId: 'rl-qa-runtime-contract-001',
+            rule: 'peaks-qa SKILL.md must declare the runtime contract (transition gates + Playwright MCP + OpenSpec integration)',
+            file: skill.path,
+            line: 1,
+            matchedText: `missing markers: ${missing.join(', ')}`
+        }];
+}

package/dist/services/audit/enforcers/lint-rd-handoff-coverage.d.ts

@@ -0,0 +1,18 @@
+/**
+ * P2-b sweep 005 — peaks-rd handoff + coverage enforcers.
+ *
+ * Closes three peaks-rd discovered lines:
+ *  - md-121 : "do not hand off to QA without [tech-doc.md]" (BLOCKING)
+ *  - md-127 : "do not hand off to QA without a perf-baseline" (BLOCKING)
+ *  - md-162 : "100% coverage target on testable files is meaningful"
+ *
+ * Two enforcers (handoff + coverage). The handoff enforcer
+ * checks for both 'tech-doc' and 'perf-baseline' handoff
+ * markers; the coverage enforcer checks for the 100%-target
+ * phrasing + the no-coverage-padding rule.
+ *
+ * scope: peaks-rd only.
+ */
+import type { LintHit, SkillFile } from './lint-style.js';
+export declare function lintRdHandoffContract(skill: SkillFile): ReadonlyArray<LintHit>;
+export declare function lintRdCoverageDiscipline(skill: SkillFile): ReadonlyArray<LintHit>;

package/dist/services/audit/enforcers/lint-rd-handoff-coverage.js

@@ -0,0 +1,70 @@
+const TECH_DOC_HANDOFF = /do not hand off to qa without[^\n]*tech-doc/im;
+const PERF_BASELINE_HANDOFF = /do not hand off to qa without[^\n]*perf-baseline/im;
+const COVERAGE_TARGET = /100%\s*coverage target[^\n]*testable files/i;
+const NO_PADDING = /must not write coverage-padding tests/i;
+function findHandoffContract(lines) {
+    let techDoc = false;
+    let perfBaseline = false;
+    for (const line of lines) {
+        if (TECH_DOC_HANDOFF.test(line))
+            techDoc = true;
+        if (PERF_BASELINE_HANDOFF.test(line))
+            perfBaseline = true;
+    }
+    return { techDoc, perfBaseline };
+}
+function findCoverageContract(lines) {
+    let target = false;
+    let noPadding = false;
+    for (const line of lines) {
+        if (COVERAGE_TARGET.test(line))
+            target = true;
+        if (NO_PADDING.test(line))
+            noPadding = true;
+    }
+    return { target, noPadding };
+}
+export function lintRdHandoffContract(skill) {
+    if (skill.name !== 'peaks-rd')
+        return [];
+    const lines = skill.lines.length > 0
+        ? skill.lines
+        : skill.body.split(/\r?\n/);
+    const { techDoc, perfBaseline } = findHandoffContract(lines);
+    if (techDoc && perfBaseline)
+        return [];
+    const missing = [];
+    if (!techDoc)
+        missing.push('tech-doc handoff BLOCKING');
+    if (!perfBaseline)
+        missing.push('perf-baseline handoff BLOCKING');
+    return [{
+            catalogId: 'rl-rd-handoff-contract-001',
+            rule: 'peaks-rd SKILL.md must declare the QA-handoff BLOCKING contract (tech-doc + perf-baseline)',
+            file: skill.path,
+            line: 1,
+            matchedText: `missing markers: ${missing.join(', ')}`
+        }];
+}
+export function lintRdCoverageDiscipline(skill) {
+    if (skill.name !== 'peaks-rd')
+        return [];
+    const lines = skill.lines.length > 0
+        ? skill.lines
+        : skill.body.split(/\r?\n/);
+    const { target, noPadding } = findCoverageContract(lines);
+    if (target && noPadding)
+        return [];
+    const missing = [];
+    if (!target)
+        missing.push('100% coverage target (testable files) phrasing');
+    if (!noPadding)
+        missing.push('"must not write coverage-padding tests" rule');
+    return [{
+            catalogId: 'rl-rd-coverage-discipline-001',
+            rule: 'peaks-rd SKILL.md must declare the coverage discipline (100% target + no-padding rule)',
+            file: skill.path,
+            line: 1,
+            matchedText: `missing markers: ${missing.join(', ')}`
+        }];
+}

package/dist/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/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/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/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/services/audit/enforcers/lint-skill-presence-mandatory.d.ts

@@ -0,0 +1,25 @@
+/**
+ * P2-b (Slice #6+1) — Skill presence MANDATORY enforcer.
+ *
+ * Targets the `peaks-prd` / `peaks-rd` / `peaks-qa` SKILL.md
+ * "Skill presence (MANDATORY first action)" heading that the
+ * audit classified as `rl-discovered-skills-bee-peaks-prd-skill-md-56`
+ * (and the parallel peaks-rd / peaks-qa lines). The marker
+ * MANDATORY + the phrase "Skill presence" + "first action" are
+ * all required; if any of the three is missing on a `peaks-*`
+ * SKILL.md the enforcer emits a synthetic hit so the audit
+ * report can render the entry.
+ *
+ * This file is a single-purpose enforcer (one enforcerRef per
+ * catalog entry). It deliberately does NOT cover every
+ * discovered prose-only line — the next rid (catalog
+ * governance sweep) is the right place to add the rest. This
+ * commit's goal is to close the first one and prove the
+ * catalog-entry + enforcerRef + test path works end-to-end.
+ *
+ * No new deps. No shell-out. No FS writes. The enforcer
+ * function is sync + side-effect-free so the audit hot path
+ * stays fast.
+ */
+import type { LintHit, SkillFile } from './lint-style.js';
+export declare function lintSkillPresenceMandatory(skill: SkillFile): ReadonlyArray<LintHit>;