javi-forge 1.26.0 → 1.28.0

package/ci-local/hooks/commit-msg

@@ -1,6 +1,13 @@
 #!/bin/bash
 set -e
 # =============================================================================
+# LEGACY — retained for reference only (hook-consolidation).
+# The canonical hook mechanism is now `.git/hooks/` written by `installCIHooks`
+# (javi-forge ci init / init). The shipped commit-msg shim lives in
+# assets/hooks/commit-msg; `javi-forge init` no longer copies this directory or
+# sets `core.hooksPath=ci-local/hooks`. This body is kept for historical
+# reference and is NOT the source of truth. See docs/commands.md → hooks.
+# =============================================================================
 # COMMIT-MSG: Block accidental AI-attribution in commit messages
 # =============================================================================
 # Best-effort, NOT an adversarial-grade security control.

package/ci-local/hooks/pre-commit

@@ -1,5 +1,13 @@
 #!/bin/bash
 # =============================================================================
+# LEGACY — retained for reference only (hook-consolidation).
+# The canonical hook mechanism is now `.git/hooks/` written by `installCIHooks`
+# (javi-forge ci init / init), whose static shims exec the dispatcher
+# `javi-forge hooks run <name>`. `javi-forge init` no longer copies this
+# directory or sets `core.hooksPath=ci-local/hooks`; a repo still on that legacy
+# path is auto-migrated on the next install. This body is kept for historical
+# reference and is NOT the source of truth. See docs/commands.md → hooks.
+# =============================================================================
 # PRE-COMMIT: Quick CI check via javi-forge
 # =============================================================================
 # Requires: npm install -g javi-forge

package/ci-local/hooks/pre-push

@@ -1,5 +1,13 @@
 #!/bin/bash
 # =============================================================================
+# LEGACY — retained for reference only (hook-consolidation).
+# The canonical hook mechanism is now `.git/hooks/` written by `installCIHooks`
+# (javi-forge ci init / init), whose static shims exec the dispatcher
+# `javi-forge hooks run <name>`. `javi-forge init` no longer copies this
+# directory or sets `core.hooksPath=ci-local/hooks`; a repo still on that legacy
+# path is auto-migrated on the next install. This body is kept for historical
+# reference and is NOT the source of truth. See docs/commands.md → hooks.
+# =============================================================================
 # PRE-PUSH: Full CI simulation via javi-forge
 # =============================================================================
 # Requires: npm install -g javi-forge

package/dist/cli/dispatch/ci.js

@@ -83,7 +83,7 @@ export async function handleCi(cli, ctx) {
         }
         if (installed.length > 0) {
             console.log(`✓ Installed git hooks: ${installed.join(", ")}`);
-            console.log("  Hooks call javi-forge ci (with npx fallback)");
+            console.log("  Hooks call javi-forge hooks run (with npx fallback)");
         }
         // Upgrades are reported DISTINCTLY from fresh installs: replacing an
         // older javi-forge hook is not the same event as writing a new one.

package/dist/cli/dispatch/simple-renderers.js

@@ -46,7 +46,7 @@ export function handlePlugin(cli, ctx) {
         : "list";
     const target = cli.input[2];
     render(React.createElement(CIContextProvider, { isCI: ctx.isCI },
-        React.createElement(Plugin, { action: action, target: target, dryRun: cli.flags.dryRun, codex: cli.flags.codex })), { stdin: ctx.inkStdin });
+        React.createElement(Plugin, { action: action, target: target, dryRun: cli.flags.dryRun, codex: cli.flags.codex, force: cli.flags.force })), { stdin: ctx.inkStdin });
 }
 export function handleInitDefault(cli, ctx) {
     const presetStack = VALID_STACKS.includes(cli.flags.stack)

package/dist/cli/dispatch/skills-cmd.js

@@ -37,7 +37,7 @@ export async function handleSkillsCmd(cli, ctx) {
     // Auto / auto-install: render interactive Ink UI
     if (skillsAction === "auto" || skillsAction === "auto-install") {
         render(React.createElement(CIContextProvider, { isCI: ctx.isCI },
-            React.createElement(AutoSkills, { projectDir: process.cwd(), skillsDir: cli.flags.skillsDir || undefined, dryRun: cli.flags.dryRun })), { stdin: ctx.inkStdin });
+            React.createElement(AutoSkills, { projectDir: process.cwd(), skillsDir: cli.flags.skillsDir || undefined, dryRun: cli.flags.dryRun, force: cli.flags.force })), { stdin: ctx.inkStdin });
         return;
     }
     // Score and benchmark are non-interactive CLI commands
