@event4u/agent-config 16.4.0 → 17.0.0

package/src/scripts/lint_skill_link_reach.ts

@@ -24,6 +24,20 @@
  * not close the pattern: a two-link blind spot in a link checker is a link
  * checker that reports clean while missing exactly the shape most likely to rot.
  *
+ * Relative links resolve against their own file. A link inside `references/*.md`
+ * (recursively) is resolved against that file's directory, and a `SKILL.md`
+ * link into the skill's own `references/`, `scripts/`, `assets/` or `examples/`
+ * is resolved against the skill directory. A link that climbs out to `docs/` is
+ * its own reported class — `docs/` is not delivered, and
+ * `measure_docs_dead_links` owns that question. A link inside a fenced block or
+ * an inline code span, or one carrying an angle-bracket placeholder, is not a
+ * link. Any other `SKILL.md` link that leaves the skill directory and resolves
+ * to nothing in the delivered tree is checked against the skill's SOURCE
+ * directory (`src/skills/<slug>/`): a target that exists there is the named
+ * repo-only class — real, but not delivered — and is reported; a target that
+ * exists in neither tree is broken and fails (road-to-steps-the-skill-cannot-skip
+ * AC-1).
+ *
  * Exit codes: 0 clean · 1 unresolved link(s) · 2 usage / dead corpus.
  */
 import * as fs from 'node:fs';
