peaks-cli 1.4.2 → 2.0.0

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[];

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

@@ -0,0 +1,173 @@
+/**
+ * P2-a lint-style enforcers — Theme A (section structure) and
+ * Theme B (frontmatter shape).
+ *
+ * These enforcers do NOT block commands; they feed the
+ * `peaks audit red-lines --json` report. The backing-detector
+ * downgrades them to `cli-backed` when the catalog has an
+ * `enforcerRef` (i.e. this file) and the per-skill scan finds a
+ * match. The audit service counts hits + misses and reports the
+ * per-catalog-entry breakdown.
+ *
+ * Pattern-only (no shell-out, no FS writes, no env mutations) so
+ * the enforcer can run inside the `peaks audit red-lines` hot
+ * path without the 5s ECC-AgentShield subprocess budget.
+ */
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+const SECTION_HARD_CONTRACTS_HEADING = /^##\s+(Hard contracts|Hard contract)\b/im;
+const SECTION_MANDATORY_HEADING = /^##\s+Mandatory\b/im;
+const SECTION_DEFAULT_RUNBOOK_HEADING = /^##\s+(Default runbook|Default)\b/im;
+const SECTION_GATE_INDEX_HEADING = /^##\s+(RD gate index|QA gate index|Gate index|gate-index)\b/im;
+const SECTION_NAMING_AXIOM_HEADING = /(Two-axis naming convention|change-id.*session-id|두 가지 직교 축)/i;
+const FRONTMATTER_NAME_LINE = /^name:\s*peaks-/m;
+const FRONTMATTER_DESCRIPTION_LINE = /^description:\s*\S/m;
+const FRONTMATTER_LOAD_STRATEGY = /loadStrategy:\s*(always|on-demand)/i;
+const FRONTMATTER_APPLICABLE_TASK_LEVELS = /applicableTaskLevels/i;
+export function readSkillFiles(skillsRoot, names) {
+    const out = [];
+    for (const name of names) {
+        const path = join(skillsRoot, name, 'SKILL.md');
+        const body = readFileSync(path, 'utf8');
+        out.push({ name, path, body, lines: body.split(/\r?\n/) });
+    }
+    return out;
+}
+function findLine(lines, pattern) {
+    for (let i = 0; i < lines.length; i += 1) {
+        if (pattern.test(lines[i] ?? ''))
+            return i + 1;
+    }
+    return -1;
+}
+function matchedText(lines, line) {
+    if (line <= 0)
+        return '';
+    return (lines[line - 1] ?? '').trim();
+}
+/** 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 function lintSectionShape(skill) {
+    const hits = [];
+    const rules = [
+        { id: 'rl-section-hard-contracts-001', rule: 'Hard contracts for browser/IO surface', pattern: SECTION_HARD_CONTRACTS_HEADING },
+        { id: 'rl-section-mandatory-artifact-001', rule: 'Mandatory per-request artifact', pattern: SECTION_MANDATORY_HEADING },
+        { id: 'rl-section-default-runbook-001', rule: 'Default runbook pointer', pattern: SECTION_DEFAULT_RUNBOOK_HEADING },
+        { id: 'rl-section-gate-index-001', rule: 'Gate index', pattern: SECTION_GATE_INDEX_HEADING },
+        { id: 'rl-section-naming-axiom-001', rule: 'Two-axis naming axiom', pattern: SECTION_NAMING_AXIOM_HEADING }
+    ];
+    for (const r of rules) {
+        const line = findLine(skill.lines, r.pattern);
+        if (line === -1) {
+            hits.push({
+                catalogId: r.id,
+                rule: r.rule,
+                file: skill.path,
+                line: 1,
+                matchedText: '(missing section)'
+            });
+        }
+    }
+    return hits;
+}
+/**
+ * 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 function lintSectionOrder(skill) {
+    const hits = [];
+    const order = [
+        { id: 'rl-section-naming-axiom-001', rule: 'Two-axis naming axiom must precede Hard contracts', pattern: SECTION_NAMING_AXIOM_HEADING },
+        { id: 'rl-section-hard-contracts-001', rule: 'Hard contracts must precede Default runbook', pattern: SECTION_HARD_CONTRACTS_HEADING },
+        { id: 'rl-section-default-runbook-001', rule: 'Default runbook must precede Gate index', pattern: SECTION_DEFAULT_RUNBOOK_HEADING },
+    ];
+    let lastSeenLine = -1;
+    let lastSeenRule = '';
+    for (const r of order) {
+        const line = findLine(skill.lines, r.pattern);
+        if (line === -1)
+            continue; // missing-section is its own enforcer
+        if (line < lastSeenLine) {
+            hits.push({
+                catalogId: 'rl-section-order-wireframe-001',
+                rule: 'Section wireframe order: each section must appear in the canonical order',
+                file: skill.path,
+                line,
+                matchedText: `(section "${r.rule}" at line ${line} comes after "${lastSeenRule}" at line ${lastSeenLine})`,
+            });
+        }
+        lastSeenLine = line;
+        lastSeenRule = r.rule;
+    }
+    return hits;
+}
+/** Theme B — frontmatter shape. Same convention as Theme A. */
+export function lintFrontmatterShape(skill) {
+    const hits = [];
+    const hasName = FRONTMATTER_NAME_LINE.test(skill.body);
+    const hasDescription = FRONTMATTER_DESCRIPTION_LINE.test(skill.body);
+    if (!hasName || !hasDescription) {
+        hits.push({
+            catalogId: 'rl-frontmatter-skills-md-001',
+            rule: 'skills_md parseable frontmatter',
+            file: skill.path,
+            line: 1,
+            matchedText: '(missing name or description)'
+        });
+    }
+    // The `applicableTaskLevels` field is a body-level annotation, not
+    // strictly YAML frontmatter. We accept either a top-of-file
+    // frontmatter `applicableTaskLevels:` line or an in-body "applies
+    // to <levels>" sentence.
+    if (!FRONTMATTER_APPLICABLE_TASK_LEVELS.test(skill.body)) {
+        hits.push({
+            catalogId: 'rl-frontmatter-applicable-task-levels-001',
+            rule: 'skill applicable task levels',
+            file: skill.path,
+            line: 1,
+            matchedText: '(missing applicableTaskLevels)'
+        });
+    }
+    return hits;
+}
+/**
+ * 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 function lintReferenceLoadStrategy(referencesRoot, refs) {
+    const hits = [];
+    for (const ref of refs) {
+        const path = join(referencesRoot, ref);
+        const body = readFileSync(path, 'utf8');
+        if (!FRONTMATTER_LOAD_STRATEGY.test(body)) {
+            hits.push({
+                catalogId: 'rl-frontmatter-references-load-strategy-001',
+                rule: 'references loadStrategy declared',
+                file: path,
+                line: 1,
+                matchedText: '(missing loadStrategy)'
+            });
+        }
+    }
+    return hits;
+}

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

@@ -0,0 +1,5 @@
+import type { LintHit, SkillFile } from './lint-style.js';
+export declare function lintOpenSpecAcceptanceBullets(projectRoot: string): readonly LintHit[];
+export declare function lintOpenSpecSpecReference(projectRoot: string): readonly LintHit[];
+export declare function lintTechDocPresenceShape(projectRoot: string): readonly LintHit[];
+export declare function lintPeaksDoctorAcknowledged(skill: SkillFile): readonly LintHit[];