@@ -57,6 +57,10 @@ export async function handleSkillsCmd(cli, ctx) {
                 console.error(`\u2717 Skill not found: ${skillPath}`);
                 process.exit(1);
             }
+            if (result.unread) {
+                console.error(`\u2717 Skill could not be scored \u2014 ${result.unread}: ${skillPath}`);
+                process.exit(1);
+            }
             console.log(`\nSkill: ${result.skillName}`);
             console.log(`  Completeness:      ${result.completeness}/100`);
             console.log(`  Clarity:           ${result.clarity}/100`);
@@ -77,6 +81,10 @@ export async function handleSkillsCmd(cli, ctx) {
             console.error(`\u2717 Skill not found: ${skillPath}`);
             process.exit(1);
         }
+        if (result.unread) {
+            console.error(`\u2717 Skill could not be benchmarked \u2014 ${result.unread}: ${skillPath}`);
+            process.exit(1);
+        }
         console.log(`\nBenchmark: ${result.skillName}`);
         for (const check of result.checks) {
             const icon = check.passed ? "\u2713" : "\u2717";

package/dist/cli/help.d.ts

@@ -8,7 +8,7 @@
  * Help banner shown by meow when `--help` is passed or invalid args are supplied.
  * Multi-line template literal — preserve exact formatting (whitespace is significant).
  */
-export declare const HELP_TEXT = "\n  Usage\n    $ javi-forge [command] [options]\n\n  Commands\n    init              Bootstrap a new project (default)\n    ci                Run CI simulation (lint + compile + test + security + ghagga)\n    ci validate       Validate .javi-forge/ci.yaml without running anything\n    ci init           Install git hooks that call javi-forge ci\n    tdd init          Enable the TDD pre-commit section + install managed hooks\n    tdd pipeline      Enable the TDD pre-push section (--mode strict|warn)\n    hooks run         Run a git hook's composed sections (pre-commit | pre-push)\n    analyze           Run repoforge skills analysis\n    doctor            Show health report\n    workflow show     Render a workflow graph as ASCII (--template <name> or file path)\n    workflow validate Validate project state against a workflow graph\n    workflow list     List available workflows and built-in templates\n    plugin add        Install a plugin from GitHub (org/repo)\n    plugin remove     Remove an installed plugin\n    plugin list       List installed plugins\n    plugin search     Search the plugin registry\n    plugin validate   Validate a local plugin directory\n    plugin sync       Auto-detect and wire installed plugins\n    plugin export     Export plugin to Agent Skills spec format (skills.json)\n    plugin export     --codex: Export plugin to Codex-compatible TOML subagent files\n    plugin export-skills  Generate aggregated skills.json from all installed plugins\n    plugin export-skills global  Generate global skills.json from all globally installed plugins\n    plugin import     Import an Agent Skills spec package as a javi-forge plugin\n    skills doctor     Show skills health report (add --deep for conflict detection)\n    skills budget     Show token cost of loaded skills (add -b N for custom budget)\n    skills score      Score a skill on quality dimensions (completeness, clarity, testability, token-efficiency)\n    skills benchmark  Benchmark a skill with structural quality checks\n    skills auto       Auto-detect project stack and suggest/install matching AI skills\n    skills auto-install  Alias for skills auto\n    skill publish     Package a skill directory for marketplace distribution (generates plugin.json)\n    security baseline   Create security baseline from current audit findings\n    security check      Check for regressions against baseline (exits non-zero if found)\n    security update     Re-snapshot baseline (acknowledge current vulns)\n    security allowlist  Add all current findings to the allowlist (suppress in future checks)\n    llms-txt          Generate AI-friendly llms.txt for current project\n\n  Options\n    --dry-run       Preview changes without writing files\n    --stack         Project stack (node, python, go, rust, java-gradle, java-maven, elixir)\n    --ci            CI provider (github, gitlab, woodpecker)\n    --memory        Memory module (engram, obsidian-brain, memory-simple, none)\n    --project-name  Project name (skips name prompt)\n    --ghagga        Enable GHAGGA review system\n    --mock          Enable mock-first mode (no real API keys needed)\n    --local-ai      Include local AI dev stack (Ollama + Docker Compose)\n    --batch         Non-interactive mode (auto-proceed, no keyboard input)\n    --deep          Enable deep analysis (conflict + duplicate detection)\n    --budget, -b    Token budget limit for skills (default: 8000)\n    --skills-dir    Custom skills directory path\n    --author        Author name for skill publish\n    --repo          Repository URL for skill publish\n    --version       Show version\n    --help          Show this help\n\n  CI options (javi-forge ci)\n    --quick         Lint + compile only (fast, for pre-commit)\n    --shell         Open interactive shell in CI container\n    --detect        Show detected stack and exit\n    --config PATH   Load ordered CI runners from a versioned config file\n                    (default discovery: .javi-forge/ci.yaml)\n    --stack STACK   Force a single explicit stack (single-stack repos only \u2014\n                    insufficient for hybrid repos; use --config instead)\n    --no-docker     Run commands natively (no Docker)\n    --no-ci-ghagga  Skip GHAGGA review\n    --no-security   Skip Semgrep security scan\n    --timeout N     Per-step timeout in seconds (default: 600)\n\n  CI hooks (javi-forge ci init)\n    Install git hooks that call javi-forge ci.\n    No files copied \u2014 hooks reference the global CLI.\n    Existing hooks javi-forge did not write are refused, never clobbered.\n    --force         Overwrite a foreign or locally modified hook. The previous\n                    content is copied to a .bak sibling first; if that backup\n                    cannot be written, the hook is left untouched. Symlinked\n                    hook paths are refused even with --force.\n\n  Examples\n    $ javi-forge\n    $ javi-forge init --dry-run\n    $ javi-forge init --stack node --ci github\n    $ javi-forge ci\n    $ javi-forge ci init\n    $ javi-forge ci init --force\n    $ javi-forge tdd init\n    $ javi-forge ci --quick\n    $ javi-forge ci --no-ci-ghagga --no-security\n    $ javi-forge ci --no-docker\n    $ javi-forge ci --shell\n    $ javi-forge ci --config .javi-forge/ci.yaml\n    $ javi-forge ci validate\n    $ javi-forge ci --help\n    $ javi-forge analyze\n    $ javi-forge doctor\n    $ javi-forge plugin add mapbox/agent-skills\n    $ javi-forge plugin list\n";
+export declare const HELP_TEXT = "\n  Usage\n    $ javi-forge [command] [options]\n\n  Commands\n    init              Bootstrap a new project (default)\n    ci                Run CI simulation (lint + compile + test + security + ghagga)\n    ci validate       Validate .javi-forge/ci.yaml without running anything\n    ci init           Install git hooks that call javi-forge ci\n    tdd init          Enable the TDD pre-commit section + install managed hooks\n    tdd pipeline      Enable the TDD pre-push section (--mode strict|warn)\n    hooks run         Run a git hook's composed sections (pre-commit | pre-push)\n    analyze           Run repoforge skills analysis\n    doctor            Show health report\n    workflow show     Render a workflow graph as ASCII (--template <name> or file path)\n    workflow validate Validate project state against a workflow graph\n    workflow list     List available workflows and built-in templates\n    plugin add        Install a plugin from GitHub (org/repo)\n    plugin remove     Remove an installed plugin\n    plugin list       List installed plugins\n    plugin search     Search the plugin registry\n    plugin validate   Validate a local plugin directory\n    plugin sync       Auto-detect and wire installed plugins\n    plugin export     Export plugin to Agent Skills spec format (skills.json)\n    plugin export     --codex: Export plugin to Codex-compatible TOML subagent files\n    plugin export-skills  Generate aggregated skills.json from all installed plugins\n    plugin export-skills global  Generate global skills.json from all globally installed plugins\n    plugin import     Import an Agent Skills spec package as a javi-forge plugin\n    skills doctor     Show skills health report (add --deep for conflict detection)\n    skills budget     Show token cost of loaded skills (add -b N for custom budget)\n    skills score      Score a skill on quality dimensions (completeness, clarity, testability, token-efficiency)\n    skills benchmark  Benchmark a skill with structural quality checks\n    skills auto       Auto-detect project stack and suggest/install matching AI skills\n    skills auto-install  Alias for skills auto\n    skill publish     Package a skill directory for marketplace distribution (generates plugin.json)\n    security baseline   Create security baseline from current audit findings\n    security check      Check for regressions against baseline (exits non-zero if found)\n    security update     Re-snapshot baseline (acknowledge current vulns)\n    security allowlist  Add all current findings to the allowlist (suppress in future checks)\n    llms-txt          Generate AI-friendly llms.txt for current project\n\n  Options\n    --dry-run       Preview changes without writing files\n    --stack         Project stack (node, python, go, rust, java-gradle, java-maven, elixir)\n    --ci            CI provider (github, gitlab, woodpecker)\n    --memory        Memory module (engram, obsidian-brain, memory-simple, none)\n    --project-name  Project name (skips name prompt)\n    --ghagga        Enable GHAGGA review system\n    --mock          Enable mock-first mode (no real API keys needed)\n    --local-ai      Include local AI dev stack (Ollama + Docker Compose)\n    --batch         Non-interactive mode (auto-proceed, no keyboard input)\n    --deep          Enable deep analysis (conflict + duplicate detection)\n    --budget, -b    Token budget limit for skills (default: 8000)\n    --skills-dir    Custom skills directory path\n    --author        Author name for skill publish\n    --repo          Repository URL for skill publish\n    --version       Show version\n    --help          Show this help\n\n  CI options (javi-forge ci)\n    --quick         Lint + compile only (fast, for pre-commit)\n    --shell         Open interactive shell in CI container\n    --detect        Show detected stack and exit\n    --config PATH   Load ordered CI runners from a versioned config file\n                    (default discovery: .javi-forge/ci.yaml)\n    --stack STACK   Force a single explicit stack (single-stack repos only \u2014\n                    insufficient for hybrid repos; use --config instead)\n    --no-docker     Run commands natively (no Docker)\n    --no-ci-ghagga  Skip GHAGGA review\n    --no-security   Skip Semgrep security scan\n    --timeout N     Per-step timeout in seconds (default: 600)\n\n  CI hooks (javi-forge ci init)\n    Install git hooks that call javi-forge ci.\n    No files copied \u2014 hooks reference the global CLI.\n    Existing hooks javi-forge did not write are refused, never clobbered.\n    --force         Overwrite a foreign or locally modified hook. The previous\n                    content is copied to a .bak sibling first; if that backup\n                    cannot be written, the hook is left untouched. Symlinked\n                    hook paths are refused even with --force.\n\n  SkillGuard install gate (plugin add / plugin import / skills auto)\n    Every install is scanned before anything is written. Refusals are\n    fail-closed and name the offending files:\n    - SKILL.md files that block (critical threats) are refused \u2014 always.\n    - Unscannable files (binary, oversized, unreadable) are refused unless\n      --force is given.\n    - Symlinks anywhere in the tree and SKILL.md files outside the declared\n      set are manifest-integrity refusals \u2014 they are refused even with --force.\n    - Empty or missing skills.json `skills` array on import is refused.\n\n  Examples\n    $ javi-forge\n    $ javi-forge init --dry-run\n    $ javi-forge init --stack node --ci github\n    $ javi-forge ci\n    $ javi-forge ci init\n    $ javi-forge ci init --force\n    $ javi-forge plugin add org/repo\n    $ javi-forge plugin add org/repo --force\n    $ javi-forge tdd init\n    $ javi-forge ci --quick\n    $ javi-forge ci --no-ci-ghagga --no-security\n    $ javi-forge ci --no-docker\n    $ javi-forge ci --shell\n    $ javi-forge ci --config .javi-forge/ci.yaml\n    $ javi-forge ci validate\n    $ javi-forge ci --help\n    $ javi-forge analyze\n    $ javi-forge doctor\n    $ javi-forge plugin add mapbox/agent-skills\n    $ javi-forge plugin list\n";
 /**
  * Per-command help for `ci`, shown by `javi-forge ci --help` (or when `ci` is
  * given an unknown subcommand). Kept consistent with the global HELP_TEXT

package/dist/cli/help.js

@@ -89,6 +89,16 @@ export const HELP_TEXT = `
                     cannot be written, the hook is left untouched. Symlinked
                     hook paths are refused even with --force.
 
+  SkillGuard install gate (plugin add / plugin import / skills auto)
+    Every install is scanned before anything is written. Refusals are
+    fail-closed and name the offending files:
+    - SKILL.md files that block (critical threats) are refused — always.
+    - Unscannable files (binary, oversized, unreadable) are refused unless
+      --force is given.
+    - Symlinks anywhere in the tree and SKILL.md files outside the declared
+      set are manifest-integrity refusals — they are refused even with --force.
+    - Empty or missing skills.json \`skills\` array on import is refused.
+
   Examples
     $ javi-forge
     $ javi-forge init --dry-run
@@ -96,6 +106,8 @@ export const HELP_TEXT = `
     $ javi-forge ci
     $ javi-forge ci init
     $ javi-forge ci init --force
+    $ javi-forge plugin add org/repo
+    $ javi-forge plugin add org/repo --force
     $ javi-forge tdd init
     $ javi-forge ci --quick
     $ javi-forge ci --no-ci-ghagga --no-security

package/dist/commands/ci.js

@@ -487,7 +487,11 @@ export async function runCI(options, onStep, onGateOutcome) {
     try {
         const ctxResult = await refreshContextDir(projectDir);
         if (ctxResult) {
-            report(onStep, stepContext, "Refresh .context/ directory", "done", "INDEX.md + summary.md updated");
+            // An unreadable manifest is reported, not silently treated as no deps.
+            const detail = ctxResult.warnings.length > 0
+                ? `INDEX.md + summary.md updated (manifest warnings: ${ctxResult.warnings.join("; ")})`
+                : "INDEX.md + summary.md updated";
+            report(onStep, stepContext, "Refresh .context/ directory", "done", detail);
         }
         else {
             report(onStep, stepContext, "Refresh .context/ directory", "skipped", "no .context/ or no manifest");

package/dist/commands/doctor.js

@@ -319,6 +319,15 @@ export async function runDoctor(projectDir) {
                 status: "ok",
                 detail: "INDEX.md + summary.md updated",
             });
+            // A manifest that could not be read is not "no dependencies" — surface
+            // each warning so an unreadable/oversized/invalid manifest is visible.
+            for (const warning of result.warnings) {
+                contextChecks.push({
+                    label: "dependency manifest",
+                    status: "fail",
+                    detail: warning,
+                });
+            }
         }
         else {
             contextChecks.push({

package/dist/commands/init/steps/ghagga.d.ts

@@ -1,15 +1,14 @@
 import type { StepFn } from "../types.js";
 /**
- * Step 9: Install GHAGGA review system.
+ * Step 9: Install the local GHAGGA review module.
  *
  * - When ghagga is false, reports "skipped".
  * - Copies <MODULES_DIR>/ghagga → <project>/.javi-forge/modules/ghagga (no overwrite).
- * - For GitHub provider, also copies the ghagga-review.yml caller workflow into
- *   <project>/.github/workflows/.
  * - If module source dir is missing, reports "error" with "module not found".
  * - Errors are swallowed and reported as status:"error" — never thrown.
  *
- * Extracted VERBATIM from src/commands/init.ts (PR 3 of 6).
+ * The GitHub Action review workflow is intentionally NOT scaffolded — ghagga
+ * runs locally/self-hosted, not as a GitHub Action.
  */
 export declare const stepGhagga: StepFn;
 //# sourceMappingURL=ghagga.d.ts.map

package/dist/commands/init/steps/ghagga.js

@@ -1,23 +1,22 @@
 import path from "node:path";
 import fs from "fs-extra";
-import { FORGE_ROOT, MODULES_DIR } from "../../../constants.js";
+import { MODULES_DIR } from "../../../constants.js";
 import { ensureDirExists } from "../../../lib/common.js";
 import { report } from "../report.js";
 /**
- * Step 9: Install GHAGGA review system.
+ * Step 9: Install the local GHAGGA review module.
  *
  * - When ghagga is false, reports "skipped".
  * - Copies <MODULES_DIR>/ghagga → <project>/.javi-forge/modules/ghagga (no overwrite).
- * - For GitHub provider, also copies the ghagga-review.yml caller workflow into
- *   <project>/.github/workflows/.
  * - If module source dir is missing, reports "error" with "module not found".
  * - Errors are swallowed and reported as status:"error" — never thrown.
  *
- * Extracted VERBATIM from src/commands/init.ts (PR 3 of 6).
+ * The GitHub Action review workflow is intentionally NOT scaffolded — ghagga
+ * runs locally/self-hosted, not as a GitHub Action.
  */
 export const stepGhagga = async (ctx) => {
     const { projectDir, dryRun, onStep, options } = ctx;
-    const { ghagga, ciProvider } = options;
+    const { ghagga } = options;
     const stepId = "ghagga";
     report(onStep, stepId, "Install GHAGGA review system", "running");
     try {
@@ -31,15 +30,6 @@ export const stepGhagga = async (ctx) => {
                         overwrite: false,
                         errorOnExist: false,
                     });
-                    // Copy ghagga caller workflow to CI provider location
-                    if (ciProvider === "github") {
-                        const workflowSrc = path.join(FORGE_ROOT, "templates", "github", "ghagga-review.yml");
-                        if (await fs.pathExists(workflowSrc)) {
-                            const workflowDest = path.join(projectDir, ".github", "workflows", "ghagga-review.yml");
-                            await ensureDirExists(path.dirname(workflowDest));
-                            await fs.copy(workflowSrc, workflowDest, { overwrite: false });
-                        }
-                    }
                 }
                 report(onStep, stepId, "Install GHAGGA review system", "done");
             }