@@ -49,6 +63,107 @@ export const DELIVERED_SKILLS_ROOT = 'dist/agent-src/skills';
  */
 const CROSS_SKILL_LINK = /\]\(\.\.\/([a-z0-9-]+)\/SKILL\.md/g;
 
+/** The same shape as a bare target — already checked against the delivered set. */
+const CROSS_SKILL_TARGET = /^\.\.\/[a-z0-9-]+\/SKILL\.md(?:#.*)?$/;
+
+/**
+ * Links from one reference file to a sibling reference of the same skill.
+ *
+ * A reference stays one level deep, so every reference is reached from the
+ * head. The ceiling is the count on 2026-10-16 and only moves down: above it
+ * fails, below it prints the lower figure to record.
+ */
+export const SIBLING_LINK_CEILING = 7;
+
+/**
+ * A procedure's step files (road-to-steps-the-skill-cannot-skip Phase 4) are the
+ * body split in order, not reference material, so the links they carry are the
+ * head's links and none of them counts as a sibling link.
+ */
+const STEPS_DIR = path.join('references', 'steps');
+
+/** The skill subdirectories a `SKILL.md` link may point into. */
+const OWN_SKILL_DIRS = /^(?:\.\/)?(?:references|scripts|assets|examples)\//;
+
+/** Where a delivered skill's source lives, relative to the repo root. */
+const SOURCE_SKILLS_ROOT = 'src/skills';
+
+/** A link that climbs out to `docs/`, which the installer does not deliver. */
+const DOCS_TARGET = /^(?:\.\.\/)+docs\//;
+
+/** Every inline markdown link target; a quoted title after it is tolerated. */
+const MARKDOWN_LINK = /\]\(([^)\s]+)(?:\s+"[^"]*")?\)/g;
+
+/** Body text with fenced blocks and inline code spans removed. */
+export function linkableText(source: string): string {
+    const out: string[] = [];
+    let fence: string | null = null;
+    for (const line of source.split('\n')) {
+        const m = /^\s*(`{3,}|~{3,})/.exec(line);
+        const marker = m?.[1];
+        if (fence !== null) {
+            if (marker !== undefined && marker[0] === fence[0] && marker.length >= fence.length) fence = null;
+            continue;
+        }
+        if (marker !== undefined) {
+            fence = marker;
+            continue;
+        }
+        out.push(line.replace(/`[^`]*`/g, ''));
+    }
+    return out.join('\n');
+}
+
+/** Relative link targets worth resolving: no scheme, no bare anchor, no placeholder. */
+export function relativeTargets(source: string): string[] {
+    const targets: string[] = [];
+    for (const m of linkableText(source).matchAll(MARKDOWN_LINK)) {
+        const target = m[1] as string;
+        if (/^[a-z][a-z0-9+.-]*:/i.test(target) || target.startsWith('#') || target.startsWith('/')) continue;
+        if (/[<>]/.test(target)) continue;
+        targets.push(target);
+    }
+    return targets;
+}
+
+/** The absolute path a relative target names, or null for a bare anchor. */
+function resolveTarget(fromDir: string, target: string): string | null {
+    const bare = target.split('#')[0]?.split('?')[0] ?? '';
+    if (bare === '') return null;
+    let decoded = bare;
+    try {
+        decoded = decodeURIComponent(bare);
+    } catch {
+        // A malformed escape is checked under its raw spelling.
+    }
+    return path.resolve(fromDir, decoded);
+}
+
+function targetExists(fromDir: string, target: string): boolean {
+    const resolved = resolveTarget(fromDir, target);
+    return resolved === null || fs.existsSync(resolved);
+}
+
+/** Every markdown file under a skill's `references/`, recursively, sorted. */
+function referenceFiles(skillDir: string): string[] {
+    const out: string[] = [];
+    const walk = (dir: string): void => {
+        let entries: fs.Dirent[];
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        } catch {
+            return;
+        }
+        for (const e of entries.sort((x, y) => x.name.localeCompare(y.name))) {
+            const full = path.join(dir, e.name);
+            if (e.isDirectory()) walk(full);
+            else if (e.name.endsWith('.md')) out.push(full);
+        }
+    };
+    walk(path.join(skillDir, 'references'));
+    return out;
+}
+
 export interface UnresolvedLink {
     /** Skill whose body carries the link. */
     from: string;
@@ -62,6 +177,22 @@ export interface ReachReport {
     /** Cross-skill links examined. */
     links: number;
     unresolved: UnresolvedLink[];
+    /** Gated relative links resolved against their own file. */
+    fileLinks: number;
+    unresolvedFiles: UnresolvedFileLink[];
+    /** Links into `docs/` — not delivered; reported, never failing. */
+    docsLinks: number;
+    /** `SKILL.md` links whose target exists only in the source repository — reported, never failing. */
+    repoOnlyLinks: UnresolvedFileLink[];
+    /** Reference files linking a sibling reference of their own skill. */
+    siblingLinks: UnresolvedFileLink[];
+}
+
+export interface UnresolvedFileLink {
+    /** File carrying the link, relative to the delivered skills root. */
+    file: string;
+    /** The target exactly as written. */
+    target: string;
 }
 
 /** Every skill directory in the delivered tree. */
@@ -83,10 +214,17 @@ export function run(root: string, ledger?: GateLedger): ReachReport {
     const slugs = deliveredSkills(root);
     const present = new Set(slugs);
     const unresolved: UnresolvedLink[] = [];
+    const unresolvedFiles: UnresolvedFileLink[] = [];
+    const siblingLinks: UnresolvedFileLink[] = [];
+    const repoOnlyLinks: UnresolvedFileLink[] = [];
     let links = 0;
+    let fileLinks = 0;
+    let docsLinks = 0;
+    const skillsRoot = path.join(root, DELIVERED_SKILLS_ROOT);
     for (const slug of slugs) {
         ledger?.plan(slug);
-        const file = path.join(root, DELIVERED_SKILLS_ROOT, slug, 'SKILL.md');
+        const skillDir = path.join(skillsRoot, slug);
+        const file = path.join(skillDir, 'SKILL.md');
         let source: string;
         try {
             source = fs.readFileSync(file, 'utf-8');
@@ -106,10 +244,61 @@ export function run(root: string, ledger?: GateLedger): ReachReport {
                 bad += 1;
             }
         }
-        if (bad > 0) ledger?.fail(slug, `${String(bad)} unresolved cross-skill link(s)`);
+        for (const target of relativeTargets(source)) {
+            if (CROSS_SKILL_TARGET.test(target)) continue;
+            if (DOCS_TARGET.test(target)) {
+                docsLinks += 1;
+                continue;
+            }
+            const exists = targetExists(skillDir, target);
+            fileLinks += 1;
+            if (!exists && !OWN_SKILL_DIRS.test(target) && targetExists(path.join(root, SOURCE_SKILLS_ROOT, slug), target)) {
+                repoOnlyLinks.push({ file: `${slug}/SKILL.md`, target });
+                continue;
+            }
+            if (!exists) {
+                unresolvedFiles.push({ file: `${slug}/SKILL.md`, target });
+                bad += 1;
+            }
+        }
+        for (const ref of referenceFiles(skillDir)) {
+            const rel = path.relative(skillsRoot, ref).split(path.sep).join('/');
+            for (const target of relativeTargets(fs.readFileSync(ref, 'utf-8'))) {
+                if (DOCS_TARGET.test(target)) {
+                    docsLinks += 1;
+                    continue;
+                }
+                fileLinks += 1;
+                if (!targetExists(path.dirname(ref), target)) {
+                    unresolvedFiles.push({ file: rel, target });
+                    bad += 1;
+                    continue;
+                }
+                const resolved = resolveTarget(path.dirname(ref), target);
+                if (
+                    resolved !== null &&
+                    resolved !== ref &&
+                    resolved.endsWith('.md') &&
+                    resolved.startsWith(path.join(skillDir, 'references') + path.sep) &&
+                    !ref.startsWith(path.join(skillDir, STEPS_DIR) + path.sep)
+                ) {
+                    siblingLinks.push({ file: rel, target });
+                }
+            }
+        }
+        if (bad > 0) ledger?.fail(slug, `${String(bad)} unresolved link(s)`);
         else ledger?.complete(slug);
     }
-    return { delivered: slugs.length, links, unresolved };
+    return {
+        delivered: slugs.length,
+        links,
+        unresolved,
+        fileLinks,
+        unresolvedFiles,
+        docsLinks,
+        repoOnlyLinks,
+        siblingLinks,
+    };
 }
 
 /** Self-test. The rejecting case is a link to a skill that is not delivered. */
@@ -128,8 +317,8 @@ function selfTest(): number {
     try {
         return runSelfTest({
             gate: 'lint_skill_link_reach',
-            minCases: 4,
-            minRejectCases: 2,
+            minCases: 5,
+            minRejectCases: 3,
             cases: [
                 {
                     name: 'a link to a skill that is NOT delivered is rejected',
@@ -149,6 +338,19 @@ function selfTest(): number {
                         return invoke();
                     },
                 },
+                {
+                    name: 'a references/ link one ../ short is rejected',
+                    expect: 'reject',
+                    run: () => {
+                        fresh();
+                        mk('a', 'body\n');
+                        mk('b', 'body\n');
+                        const refs = path.join(tmp, DELIVERED_SKILLS_ROOT, 'a', 'references');
+                        fs.mkdirSync(refs, { recursive: true });
+                        fs.writeFileSync(path.join(refs, 'r.md'), 'see [b](../b/SKILL.md)\n', 'utf-8');
+                        return invoke();
+                    },
+                },
                 {
                     name: 'a link to a delivered skill is accepted',
                     expect: 'accept',
@@ -188,6 +390,12 @@ export function main(argv: string[] = process.argv.slice(2)): number {
     const root = rootArg === undefined ? REPO_ROOT : path.resolve(rootArg);
     const quiet = argv.includes('--quiet');
     const isFixture = root !== REPO_ROOT;
+    const ceilingIdx = argv.indexOf('--sibling-ceiling');
+    const siblingCeiling = ceilingIdx >= 0 ? Number(argv[ceilingIdx + 1]) : SIBLING_LINK_CEILING;
+    if (!Number.isInteger(siblingCeiling) || siblingCeiling < 0) {
+        process.stderr.write('lint_skill_link_reach: --sibling-ceiling takes a non-negative integer\n');
+        return 2;
+    }
 
     const ledger = isFixture ? undefined : new GateLedger('lint_skill_link_reach');
     const report = run(root, ledger);
@@ -214,8 +422,8 @@ export function main(argv: string[] = process.argv.slice(2)): number {
         throw e;
     }
 
-    if (report.unresolved.length > 0) {
-        if (!quiet) {
+    if (report.unresolved.length > 0 || report.unresolvedFiles.length > 0) {
+        if (!quiet && report.unresolved.length > 0) {
             process.stderr.write(
                 `❌  lint_skill_link_reach: ${String(report.unresolved.length)} cross-skill link(s) ` +
                     `do not resolve inside ${DELIVERED_SKILLS_ROOT}:\n`,
@@ -228,14 +436,48 @@ export function main(argv: string[] = process.argv.slice(2)): number {
                     '   delivered set, or the link should point at something that is.\n',
             );
         }
+        if (!quiet && report.unresolvedFiles.length > 0) {
+            process.stderr.write(
+                `❌  lint_skill_link_reach: ${String(report.unresolvedFiles.length)} relative link(s) ` +
+                    `resolve to nothing against their own file inside ${DELIVERED_SKILLS_ROOT}:\n`,
+            );
+            for (const u of report.unresolvedFiles) process.stderr.write(`   ${u.file} → ${u.target}\n`);
+            process.stderr.write(
+                '   A link inside references/ resolves against references/, so it needs one more\n' +
+                    '   ../ than the same link written in SKILL.md.\n',
+            );
+        }
+        ledger?.report(quiet ? () => undefined : undefined);
+        return 1;
+    }
+    const siblings = report.siblingLinks.length;
+    if (siblings > siblingCeiling) {
+        if (!quiet) {
+            process.stderr.write(
+                `❌  lint_skill_link_reach: ${String(siblings)} reference-to-sibling-reference link(s), ` +
+                    `ceiling ${String(siblingCeiling)}. A reference file links no sibling reference of its ` +
+                    'own skill — link it from SKILL.md instead:\n',
+            );
+            for (const s of report.siblingLinks) process.stderr.write(`   ${s.file} → ${s.target}\n`);
+        }
         ledger?.report(quiet ? () => undefined : undefined);
         return 1;
     }
+    if (!quiet && siblings < siblingCeiling) {
+        process.stdout.write(
+            `   sibling-reference links fell to ${String(siblings)} — lower SIBLING_LINK_CEILING ` +
+                `from ${String(siblingCeiling)} to ${String(siblings)}.\n`,
+        );
+    }
     ledger?.report(quiet ? () => undefined : undefined);
     if (!quiet) {
         process.stdout.write(
-            `✅  lint_skill_link_reach: ${String(report.links)} cross-skill link(s) across ` +
-                `${String(report.delivered)} delivered skill(s) all resolve.\n`,
+            `✅  lint_skill_link_reach: ${String(report.links)} cross-skill link(s) and ` +
+                `${String(report.fileLinks)} relative link(s) across ` +
+                `${String(report.delivered)} delivered skill(s) all resolve.\n` +
+                `   reported, not gated: ${String(report.docsLinks)} link(s) into docs/ (not delivered — ` +
+                `measure_docs_dead_links owns them) · ${String(report.repoOnlyLinks.length)} SKILL.md ` +
+                `link(s) to a repo-only target (exists in the source repository, not delivered).\n`,
         );
     }
     return 0;

package/src/scripts/lint_skill_procedures.ts

@@ -0,0 +1,252 @@
+#!/usr/bin/env tsx
+/**
+ * Procedure sidecar lint (road-to-steps-the-skill-cannot-skip Phase 3).
+ *
+ * A skill whose procedure is handed out step by step carries
+ * `src/skills/<skill>/procedure.yaml` beside its SKILL.md. The sidecar is data
+ * with no runtime here: this lint holds its shape so the `/work` cursor can
+ * trust it later.
+ *
+ *   - Keys are closed at every level. No step names another skill — a `skill:`
+ *     key per step would be the skill-to-skill chain the skill-DAG lock rejects.
+ *   - `exit` is exactly one of `exists: <path>`, `schema: <path>#<id>`,
+ *     `check: <id>` (registered in `_lib/procedure_checks.ts`) or `judgement`.
+ *     Nothing a manifest says is ever executed.
+ *   - `when` takes a predicate from a closed vocabulary; a step not taken is
+ *     recorded by the runner as `skipped: <reason>`, never silently.
+ *   - Every step `file` exists under `references/steps/`, is linked from the
+ *     head, and no path escapes the skill directory; ids are unique.
+ *
+ * The share of `judgement` exits is reported, never gated.
+ *
+ * Exit codes: 0 clean, 1 violations, 2 usage.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import YAML from 'yaml';
+
+import { registeredCheckIds } from './_lib/procedure_checks.js';
+import { DeadScopeError, reportScanned } from './_lib/scan_scope.js';
+import { relativeTargets } from './lint_skill_link_reach.js';
+
+const _HERE = fileURLToPath(import.meta.url);
+const REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..');
+
+export const SIDECAR = 'procedure.yaml';
+const STEPS_DIR = 'references/steps/';
+const TOP_KEYS = new Set(['schema_version', 'brief', 'steps']);
+const BRIEF_KEYS = new Set(['goal', 'inputs', 'done_when']);
+const STEP_KEYS = new Set(['id', 'file', 'exit', 'when']);
+const STEP_ID = /^[a-z0-9][a-z0-9-]*$/;
+const CHECK_ID = /^[a-z0-9][a-z0-9-]*$/;
+
+/** The closed `when:` vocabulary — each takes one project-relative path. */
+export const WHEN_PREDICATES: ReadonlySet<string> = new Set(['file-exists', 'file-absent']);
+
+export type ExitKind = 'exists' | 'schema' | 'check' | 'judgement';
+
+export interface ParsedExit {
+    kind?: ExitKind;
+    error?: string;
+}
+
+/** A relative path that stays where it was resolved: no absolute, no `..`, no scheme. */
+function containedPath(p: string): boolean {
+    if (p === '' || path.isAbsolute(p) || /^[a-z][a-z0-9+.-]*:/i.test(p) || /[\s;&|`$<>]/.test(p)) return false;
+    return !p.split(/[\\/]/).includes('..');
+}
+
+export function parseExit(raw: unknown, skillDir: string, checks: ReadonlySet<string> = registeredCheckIds()): ParsedExit {
+    if (typeof raw !== 'string') return { error: 'exit must be a string' };
+    if (raw === 'judgement') return { kind: 'judgement' };
+    const m = /^(exists|schema|check): (.+)$/.exec(raw);
+    if (m === null) {
+        return { error: `exit '${raw}' is not one of exists: <path> · schema: <path>#<id> · check: <id> · judgement` };
+    }
+    const kind = m[1] as ExitKind;
+    const arg = (m[2] as string).trim();
+    if (kind === 'exists') {
+        return containedPath(arg) ? { kind } : { error: `exit 'exists: ${arg}' must name a relative path that does not escape` };
+    }
+    if (kind === 'check') {
+        if (!CHECK_ID.test(arg)) return { error: `exit 'check: ${arg}' must name a check id, not a command` };
+        if (!checks.has(arg)) return { error: `exit 'check: ${arg}' names no function registered in _lib/procedure_checks.ts` };
+        return { kind };
+    }
+    const hash = arg.lastIndexOf('#');
+    const file = hash === -1 ? '' : arg.slice(0, hash);
+    const id = hash === -1 ? '' : arg.slice(hash + 1);
+    if (file === '' || id === '' || !containedPath(file)) {
+        return { error: `exit 'schema: ${arg}' must be <path inside the skill>#<schema-id>` };
+    }
+    const abs = path.join(skillDir, file);
+    if (!fs.existsSync(abs)) return { error: `exit 'schema: ${arg}' — ${file} does not exist in the skill` };
+    try {
+        const doc = JSON.parse(fs.readFileSync(abs, 'utf-8')) as Record<string, unknown>;
+        const declared = String(doc['$id'] ?? '');
+        if (declared !== id && declared.replace(/\.schema\.json$/, '') !== id) {
+            return { error: `exit 'schema: ${arg}' — ${file} declares $id '${declared}', not '${id}'` };
+        }
+    } catch {
+        return { error: `exit 'schema: ${arg}' — ${file} is not valid JSON` };
+    }
+    return { kind };
+}
+
+function parseWhen(raw: unknown): string | undefined {
+    if (typeof raw !== 'string') return 'when must be a string';
+    const m = /^([a-z-]+): (.+)$/.exec(raw);
+    if (m === null || !WHEN_PREDICATES.has(m[1] as string)) {
+        return `when '${raw}' is not one of ${[...WHEN_PREDICATES].map((p) => `${p}: <path>`).join(' · ')}`;
+    }
+    return containedPath((m[2] as string).trim()) ? undefined : `when '${raw}' must name a relative path that does not escape`;
+}
+
+function unknownKeys(obj: Record<string, unknown>, allowed: ReadonlySet<string>, where: string): string[] {
+    return Object.keys(obj)
+        .filter((k) => !allowed.has(k))
+        .map((k) => `${where}: unknown key '${k}' (allowed: ${[...allowed].join(', ')})`);
+}
+
+export interface ProcedureReport {
+    errors: string[];
+    steps: number;
+    judgement: number;
+}
+
+export function lintProcedure(
+    skillDir: string,
+    text: string,
+    checks: ReadonlySet<string> = registeredCheckIds(),
+): ProcedureReport {
+    const errors: string[] = [];
+    let doc: unknown;
+    try {
+        doc = YAML.parse(text);
+    } catch (exc) {
+        return { errors: [`not valid YAML: ${(exc as Error).message.split('\n')[0]}`], steps: 0, judgement: 0 };
+    }
+    if (doc === null || typeof doc !== 'object' || Array.isArray(doc)) {
+        return { errors: ['the sidecar must be a mapping'], steps: 0, judgement: 0 };
+    }
+    const top = doc as Record<string, unknown>;
+    errors.push(...unknownKeys(top, TOP_KEYS, 'top level'));
+    if (top['schema_version'] !== 1) errors.push('schema_version must be 1');
+    const brief = top['brief'];
+    if (brief === null || typeof brief !== 'object' || Array.isArray(brief)) {
+        errors.push('brief must be a mapping with goal, inputs, done_when');
+    } else {
+        errors.push(...unknownKeys(brief as Record<string, unknown>, BRIEF_KEYS, 'brief'));
+        for (const k of BRIEF_KEYS) {
+            if (!(k in (brief as Record<string, unknown>))) errors.push(`brief.${k} is required`);
+        }
+    }
+    const steps = top['steps'];
+    if (!Array.isArray(steps) || steps.length === 0) {
+        errors.push('steps must be a non-empty list');
+        return { errors, steps: 0, judgement: 0 };
+    }
+    const head = fs.existsSync(path.join(skillDir, 'SKILL.md')) ? fs.readFileSync(path.join(skillDir, 'SKILL.md'), 'utf-8') : '';
+    const linked = new Set(relativeTargets(head).map((t) => path.posix.normalize(t.split('#')[0] ?? '')));
+    const seen = new Set<string>();
+    let judgement = 0;
+    steps.forEach((raw, i) => {
+        const where = `steps[${i}]`;
+        if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) {
+            errors.push(`${where} must be a mapping`);
+            return;
+        }
+        const step = raw as Record<string, unknown>;
+        errors.push(...unknownKeys(step, STEP_KEYS, where));
+        const id = step['id'];
+        if (typeof id !== 'string' || !STEP_ID.test(id)) {
+            errors.push(`${where}: id must be a lower-case slug`);
+        } else if (seen.has(id)) {
+            errors.push(`${where}: duplicate id '${id}'`);
+        } else {
+            seen.add(id);
+        }
+        const file = step['file'];
+        if (typeof file !== 'string' || !file.startsWith(STEPS_DIR) || !containedPath(file)) {
+            errors.push(`${where}: file must be a path under ${STEPS_DIR} that does not escape the skill`);
+        } else if (!fs.existsSync(path.join(skillDir, file))) {
+            errors.push(`${where}: file ${file} does not exist`);
+        } else if (!linked.has(path.posix.normalize(file))) {
+            errors.push(`${where}: file ${file} is not linked from SKILL.md`);
+        }
+        const exit = parseExit(step['exit'], skillDir, checks);
+        if (exit.error !== undefined) errors.push(`${where}: ${exit.error}`);
+        if (exit.kind === 'judgement') judgement += 1;
+        if ('when' in step) {
+            const bad = parseWhen(step['when']);
+            if (bad !== undefined) errors.push(`${where}: ${bad}`);
+        }
+    });
+    return { errors, steps: steps.length, judgement };
+}
+
+export function main(argv: string[] = process.argv.slice(2), root: string = REPO_ROOT): number {
+    if (argv.length > 0) {
+        process.stderr.write(`lint_skill_procedures: unknown argument ${argv[0]}\n`);
+        return 2;
+    }
+    const skillsRoot = path.join(root, 'src', 'skills');
+    const skills = fs.existsSync(skillsRoot)
+        ? fs.readdirSync(skillsRoot).filter((s) => fs.existsSync(path.join(skillsRoot, s, 'SKILL.md'))).sort()
+        : [];
+    try {
+        reportScanned({
+            gate: 'lint_skill_procedures',
+            scanned: skills.length,
+            units: 'skill(s)',
+            roots: ['src/skills'],
+            ...(root === REPO_ROOT ? {} : { allowEmpty: 'EMPTY_VALID: a fixture root may carry no skills' }),
+        });
+    } catch (exc) {
+        if (exc instanceof DeadScopeError) {
+            process.stderr.write(`❌  ${exc.message}\n`);
+            return 1;
+        }
+        throw exc;
+    }
+    const failures: string[] = [];
+    let procedures = 0;
+    let steps = 0;
+    let judgement = 0;
+    for (const s of skills) {
+        const sidecar = path.join(skillsRoot, s, SIDECAR);
+        if (!fs.existsSync(sidecar)) continue;
+        procedures += 1;
+        const r = lintProcedure(path.join(skillsRoot, s), fs.readFileSync(sidecar, 'utf-8'));
+        steps += r.steps;
+        judgement += r.judgement;
+        for (const e of r.errors) failures.push(`src/skills/${s}/${SIDECAR}: ${e}`);
+    }
+    const share = steps === 0 ? 'n/a' : `${Math.round((100 * judgement) / steps)} %`;
+    if (failures.length > 0) {
+        process.stdout.write(`❌  lint_skill_procedures: ${failures.length} violation(s):\n`);
+        for (const f of failures) process.stdout.write(`  🔴 ${f}\n`);
+        return 1;
+    }
+    process.stdout.write(
+        `✅  lint_skill_procedures: ${procedures} procedure sidecar(s) across ${skills.length} skill(s) valid.\n` +
+            `   reported, not gated: ${judgement} of ${steps} step exit(s) are judgement (${share}).\n`,
+    );
+    return 0;
+}
+
+function isCliEntry(): boolean {
+    if (process.argv[1] === undefined) return false;
+    if (import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href) return true;
+    try {
+        return fs.realpathSync(_HERE) === fs.realpathSync(path.resolve(process.argv[1]));
+    } catch {
+        return false;
+    }
+}
+
+if (isCliEntry()) {
+    process.exit(main());
+}

package/src/scripts/lint_skill_scripts_readonly.ts

@@ -81,6 +81,17 @@ function loadAllowlist(): Set<string> {
     return new Set(entries.map((e) => e.path));
 }
 
+/**
+ * A `.mjs` a sibling `.ts` produced — `build:skill-scripts` emits one beside
+ * every entry point. It is the same code twice, so counting it would report
+ * each mutation primitive in a bundled entry point a second time and let a
+ * source file pass review while its own bundle fails it.
+ */
+function isProducedBundle(file: string): boolean {
+    if (path.extname(file) !== '.mjs') return false;
+    return fs.existsSync(file.replace(/\.mjs$/, '.ts'));
+}
+
 function* scriptFiles(root: string): Generator<string> {
     if (!fs.existsSync(root)) return;
     for (const skill of fs.readdirSync(root, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
@@ -93,7 +104,7 @@ function* scriptFiles(root: string): Generator<string> {
             for (const e of fs.readdirSync(d, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
                 const full = path.join(d, e.name);
                 if (e.isDirectory()) stack.push(full);
-                else if (SCRIPT_EXT.has(path.extname(e.name))) yield full;
+                else if (SCRIPT_EXT.has(path.extname(e.name)) && !isProducedBundle(full)) yield full;
             }
         }
     }

package/src/scripts/lint_subagent_determinism.ts

@@ -37,9 +37,22 @@ function _listSubagents(dir: string): string[] {
     if (!fs.existsSync(dir)) {
         return [];
     }
+    // `_`-prefixed files are PARTIALS, never projected as agents.
+    //
+    // `src/subagents/_prompt-defense.md` says so in its own first line — it is
+    // a preamble composed into every projected subagent body at projection
+    // time — and two shipped readers already honour the convention:
+    // `build_discovery_manifest` and `condense` both skip a basename starting
+    // with `_`. This lint did not, so it demanded `subagent-v1` frontmatter
+    // from a markdown fragment that by contract has none, and reported "no
+    // parseable frontmatter" against a file that is correct as written.
+    //
+    // Skipping is the right repair rather than giving the partial frontmatter:
+    // the preamble is INJECTED into other bodies, so a `schema_version` in it
+    // would travel into every projected agent as stray text.
     return fs
         .readdirSync(dir)
-        .filter((f) => f.endsWith('.md'))
+        .filter((f) => f.endsWith('.md') && !f.startsWith('_'))
         .sort()
         .map((f) => path.join(dir, f));
 }