javi-forge 1.25.1 → 1.27.0

package/dist/lib/safe-read.js

@@ -0,0 +1,221 @@
+/**
+ * Bounded, non-throwing file reads.
+ *
+ * Every whole-file read in this CLI used to be an unguarded
+ * `fs.readFile(path, "utf-8")`: a 400 MB log, a minified bundle or a binary
+ * blob under a scanned directory could exhaust memory or stall a scan. This
+ * module is the single guarded entry point — it caps bytes during the read,
+ * rejects binaries by content sniffing, clamps pathological single lines, and
+ * returns a discriminated union instead of throwing for expected conditions.
+ *
+ * Deliberately NOT included: no path allow/block list. This is a local CLI
+ * operating on the user's own repository, so any path they can name they can
+ * already `cat`; a blocklist would add friction without adding a boundary.
+ */
+import { open, stat } from "node:fs/promises";
+// =============================================================================
+// Constants
+// =============================================================================
+/** Default byte budget for a single read (1 MiB). */
+export const DEFAULT_MAX_BYTES = 1024 * 1024;
+/** Default per-line character clamp — catches minified bundles and data URIs. */
+export const DEFAULT_MAX_LINE_LENGTH = 10_000;
+/** Size of each read from the file handle. */
+const READ_CHUNK_BYTES = 64 * 1024;
+/** Bytes of the first chunk sniffed for NUL when classifying binary content. */
+const BINARY_SNIFF_BYTES = 8 * 1024;
+const BOM = "\uFEFF";
+// =============================================================================
+// Internal helpers
+// =============================================================================
+function errnoOf(err) {
+    return typeof err === "object" && err !== null && "code" in err
+        ? String(err.code)
+        : undefined;
+}
+function messageOf(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+/**
+ * Drop a trailing partial UTF-8 sequence so a byte-capped buffer never decodes
+ * into a replacement character. Scans back at most 3 bytes (max lead distance
+ * for a 4-byte sequence) looking for a lead byte whose sequence would run past
+ * the end of the buffer.
+ */
+function trimPartialUtf8(buf) {
+    const maxLookback = Math.min(3, buf.length);
+    for (let back = 0; back < maxLookback; back++) {
+        const index = buf.length - 1 - back;
+        const byte = buf[index];
+        // Continuation byte (10xxxxxx): keep walking back to its lead byte.
+        if ((byte & 0xc0) === 0x80)
+            continue;
+        // ASCII byte: the buffer ends on a complete codepoint.
+        if ((byte & 0x80) === 0)
+            return buf;
+        // Lead byte: does its full sequence fit in what we kept?
+        let needed = 0;
+        if ((byte & 0xe0) === 0xc0)
+            needed = 2;
+        else if ((byte & 0xf0) === 0xe0)
+            needed = 3;
+        else if ((byte & 0xf8) === 0xf0)
+            needed = 4;
+        else
+            return buf; // invalid lead byte — leave it to the decoder
+        const available = buf.length - index;
+        return available >= needed ? buf : buf.subarray(0, index);
+    }
+    return buf;
+}
+/** Clamp lines longer than `maxLineLength`, marking how much was dropped. */
+function clampLongLines(content, maxLineLength) {
+    if (!Number.isFinite(maxLineLength) || maxLineLength <= 0) {
+        return { content, clamped: false };
+    }
+    if (content.length <= maxLineLength)
+        return { content, clamped: false };
+    const lines = content.split("\n");
+    let clamped = false;
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        if (line.length <= maxLineLength)
+            continue;
+        const dropped = line.length - maxLineLength;
+        lines[i] = `${line.slice(0, maxLineLength)}…[clamped ${dropped} chars]`;
+        clamped = true;
+    }
+    return clamped
+        ? { content: lines.join("\n"), clamped }
+        : { content, clamped };
+}
+// =============================================================================
+// Public API
+// =============================================================================
+/**
+ * Read a text file with a byte budget, binary rejection and line clamping.
+ *
+ * Never throws for expected conditions (missing file, directory, binary,
+ * oversized, permission denied) — inspect `result.ok` and branch on `reason`.
+ *
+ * Newlines are returned verbatim: CRLF is NOT normalized, because the callers
+ * migrated to this helper already tolerate `\r` (they `trim()` split lines) and
+ * silently rewriting bytes would make reported offsets diverge from the file.
+ */
+export async function safeReadFile(filePath, opts = {}) {
+    const maxBytes = opts.maxBytes ?? DEFAULT_MAX_BYTES;
+    const maxLineLength = opts.maxLineLength ?? DEFAULT_MAX_LINE_LENGTH;
+    const hardRejectOverBytes = opts.hardRejectOverBytes;
+    // -- Stat first: classify directories, sockets and missing paths cheaply ---
+    let totalBytes;
+    try {
+        const stats = await stat(filePath);
+        if (!stats.isFile()) {
+            return {
+                ok: false,
+                reason: "not-a-file",
+                detail: stats.isDirectory()
+                    ? "path is a directory"
+                    : "not a regular file",
+            };
+        }
+        totalBytes = stats.size;
+    }
+    catch (err) {
+        const code = errnoOf(err);
+        if (code === "ENOENT" || code === "ENOTDIR") {
+            return { ok: false, reason: "not-found", detail: filePath };
+        }
+        return { ok: false, reason: "io-error", detail: messageOf(err) };
+    }
+    if (hardRejectOverBytes !== undefined && totalBytes > hardRejectOverBytes) {
+        return {
+            ok: false,
+            reason: "too-large",
+            detail: `${totalBytes} bytes exceeds limit of ${hardRejectOverBytes}`,
+        };
+    }
+    if (maxBytes <= 0) {
+        return {
+            ok: true,
+            content: "",
+            truncated: totalBytes > 0,
+            bytesRead: 0,
+            totalBytes,
+            longLinesClamped: false,
+        };
+    }
+    // -- Read in chunks, enforcing the budget as we go (never buffer it all) ---
+    const chunks = [];
+    let collected = 0;
+    let truncated = false;
+    let handle;
+    try {
+        handle = await open(filePath, "r");
+        while (collected < maxBytes) {
+            const want = Math.min(READ_CHUNK_BYTES, maxBytes - collected);
+            const buf = Buffer.allocUnsafe(want);
+            const { bytesRead } = await handle.read(buf, 0, want, null);
+            if (bytesRead === 0)
+                break;
+            const chunk = buf.subarray(0, bytesRead);
+            // Binary sniff on the first chunk only — by content, never extension.
+            if (chunks.length === 0) {
+                const sniff = chunk.subarray(0, BINARY_SNIFF_BYTES);
+                if (sniff.includes(0)) {
+                    return {
+                        ok: false,
+                        reason: "binary",
+                        detail: "NUL byte in first chunk",
+                    };
+                }
+            }
+            chunks.push(chunk);
+            collected += bytesRead;
+        }
+        // One probe byte tells us whether the budget actually cut something off.
+        if (collected >= maxBytes) {
+            const probe = Buffer.allocUnsafe(1);
+            const { bytesRead } = await handle.read(probe, 0, 1, null);
+            truncated = bytesRead > 0;
+        }
+    }
+    catch (err) {
+        return { ok: false, reason: "io-error", detail: messageOf(err) };
+    }
+    finally {
+        await handle?.close().catch(() => { });
+    }
+    let buffer = Buffer.concat(chunks, collected);
+    if (truncated)
+        buffer = trimPartialUtf8(buffer);
+    const bytesRead = buffer.length;
+    let content = buffer.toString("utf-8");
+    if (content.startsWith(BOM))
+        content = content.slice(BOM.length);
+    const { content: clampedContent, clamped } = clampLongLines(content, maxLineLength);
+    return {
+        ok: true,
+        content: clampedContent,
+        truncated,
+        bytesRead,
+        totalBytes,
+        longLinesClamped: clamped,
+    };
+}
+/** Human-readable one-liner for a failed read — for CLI notes and findings. */
+export function describeSafeReadFailure(failure) {
+    switch (failure.reason) {
+        case "not-found":
+            return "file not found";
+        case "not-a-file":
+            return failure.detail ?? "not a regular file";
+        case "binary":
+            return "binary file";
+        case "too-large":
+            return failure.detail ? `too large (${failure.detail})` : "too large";
+        case "io-error":
+            return failure.detail ? `read error: ${failure.detail}` : "read error";
+    }
+}
+//# sourceMappingURL=safe-read.js.map