package/dist/commands/plugin.d.ts

@@ -3,7 +3,9 @@ type StepCallback = (step: InitStep) => void;
 /**
  * Add (install) a plugin from a GitHub source.
  */
-export declare function runPluginAdd(source: string, dryRun: boolean, onStep: StepCallback): Promise<void>;
+export declare function runPluginAdd(source: string, dryRun: boolean, onStep: StepCallback, options?: {
+    force?: boolean;
+}): Promise<void>;
 /**
  * Remove an installed plugin by name.
  */
@@ -35,7 +37,7 @@ export declare function runPluginExportCodex(name: string, onStep: StepCallback)
 /**
  * Import an Agent Skills spec package and convert to javi-forge plugin format.
  */
-export declare function runPluginImport(sourceDir: string, dryRun: boolean, onStep: StepCallback): Promise<void>;
+export declare function runPluginImport(sourceDir: string, dryRun: boolean, onStep: StepCallback, force?: boolean): Promise<void>;
 /**
  * Generate a project-level skills.json from all installed plugins.
  * Makes the project discoverable by `npx skills add` and 40+ AI agents.

package/dist/commands/plugin.js

@@ -7,10 +7,10 @@ function report(onStep, id, label, status, detail) {
 /**
  * Add (install) a plugin from a GitHub source.
  */