package/dist/lib/security-analysis.d.ts

@@ -25,12 +25,29 @@ export interface SecurityAnalysisReport {
     projectDir: string;
     findings: SecurityAnalysisFinding[];
     summary: SecurityAnalysisSummary;
+    /**
+     * Files the pattern pass never saw — binary, oversized or unreadable. A scan
+     * that silently skipped files is not a clean scan, so they are reported.
+     */
+    skipped?: SecurityAnalysisSkippedFile[];
+}
+export interface SecurityAnalysisSkippedFile {
+    /** Path relative to `projectDir`, matching the finding paths. */
+    file: string;
+    reason: string;
 }
 export interface SecurityAnalysisSummary {
     total: number;
     bySeverity: Record<SecuritySeverity, number>;
     byCategory: Record<string, number>;
     passed: boolean;
+    /**
+     * True when at least one file was skipped or only partially scanned (binary,
+     * oversized, I/O error, truncated, or clamped). The scan did not see the whole
+     * codebase, so `passed` is forced to `false` — a clean result over an
+     * incomplete scan would be a fail-open lie.
+     */
+    incomplete: boolean;
     failThreshold: SecuritySeverity;
 }
 export interface SecurityAnalysisOptions {
@@ -64,8 +81,8 @@ export declare function detectFileLanguage(filePath: string): string | null;
 export declare function matchRule(rule: SemgrepRule, content: string, filePath: string): SecurityAnalysisFinding[];
 export declare function collectFiles(dir: string): Promise<string[]>;
 export declare function severityAtOrAbove(severity: SecuritySeverity, threshold: SecuritySeverity): boolean;
-export declare function buildSummary(findings: SecurityAnalysisFinding[], failThreshold: SecuritySeverity): SecurityAnalysisSummary;
-export declare function buildReport(findings: SecurityAnalysisFinding[], projectDir: string, options?: SecurityAnalysisOptions): SecurityAnalysisReport;
+export declare function buildSummary(findings: SecurityAnalysisFinding[], failThreshold: SecuritySeverity, incomplete?: boolean): SecurityAnalysisSummary;
+export declare function buildReport(findings: SecurityAnalysisFinding[], projectDir: string, options?: SecurityAnalysisOptions, skipped?: SecurityAnalysisSkippedFile[]): SecurityAnalysisReport;
 export declare function filterRules(rules: SemgrepRule[], options?: SecurityAnalysisOptions): SemgrepRule[];
 export declare function loadCustomRules(rulesDir: string): Promise<SemgrepRule[]>;
 export declare function runSecurityAnalysis(projectDir: string, options?: SecurityAnalysisOptions): Promise<SecurityAnalysisReport>;

package/dist/lib/security-analysis.js

@@ -7,9 +7,15 @@
  */
 import path from "node:path";
 import fs from "fs-extra";
+import { describeSafeReadFailure, safeReadFile } from "./safe-read.js";
 // =============================================================================
 // Constants
 // =============================================================================
+/**
+ * Hard ceiling per scanned file. Source files past this are generated or
+ * vendored bundles: running every rule over them costs far more than it finds.
+ */
+const MAX_ANALYSIS_BYTES = 2 * 1024 * 1024;
 const SEVERITY_ORDER = {
     critical: 5,
     high: 4,
@@ -316,7 +322,7 @@ export function severityAtOrAbove(severity, threshold) {
 // =============================================================================
 // Report generation
 // =============================================================================
-export function buildSummary(findings, failThreshold) {
+export function buildSummary(findings, failThreshold, incomplete = false) {
     const bySeverity = {
         critical: 0,
         high: 0,
@@ -329,23 +335,29 @@ export function buildSummary(findings, failThreshold) {
         bySeverity[f.severity]++;
         byCategory[f.category] = (byCategory[f.category] ?? 0) + 1;
     }
-    const passed = !findings.some((f) => severityAtOrAbove(f.severity, failThreshold));
+    // Fail closed on an incomplete scan: a file we never fully read could hold the
+    // very finding that would have failed the gate. No threshold finding is not
+    // the same as "clean" when part of the codebase was invisible to the scan.
+    const noThresholdFinding = !findings.some((f) => severityAtOrAbove(f.severity, failThreshold));
+    const passed = noThresholdFinding && !incomplete;
     return {
         total: findings.length,
         bySeverity,
         byCategory,
         passed,
+        incomplete,
         failThreshold,
     };
 }
-export function buildReport(findings, projectDir, options = {}) {
+export function buildReport(findings, projectDir, options = {}, skipped = []) {
     const failThreshold = options.failThreshold ?? "high";
     return {
         engine: "semgrep",
         timestamp: new Date().toISOString(),
         projectDir,
         findings,
-        summary: buildSummary(findings, failThreshold),
+        summary: buildSummary(findings, failThreshold, skipped.length > 0),
+        ...(skipped.length > 0 ? { skipped } : {}),
     };
 }
 // =============================================================================
@@ -426,16 +438,42 @@ export async function runSecurityAnalysis(projectDir, options = {}) {
     }
     // Run pattern matching
     const findings = [];
+    const skipped = [];
     for (const filePath of allFiles) {
-        let content;
-        try {
-            content = await fs.readFile(filePath, "utf-8");
-        }
-        catch {
-            continue;
-        }
+        // Guarded read: a binary blob or a multi-megabyte bundle would otherwise
+        // be fed to every regex rule in the set. `maxBytes` is pinned to the same
+        // ceiling as the hard reject so the documented 2 MiB limit is the effective
+        // scan cap — otherwise the 1 MiB default would silently truncate every file
+        // between 1 and 2 MiB and MAX_ANALYSIS_BYTES would be a dead constant.
+        const read = await safeReadFile(filePath, {
+            maxBytes: MAX_ANALYSIS_BYTES,
+            hardRejectOverBytes: MAX_ANALYSIS_BYTES,
+        });
         // Use relative paths in findings for readability
         const relativePath = path.relative(projectDir, filePath);
+        if (!read.ok) {
+            skipped.push({
+                file: relativePath,
+                reason: describeSafeReadFailure(read),
+            });
+            continue;
+        }
+        const content = read.content;
+        if (read.truncated) {
+            skipped.push({
+                file: relativePath,
+                reason: `truncated at ${read.bytesRead} of ${read.totalBytes} bytes — scanned partially`,
+            });
+        }
+        // A clamped long line means the regex pass saw a shortened line — a payload
+        // hidden past the clamp would be invisible. Record it like a truncation so
+        // the scan is marked incomplete and cannot report a clean pass.
+        if (read.longLinesClamped) {
+            skipped.push({
+                file: relativePath,
+                reason: "long line(s) clamped — scanned partially",
+            });
+        }
         for (const rule of rules) {
             const matches = matchRule(rule, content, filePath);
             // Rewrite file paths to relative
@@ -452,7 +490,7 @@ export async function runSecurityAnalysis(projectDir, options = {}) {
             return sevDiff;
         return a.file.localeCompare(b.file);
     });
-    return buildReport(findings, projectDir, options);
+    return buildReport(findings, projectDir, options, skipped);
 }
 // =============================================================================
 // Report formatting (for CI output)
@@ -468,7 +506,14 @@ export function formatReportText(report) {
         .map(([sev, count]) => `${count} ${sev}`)
         .join(", ") || "none"}`);
     lines.push(`Pass threshold: ${summary.failThreshold}`);
-    lines.push(`Result: ${summary.passed ? "PASS" : "FAIL"}`);
+    lines.push(`Result: ${summary.passed
+        ? "PASS"
+        : summary.incomplete
+            ? "FAIL (incomplete scan — some files were not fully analysed)"
+            : "FAIL"}`);
+    if (report.skipped && report.skipped.length > 0) {
+        lines.push(`Skipped files: ${report.skipped.length}`);
+    }
     lines.push("");
     if (findings.length > 0) {
         lines.push("--- Findings ---");
@@ -481,6 +526,13 @@ export function formatReportText(report) {
             lines.push(`  ${f.message}`);
         }
     }
+    if (report.skipped && report.skipped.length > 0) {
+        lines.push("");
+        lines.push("--- Skipped ---");
+        for (const s of report.skipped) {
+            lines.push(`${s.file}: ${s.reason}`);
+        }
+    }
     return lines.join("\n");
 }
 export function formatReportJson(report) {

package/dist/lib/skill-scanner.d.ts

@@ -15,13 +15,34 @@ export interface SkillThreat {
     context: string;
     message: string;
 }
-export type SkillScanVerdict = "pass" | "warn" | "block";
+/**
+ * `unscannable` is a fail-closed verdict: the file could not be read in full
+ * (binary, oversized, I/O error) or a content-mutating clamp/truncation
+ * happened during the read, so we cannot certify it. A gate MUST treat it as a
+ * rejection exactly like `block` — see {@link isRejectedVerdict}, the single
+ * predicate every install/registry gate should use instead of `=== "block"`.
+ */
+export type SkillScanVerdict = "pass" | "warn" | "block" | "unscannable";
+/**
+ * The set of verdicts an install/registry gate rejects on. Fail-closed:
+ * `block` (a critical threat was found) and `unscannable` (the file could not
+ * be certified because it was not fully scanned) both mean "do not install".
+ * Use this everywhere instead of a bare `verdict === "block"` check so a future
+ * gate can never let an `unscannable` file slip through.
+ */
+export declare function isRejectedVerdict(verdict: SkillScanVerdict): boolean;
 export interface SkillScanResult {
     skillPath: string;
     skillName: string;
     verdict: SkillScanVerdict;
     threats: SkillThreat[];
     summary: SkillScanSummary;
+    /**
+     * Scan-level notes — populated when the file could not be fully analysed
+     * (binary, oversized, unreadable) so a skipped file is visible in the report
+     * instead of masquerading as a clean pass.
+     */
+    notes?: string[];
 }
 export interface SkillScanSummary {
     total: number;

package/dist/lib/skill-scanner.js

@@ -7,6 +7,17 @@
  */
 import path from "node:path";
 import fs from "fs-extra";
+import { describeSafeReadFailure, safeReadFile } from "./safe-read.js";
+/**
+ * The set of verdicts an install/registry gate rejects on. Fail-closed:
+ * `block` (a critical threat was found) and `unscannable` (the file could not
+ * be certified because it was not fully scanned) both mean "do not install".
+ * Use this everywhere instead of a bare `verdict === "block"` check so a future
+ * gate can never let an `unscannable` file slip through.
+ */
+export function isRejectedVerdict(verdict) {
+    return verdict === "block" || verdict === "unscannable";
+}
 /**
  * Ordered by severity (critical first). Each pattern is tested against
  * every non-comment line in the skill file.
@@ -282,18 +293,66 @@ export function extractSkillName(content, filePath) {
 // =============================================================================
 // Main scan function
 // =============================================================================
+/**
+ * Hard ceiling for a scanned skill file. Past this it is not a skill document
+ * but a dumped log or a vendored bundle: scanning it would run every regex
+ * over megabytes of noise, so it is skipped and reported instead.
+ */
+const MAX_SCAN_BYTES = 1024 * 1024;
 export async function scanSkillFile(filePath) {
-    const content = await fs.readFile(filePath, "utf-8");
+    // `maxLineLength: 0` disables the per-line clamp for the scanner's own read:
+    // a padded single line hiding `rm -rf ~` past column 10k must reach the regex
+    // pass intact, not be silently truncated and then scanned as if complete. The
+    // total-byte ceiling still bounds memory (a file past it fails `too-large`).
+    const read = await safeReadFile(filePath, {
+        hardRejectOverBytes: MAX_SCAN_BYTES,
+        maxLineLength: 0,
+    });
+    // A file we could not read is not a clean file. Never crash the batch, and
+    // never report it as a pass: an unscannable file cannot be certified safe, so
+    // it fails closed with the strongest verdict a gate rejects on.
+    if (!read.ok) {
+        return {
+            skillPath: filePath,
+            skillName: path.basename(path.dirname(filePath)),
+            verdict: "unscannable",
+            threats: [],
+            summary: computeScanSummary([]),
+            notes: [
+                `scanning incomplete: ${describeSafeReadFailure(read)} — rejected (an unscannable file cannot be certified safe)`,
+            ],
+        };
+    }
+    const content = read.content;
     const skillName = extractSkillName(content, filePath);
     const threats = scanSkillContent(content, filePath);
-    const verdict = computeVerdict(threats);
     const summary = computeScanSummary(threats);
+    // A content-mutating read (truncated bytes, or a clamped line) means the
+    // regex pass did NOT see the whole file. Even if no threat surfaced in what
+    // we did see, we cannot certify the rest — fail closed rather than emit a
+    // pass/warn over partial content. With `maxLineLength: 0` and the byte
+    // ceiling above these should not fire, but the guard is the safety net.
+    const incomplete = read.truncated || read.longLinesClamped;
+    const notes = [];
+    if (read.truncated) {
+        notes.push(`truncated: only the first ${read.bytesRead} of ${read.totalBytes} bytes were scanned`);
+    }
+    if (read.longLinesClamped) {
+        notes.push("clamped: one or more lines exceeded the per-line limit");
+    }
+    if (incomplete) {
+        notes.push("rejected: the file was not fully scanned and cannot be certified safe");
+    }
+    const verdict = incomplete
+        ? "unscannable"
+        : computeVerdict(threats);
     return {
         skillPath: filePath,
         skillName,
         verdict,
         threats,
         summary,
+        ...(notes.length > 0 ? { notes } : {}),
     };
 }
 /**
@@ -346,6 +405,12 @@ export function formatScanReport(result) {
     lines.push(`Verdict: ${verdict.toUpperCase()}`);
     lines.push(`Findings: ${summary.total} (${summary.critical} critical, ${summary.high} high, ${summary.moderate} moderate, ${summary.low} low)`);
     lines.push("");
+    if (result.notes && result.notes.length > 0) {
+        lines.push("--- Notes ---");
+        for (const note of result.notes)
+            lines.push(`  ${note}`);
+        lines.push("");
+    }
     if (threats.length > 0) {
         lines.push("--- Threats ---");
         for (const t of threats) {
@@ -354,7 +419,11 @@ export function formatScanReport(result) {
             lines.push(`  Context: ${t.context}`);
         }
     }
-    if (verdict === "block") {
+    if (verdict === "unscannable") {
+        lines.push("");
+        lines.push("REJECTED: File could not be fully scanned, so it cannot be certified safe. Not installed.");
+    }
+    else if (verdict === "block") {
         lines.push("");
         lines.push("BLOCKED: Critical threats detected. Review and remove before installing.");
     }
@@ -367,11 +436,14 @@ export function formatScanReport(result) {
 export function formatBatchReport(results) {
     const lines = [];
     const blocked = results.filter((r) => r.verdict === "block");
+    const unscannable = results.filter((r) => r.verdict === "unscannable");
     const warned = results.filter((r) => r.verdict === "warn");
     const passed = results.filter((r) => r.verdict === "pass");
     lines.push(`=== SkillGuard Batch Scan ===`);
     lines.push(`Scanned: ${results.length} skill(s)`);
-    lines.push(`Blocked: ${blocked.length}`);
+    lines.push(`Rejected: ${blocked.length + unscannable.length}`);
+    lines.push(`  Blocked (threats): ${blocked.length}`);
+    lines.push(`  Unscannable (not certified): ${unscannable.length}`);
     lines.push(`Warned: ${warned.length}`);
     lines.push(`Passed: ${passed.length}`);
     lines.push("");

package/dist/types/index.d.ts

@@ -226,6 +226,11 @@ export interface SkillBudgetEntry {
     skillName: string;
     skillPath: string;
     tokens: number;
+    /**
+     * Set when the SKILL.md could not be fully read (binary, oversized, I/O
+     * error) — `tokens` is then partial or zero and should be read with care.
+     */
+    note?: string;
 }
 export interface SkillBudgetSuggestion {
     /** Skills to disable in this suggestion set */
@@ -271,6 +276,13 @@ export interface SkillScore {
     grade: SkillGrade;
     threshold: number;
     passing: boolean;
+    /**
+     * Set when the SKILL.md could not be read (binary, oversized, I/O error). The
+     * numeric dimensions are then meaningless placeholders (all `0`, never a
+     * computed grade or `safety: 100`); callers must surface the file as unread
+     * rather than as a scored skill. `passing` is always `false` in this state.
+     */
+    unread?: string;
 }
 export interface SkillRegistryGateResult {
     skillName: string;
@@ -287,6 +299,12 @@ export interface SkillBenchmarkResult {
     skillName: string;
     checks: SkillBenchmarkCheck[];
     passRate: number;
+    /**
+     * Set when the SKILL.md could not be read (binary, oversized, I/O error). No
+     * checks were run (`checks` is empty, `passRate` is `0`); callers must surface
+     * the file as unread rather than as a benchmarked skill that failed every check.
+     */
+    unread?: string;
 }
 declare const WORKFLOW_FORMAT: {
     readonly DOT: "dot";

package/dist/ui/Skills.js

@@ -66,13 +66,18 @@ export default function Skills({ mode, budget, deep, skillsDir }) {
                         result.budget.budget,
                         " tokens",
                         result.budget.overBudget ? " (OVER BUDGET)" : "")),
-                result.budget.entries.map((entry) => (React.createElement(Box, { key: entry.skillName, marginLeft: 4 },
-                    React.createElement(Text, { color: theme.muted }, entry.skillName),
-                    React.createElement(Text, { color: theme.muted, dimColor: true },
-                        "  ",
-                        "~",
-                        entry.tokens,
-                        " tokens")))),
+                result.budget.entries.map((entry) => (React.createElement(Box, { key: entry.skillName, flexDirection: "column", marginLeft: 4 },
+                    React.createElement(Box, null,
+                        React.createElement(Text, { color: entry.note ? theme.warning : theme.muted }, entry.skillName),
+                        React.createElement(Text, { color: theme.muted, dimColor: true },
+                            "  ",
+                            "~",
+                            entry.tokens,
+                            " tokens")),
+                    entry.note && (React.createElement(Box, { marginLeft: 2 },
+                        React.createElement(Text, { color: theme.warning },
+                            "! ",
+                            entry.note)))))),
                 result.budget.suggestions.map((s, i) => (React.createElement(Box, { key: `suggestion-${i}`, marginLeft: 4 },
                     React.createElement(Text, { color: theme.warning },
                         "! ",

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "javi-forge",
-	"version": "1.25.1",
+	"version": "1.27.0",
 	"description": "Project scaffolding and AI-ready CI bootstrap",
 	"type": "module",
 	"bin": {

package/templates/github/ghagga-review.yml

@@ -1,30 +0,0 @@
-# ===========================================
-# GHAGGA AI Code Review
-# ===========================================
-# Triggers AI code review on pull requests.
-# Requires: GHAGGA GitHub Action (JNZader/ghagga@v1)
-#
-# Modes: simple (default), workflow, consensus
-# ===========================================
-
-name: Code Review
-
-on:
-  pull_request:
-    types: [opened, synchronize, reopened]
-
-permissions:
-  pull-requests: write
-  contents: read
-
-jobs:
-  review:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
-      # TODO(pin): ghagga has no v1 tag upstream (releases start at v2) — this
-      # ref cannot be SHA-pinned as-is; pick a real released tag and pin it.
-      - uses: JNZader/ghagga@v1
-        with:
-          mode: simple
-          provider: github