-export async function runPluginAdd(source, dryRun, onStep) {
+export async function runPluginAdd(source, dryRun, onStep, options = {}) {
     const stepId = "plugin-add";
     report(onStep, stepId, `Install plugin: ${source}`, "running");
-    const result = await installPlugin(source, { dryRun });
+    const result = await installPlugin(source, { dryRun, force: options.force });
     if (result.success) {
         report(onStep, stepId, `Install plugin: ${source}`, "done", dryRun
             ? `dry-run: would install ${result.name}`
@@ -145,10 +145,10 @@ export async function runPluginExportCodex(name, onStep) {
 /**
  * Import an Agent Skills spec package and convert to javi-forge plugin format.
  */
-export async function runPluginImport(sourceDir, dryRun, onStep) {
+export async function runPluginImport(sourceDir, dryRun, onStep, force = false) {
     const stepId = "plugin-import";
     report(onStep, stepId, `Import agent-skills package: ${sourceDir}`, "running");
-    const result = await importAgentSkillsPackage(sourceDir, { dryRun });
+    const result = await importAgentSkillsPackage(sourceDir, { dryRun, force });
     if (result.success) {
         report(onStep, stepId, `Import agent-skills package: ${sourceDir}`, "done", dryRun
             ? `dry-run: would import ${result.name}`

package/dist/commands/skills/analysis.js

@@ -1,4 +1,5 @@
-import { CONTRADICTION_PAIRS, DEFAULT_BUDGET } from "./constants.js";
+import fs from "fs-extra";
+import { CHARS_PER_TOKEN, CONTRADICTION_PAIRS, DEFAULT_BUDGET, } from "./constants.js";
 import { detectDirectiveClash } from "./directives.js";
 import { discoverSkills, estimateTokens, parseSkillFile } from "./parsing.js";
 // ── Budget Optimization ─────────────────────────────────────────────────────
@@ -98,6 +99,12 @@ export async function findConflicts(skillsDir) {
         const parsed = await parseSkillFile(sp);
         if (!parsed)
             continue;
+        // A skipped file has no readable rules to compare. Don't treat its empty
+        // rule list as "no conflicts" — it is surfaced as a skip in the budget
+        // section (calculateBudget always runs alongside conflict detection), so
+        // skip it here explicitly rather than letting it pass silently.
+        if (parsed.skip)
+            continue;
         for (const rule of parsed.rules) {
             allRules.push({
                 skillName: parsed.name,
@@ -138,10 +145,32 @@ export async function calculateBudget(skillsDir, budget = DEFAULT_BUDGET) {
         const parsed = await parseSkillFile(sp);
         if (!parsed)
             continue;
+        // Token count reflects the bytes actually kept by the guarded read, so a
+        // skipped or truncated skill is reported rather than counted as normal.
+        const note = parsed.skip
+            ? `skipped: ${parsed.skip.message}`
+            : parsed.truncated
+                ? "truncated: read budget reached"
+                : undefined;
+        // A skipped skill has empty `rawContent`, so token estimation from it would
+        // be 0 and the file would sort last — the budget tool would hide the very
+        // oversized file it exists to flag. Fall back to the real on-disk byte size
+        // so an unread skill still counts toward the total and over-budget check.
+        let tokens = estimateTokens(parsed.rawContent);
+        if (parsed.skip) {
+            try {
+                const { size } = await fs.stat(sp);
+                tokens = Math.ceil(size / CHARS_PER_TOKEN);
+            }
+            catch {
+                // Vanished between discovery and stat — leave 0; the note still flags it.
+            }
+        }
         entries.push({
             skillName: parsed.name,
             skillPath: sp,
-            tokens: estimateTokens(parsed.rawContent),
+            tokens,
+            ...(note ? { note } : {}),
         });
     }
     // Sort by token count descending (biggest consumers first)

package/dist/commands/skills/benchmark.js

@@ -9,6 +9,16 @@ export async function benchmarkSkill(skillPath) {
     const parsed = await parseSkillFile(skillPath);
     if (!parsed)
         return null;
+    // A file that could not be read has no structure to benchmark. Reporting it
+    // as a skill that failed every check is misleading — mark it unread instead.
+    if (parsed.skip) {
+        return {
+            skillName: parsed.name,
+            checks: [],
+            passRate: 0,
+            unread: parsed.skip.message,
+        };
+    }
     const checks = [];
     // Check 1: Has YAML frontmatter with name
     checks.push({

package/dist/commands/skills/constants.d.ts

@@ -6,5 +6,10 @@ export declare const CHARS_PER_TOKEN = 4;
 export declare const DEFAULT_THRESHOLD = 50;
 /** Default registry quality threshold */
 export declare const DEFAULT_REGISTRY_THRESHOLD = 60;
+/**
+ * Hard ceiling for a SKILL.md. A skill file past this is not a skill — it is a
+ * dumped log or a vendored bundle — so it is skipped instead of truncated.
+ */
+export declare const MAX_SKILL_BYTES: number;
 export declare const CONTRADICTION_PAIRS: [RegExp, RegExp][];
 //# sourceMappingURL=constants.d.ts.map

package/dist/commands/skills/constants.js

@@ -8,6 +8,11 @@ export const CHARS_PER_TOKEN = 4;
 export const DEFAULT_THRESHOLD = 50;
 /** Default registry quality threshold */
 export const DEFAULT_REGISTRY_THRESHOLD = 60;
+/**
+ * Hard ceiling for a SKILL.md. A skill file past this is not a skill — it is a
+ * dumped log or a vendored bundle — so it is skipped instead of truncated.
+ */
+export const MAX_SKILL_BYTES = 1024 * 1024;
 // ── Contradiction keywords (pairs that signal opposite intent) ───────────────
 export const CONTRADICTION_PAIRS = [
     [/\buse semicolons\b/i, /\bno semicolons\b/i],

package/dist/commands/skills/parsing.d.ts

@@ -1,12 +1,27 @@
+import { type SafeReadFailureReason } from "../../lib/safe-read.js";
 /** Estimate token count from a string */
 export declare function estimateTokens(text: string): number;
-/** Read a SKILL.md and extract its name + critical rules section */
-export declare function parseSkillFile(skillPath: string): Promise<{
+/** Why a SKILL.md could not be analysed — reportable, never thrown */
+export interface SkillReadSkip {
+    reason: SafeReadFailureReason;
+    message: string;
+}
+export interface ParsedSkillFile {
     name: string;
     rules: string[];
     rawContent: string;
     triggers: string[];
-} | null>;
+    /**
+     * Non-null when the file could not be read as analysable text (binary,
+     * oversized, permission denied). `rawContent` is empty in that case, so
+     * callers can report the skip instead of scoring an empty skill.
+     */
+    skip: SkillReadSkip | null;
+    /** True when the file was longer than the read budget and got cut short. */
+    truncated: boolean;
+}
+/** Read a SKILL.md and extract its name + critical rules section */
+export declare function parseSkillFile(skillPath: string): Promise<ParsedSkillFile | null>;
 /** Extract critical rules from markdown content */
 export declare function extractCriticalRules(content: string): string[];
 /** Extract trigger keywords from a skill description */

package/dist/commands/skills/parsing.js

@@ -1,7 +1,8 @@
 import path from "node:path";
 import fs from "fs-extra";
 import { parseFrontmatter } from "../../lib/frontmatter.js";
-import { CHARS_PER_TOKEN } from "./constants.js";
+import { describeSafeReadFailure, safeReadFile, } from "../../lib/safe-read.js";
+import { CHARS_PER_TOKEN, MAX_SKILL_BYTES } from "./constants.js";
 // ── Helpers ──────────────────────────────────────────────────────────────────
 /** Estimate token count from a string */
 export function estimateTokens(text) {
@@ -11,7 +12,24 @@ export function estimateTokens(text) {
 export async function parseSkillFile(skillPath) {
     if (!(await fs.pathExists(skillPath)))
         return null;
-    const raw = await fs.readFile(skillPath, "utf-8");
+    const read = await safeReadFile(skillPath, {
+        hardRejectOverBytes: MAX_SKILL_BYTES,
+    });
+    if (!read.ok) {
+        // A path that vanished between the existence check and the read is the
+        // same "no such skill" case the caller already handles with null.
+        if (read.reason === "not-found" || read.reason === "not-a-file")
+            return null;
+        return {
+            name: path.basename(path.dirname(skillPath)),
+            rules: [],
+            rawContent: "",
+            triggers: [],
+            skip: { reason: read.reason, message: describeSafeReadFailure(read) },
+            truncated: false,
+        };
+    }
+    const raw = read.content;
     const fm = parseFrontmatter(raw);
     const rawName = fm?.data?.name;
     const name = typeof rawName === "string"
@@ -23,7 +41,15 @@ export async function parseSkillFile(skillPath) {
     const rawDesc = fm?.data?.description;
     const description = typeof rawDesc === "string" ? rawDesc : "";
     const triggers = extractTriggers(description);
-    return { name, rules, rawContent: raw, triggers };
+    // rawContent is the kept text, so token estimates reflect what was analysed.
+    return {
+        name,
+        rules,
+        rawContent: raw,
+        triggers,
+        skip: null,
+        truncated: read.truncated,
+    };
 }
 /** Extract critical rules from markdown content */
 export function extractCriticalRules(content) {

package/dist/commands/skills/scoring.d.ts

@@ -1,10 +1,11 @@
 import type { SkillGrade, SkillRegistryGateResult, SkillScore } from "../../types/index.js";
-type ParsedSkill = {
-    name: string;
-    rules: string[];
-    rawContent: string;
-    triggers: string[];
-};
+import { type ParsedSkillFile } from "./parsing.js";
+/**
+ * The fields the dimension scorers read. Derived from `ParsedSkillFile` with
+ * `Pick` (not a hand-copied shape) so the `skip` field can never be silently
+ * dropped: a skipped parse is caught in `scoreSkill` before it reaches a scorer.
+ */
+type ParsedSkill = Pick<ParsedSkillFile, "name" | "rules" | "rawContent" | "triggers">;
 /**
  * Score completeness (0-100): frontmatter fields, critical rules, structure.
  */

package/dist/commands/skills/scoring.js

@@ -1,5 +1,5 @@
 import { DEFAULT_REGISTRY_THRESHOLD, DEFAULT_THRESHOLD } from "./constants.js";
-import { estimateTokens, parseSkillFile } from "./parsing.js";
+import { estimateTokens, parseSkillFile, } from "./parsing.js";
 import { ACTION_VERBS, VAGUE_TERMS } from "./rules.js";
 // ── Dangerous content patterns (private to scoreSafety) ─────────────────────
 /** Dangerous patterns in skill content that indicate safety risks */
@@ -243,6 +243,26 @@ export async function scoreSkill(skillPath, threshold = DEFAULT_THRESHOLD) {
     const parsed = await parseSkillFile(skillPath);
     if (!parsed)
         return null;
+    // A file that could not be read is NOT a zero-content skill. Scoring it would
+    // invent a grade over an empty string — worse, `scoreSafety` starts at 100
+    // and finds no dangerous patterns in nothing, so an unreadable file would
+    // report perfect safety. Represent it as unread and fail closed instead.
+    if (parsed.skip) {
+        return {
+            skillName: parsed.name,
+            completeness: 0,
+            clarity: 0,
+            testability: 0,
+            tokenEfficiency: 0,
+            safety: 0,
+            agentReadiness: 0,
+            overall: 0,
+            grade: "F",
+            threshold,
+            passing: false,
+            unread: parsed.skip.message,
+        };
+    }
     const completeness = scoreCompleteness(parsed);
     const clarity = scoreClarity(parsed);
     const testability = scoreTestability(parsed);
@@ -279,6 +299,16 @@ export async function registryGate(skillPath, threshold = DEFAULT_REGISTRY_THRES
     const score = await scoreSkill(skillPath, threshold);
     if (!score)
         return null;
+    // An unread skill can never be accepted into the registry: it was not scored,
+    // so it cannot clear any threshold. Reject it with an explicit reason.
+    if (score.unread) {
+        return {
+            skillName: score.skillName,
+            score,
+            accepted: false,
+            reason: `Rejected: could not read skill (${score.unread}) — not scored`,
+        };
+    }
     const accepted = score.passing;
     let reason;
     if (!accepted) {

package/dist/lib/agent-skills.d.ts

@@ -30,6 +30,7 @@ export declare function exportPluginAsAgentSkills(name: string): Promise<{
  */
 export declare function importAgentSkillsPackage(sourceDir: string, options?: {
     dryRun?: boolean;
+    force?: boolean;
 }): Promise<{
     success: boolean;
     name?: string;