javi-forge 1.27.0 → 1.28.1

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

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    A refused install/auto-install exits non-zero (exit 1) so scripts and CI\n    can tell a refusal apart from success; clean installs \u2014 including\n    --force-lifted unscannable ones \u2014 exit 0.\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,19 @@ 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.
+    A refused install/auto-install exits non-zero (exit 1) so scripts and CI
+    can tell a refusal apart from success; clean installs — including
+    --force-lifted unscannable ones — exit 0.
+
   Examples
     $ javi-forge
     $ javi-forge init --dry-run
@@ -96,6 +109,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/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,9 @@ 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, options?: {
+    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}`
@@ -18,6 +18,12 @@ export async function runPluginAdd(source, dryRun, onStep) {
     }
     else {
         report(onStep, stepId, `Install plugin: ${source}`, "error", result.error);
+        // FU-1 (R4-002): a skillguard refusal must be distinguishable from
+        // success by scripted consumers — exit non-zero. `process.exitCode`
+        // (not `process.exit`) so the Ink tree keeps rendering/unmounting
+        // normally. Non-gate failures (validation, clone errors) keep exit 0.
+        if (result.refused)
+            process.exitCode = 1;
     }
 }
 /**
@@ -145,10 +151,13 @@ 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, options = {}) {
     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: options.force,
+    });
     if (result.success) {
         report(onStep, stepId, `Import agent-skills package: ${sourceDir}`, "done", dryRun
             ? `dry-run: would import ${result.name}`
@@ -156,6 +165,11 @@ export async function runPluginImport(sourceDir, dryRun, onStep) {
     }
     else {
         report(onStep, stepId, `Import agent-skills package: ${sourceDir}`, "error", result.error);
+        // FU-1 (R4-002): same exit-code contract as runPluginAdd — a skillguard
+        // refusal (manifest-integrity or verdict) exits non-zero; plain input
+        // errors (skills.json missing/invalid) keep exit 0.
+        if (result.refused)
+            process.exitCode = 1;
     }
 }
 /**

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

@@ -30,10 +30,19 @@ export declare function exportPluginAsAgentSkills(name: string): Promise<{
  */
 export declare function importAgentSkillsPackage(sourceDir: string, options?: {
     dryRun?: boolean;
+    force?: boolean;
 }): Promise<{
     success: boolean;
     name?: string;
     error?: string;
+    /**
+     * FU-1 (R4-002): true when the failure is a skillguard gate refusal
+     * (manifest-integrity — invalid name, empty/missing skills, containment
+     * escape, walk errors/symlinks/undeclared — or verdict refusal, incl. a
+     * scanner-error deny). The CLI layer turns this into a non-zero exit
+     * code. Plain input errors (skills.json missing/invalid) leave it unset.
+     */
+    refused?: boolean;
 }>;
 /**
  * Aggregate multiple installed plugins into a single Agent Skills spec manifest.

package/dist/lib/agent-skills.js

@@ -1,6 +1,8 @@
 import path from "node:path";
 import fs from "fs-extra";
 import { AGENT_SKILLS_MANIFEST_FILE, PLUGIN_MANIFEST_FILE, PLUGINS_DIR, } from "../constants.js";
+import { evaluateCoverageGate, scanFailureMessage, } from "./skill-install-gate.js";
+import { checkPathContained, scanSkillsWithCoverage } from "./skill-scanner.js";
 // ── Conversion ─────────────────────────────────────────────────────────────
 /**
  * Convert a javi-forge PluginManifest to an Agent Skills spec manifest.
@@ -68,7 +70,7 @@ export async function exportPluginAsAgentSkills(name) {
  * Reads skills.json, converts to plugin.json, copies to plugins dir.
  */
 export async function importAgentSkillsPackage(sourceDir, options = {}) {
-    const { dryRun = false } = options;
+    const { dryRun = false, force = false } = options;
     const skillsPath = path.join(sourceDir, AGENT_SKILLS_MANIFEST_FILE);
     if (!(await fs.pathExists(skillsPath))) {
         return { success: false, error: "skills.json not found" };
@@ -88,11 +90,112 @@ export async function importAgentSkillsPackage(sourceDir, options = {}) {
             error: "skills.json missing required fields (name, version, description)",
         };
     }
+    // R1-002: `name` becomes the import destination (`destDir = path.join(
+    // PLUGINS_DIR, name)`) and is handed to `fs.remove` + `fs.copy` below with
+    // NO path validation — a hostile skills.json name (e.g. `"../../.bashrc"`,
+    // an absolute path, or a separator-bearing name) would delete/copy
+    // ARBITRARY paths outside PLUGINS_DIR. The gate validates declared
+    // `skills[].path` escapes but never the name that determines the
+    // write/delete destination. Same-trust note: `name` is attacker-influenced
+    // when installing from a registry package, not a typed-in label — refuse
+    // BEFORE any `fs.remove`/`fs.copy`/`destDir` use, so an existing install
+    // is preserved (style-consistent with the gate's manifest-integrity
+    // refusals, block-level, force never lifts).
     const pluginName = agentManifest.name;
+    // R1-F2-N2: `name` is attacker-influenced JSON — it need not be a string at
+    // all (`{"name": 123}` is truthy, so it sails past the required-fields
+    // check above). Guard the type BEFORE the `.trim()` check: a non-string
+    // name refuses cleanly with the same manifest-integrity message instead of
+    // throwing a TypeError out of `.trim()` (which propagated to the UI as a
+    // "Fatal error").
+    if (typeof pluginName !== "string") {
+        return {
+            success: false,
+            refused: true,
+            error: `skillguard: install refused — invalid manifest name "${pluginName}" (manifest-integrity, force never lifts)`,
+        };
+    }
+    if (pluginName.trim() === "" ||
+        pluginName === "." ||
+        pluginName.includes("..") ||
+        pluginName.includes("/") ||
+        pluginName.includes("\\") ||
+        path.isAbsolute(pluginName)) {
+        return {
+            success: false,
+            refused: true,
+            error: `skillguard: install refused — invalid manifest name "${pluginName}" (manifest-integrity, force never lifts)`,
+        };
+    }
+    // JD-006: import requires a non-empty, well-formed skills array. Each entry
+    // must carry a `name` and a `path` that resolves INSIDE sourceDir (normalized
+    // + realpath containment — "../../x" or an absolute path refuses; the gate
+    // never reads outside the staged clone, JD-003).
+    if (!Array.isArray(agentManifest.skills) ||
+        agentManifest.skills.length === 0) {
+        return {
+            success: false,
+            refused: true,
+            error: "skills.json must declare a non-empty skills array (every skill-shaped file must be declared)",
+        };
+    }
+    const sourceRootAbs = path.resolve(sourceDir);
+    const sourceRootReal = await fs.realpath(sourceRootAbs);
+    const declaredPaths = [];
+    for (const entry of agentManifest.skills) {
+        if (!entry || typeof entry.name !== "string" || !entry.name) {
+            return {
+                success: false,
+                refused: true,
+                error: "skills.json skills entry missing name",
+            };
+        }
+        if (typeof entry.path !== "string" || !entry.path) {
+            return {
+                success: false,
+                refused: true,
+                error: `skills.json skills entry "${entry.name}" missing path`,
+            };
+        }
+        const contained = await skillPathContained(sourceRootAbs, sourceRootReal, entry.path);
+        if (!contained.ok) {
+            return {
+                success: false,
+                refused: true,
+                error: `skills.json skills entry "${entry.name}" path escapes package root (${contained.reason}) — refusing`,
+            };
+        }
+        declaredPaths.push(entry.path);
+    }
     if (dryRun) {
         return { success: true, name: pluginName };
     }
     const destDir = path.join(PLUGINS_DIR, pluginName);
+    // ── SkillGuard runtime gate (D8, JD-001/JD-003/JD-006/JD-007) ──────────
+    // Runs BEFORE the existing-install remove and fs.copy: a refusal preserves
+    // an existing install and installs nothing. dryRun early-returns above, so
+    // no scan happens on dry-run. Scanner/eval errors deny unconditionally (D7).
+    // The refusal policy + message-building is shared with plugin add via
+    // evaluateCoverageGate (R2-001).
+    let coverage;
+    try {
+        coverage = await scanSkillsWithCoverage(sourceDir, declaredPaths);
+    }
+    catch (scanError) {
+        return {
+            success: false,
+            refused: true,
+            error: scanFailureMessage(scanError),
+        };
+    }
+    const decision = evaluateCoverageGate(coverage, { force });
+    if (decision.refusalError) {
+        return {
+            success: false,
+            refused: true,
+            error: decision.refusalError,
+        };
+    }
     // Remove existing version if present
     if (await fs.pathExists(destDir)) {
         await fs.remove(destDir);
@@ -117,6 +220,24 @@ export async function importAgentSkillsPackage(sourceDir, options = {}) {
     });
     return { success: true, name: pluginName };
 }
+/**
+ * Verify a declared skill entry path stays inside the package root — both
+ * lexically (`../../x`, absolute paths) and by realpath, so an in-tree symlink
+ * cannot redirect the import read outside the staged clone (JD-003/JD-006).
+ * Non-throwing `{ ok, reason }` surface over the shared containment core
+ * (`checkPathContained`, R2-002) — the import gate refuses gracefully instead
+ * of throwing.
+ */
+async function skillPathContained(rootAbs, rootReal, entryPath) {
+    const check = await checkPathContained(rootAbs, rootReal, entryPath);
+    if (!check.ok) {
+        return {
+            ok: false,
+            reason: `path "${entryPath}" resolves outside the package root${check.violation === "realpath" ? " (realpath)" : ""}`,
+        };
+    }
+    return { ok: true };
+}
 // ── Aggregation ──────────────────────────────────────────────────────────
 /**
  * Aggregate multiple installed plugins into a single Agent Skills spec manifest.

package/dist/lib/auto-skill-install.d.ts

@@ -1,3 +1,4 @@
+import type { SkillScanResult } from "./skill-scanner.js";
 import type { StackDetectionResult } from "./stack-detector.js";
 export interface SkillInstallResult {
     /** Skills that were successfully installed (copied) */
@@ -6,6 +7,8 @@ export interface SkillInstallResult {
     skipped: string[];
     /** Skills that were recommended but not found in the source */
     notFound: string[];
+    /** Skills refused by the skillguard gate (block / unscannable w/o force) */
+    blocked: SkillScanResult[];
     /** The full detection result for reporting */
     detection: StackDetectionResult;
 }
@@ -18,6 +21,8 @@ export interface AutoInstallOptions {
     skillsTargetDir?: string;
     /** If true, skip actually copying files */
     dryRun?: boolean;
+    /** Bypass the gate for unscannable sources ONLY — block always refuses (D2) */
+    force?: boolean;
 }
 /**
  * Scan a project, detect its stack, and install matching AI skills.

package/dist/lib/auto-skill-install.js

@@ -1,6 +1,8 @@
 import path from "node:path";
 import fs from "fs-extra";
 import { DEFAULT_SKILLS_DIR } from "../commands/skills/constants.js";
+import { evaluateInstallGate } from "./skill-install-gate.js";
+import { scanSkillFile } from "./skill-scanner.js";
 import { detectProjectStack } from "./stack-detector.js";
 // ── Core ───────────────────────────────────────────────────────────────────
 /**
@@ -14,7 +16,7 @@ import { detectProjectStack } from "./stack-detector.js";
  * source to target (useful for project-local skill installation).
  */
 export async function autoInstallSkills(options) {
-    const { projectDir, skillsSourceDir = DEFAULT_SKILLS_DIR, skillsTargetDir = DEFAULT_SKILLS_DIR, dryRun = false, } = options;
+    const { projectDir, skillsSourceDir = DEFAULT_SKILLS_DIR, skillsTargetDir = DEFAULT_SKILLS_DIR, dryRun = false, force = false, } = options;
     // 1. Detect project stack
     const detection = await detectProjectStack(projectDir);
     if (detection.recommendedSkills.length === 0) {
@@ -22,6 +24,7 @@ export async function autoInstallSkills(options) {
             installed: [],
             skipped: [],
             notFound: [],
+            blocked: [],
             detection,
         };
     }
@@ -29,6 +32,10 @@ export async function autoInstallSkills(options) {
     const skipped = [];
     const notFound = [];
     const sameDir = path.resolve(skillsSourceDir) === path.resolve(skillsTargetDir);
+    // 2. Classify: notFound / sameDir-skipped / target-skipped / copyable.
+    // Predicates unchanged from pre-gate behavior; sameDir short-circuits
+    // BEFORE any scanning (D4).
+    const copyable = [];
     for (const skillName of detection.recommendedSkills) {
         const sourcePath = path.join(skillsSourceDir, skillName);
         const targetPath = path.join(skillsTargetDir, skillName);
@@ -49,6 +56,32 @@ export async function autoInstallSkills(options) {
             skipped.push(skillName);
             continue;
         }
+        copyable.push(skillName);
+    }
+    // 3. SkillGuard gate (D4, JD-009): scan-gate every copyable source via its
+    // folder-root SKILL.md. dryRun still scans (read-only) but copies nothing.
+    // A scan THROW rejects the whole function — nothing copied, matching the
+    // UI error path (AutoSkills.tsx:41-44).
+    const scans = [];
+    for (const skillName of copyable) {
+        const sourceSkillMd = path.join(skillsSourceDir, skillName, "SKILL.md");
+        scans.push(await scanSkillFile(sourceSkillMd));
+    }
+    const gate = evaluateInstallGate(scans, { force });
+    if (!gate.allowed) {
+        // Any block (or unscannable without force) ⇒ copy NOTHING.
+        return {
+            installed: [],
+            skipped,
+            notFound,
+            blocked: gate.rejected,
+            detection,
+        };
+    }
+    // 4. Copy every copyable skill — nothing was refused.
+    for (const skillName of copyable) {
+        const sourcePath = path.join(skillsSourceDir, skillName);
+        const targetPath = path.join(skillsTargetDir, skillName);
         // Copy skill to target
         if (!dryRun) {
             await fs.ensureDir(targetPath);
@@ -59,7 +92,7 @@ export async function autoInstallSkills(options) {
         }
         installed.push(skillName);
     }
-    return { installed, skipped, notFound, detection };
+    return { installed, skipped, notFound, blocked: [], detection };
 }
 /**
  * Get a human-readable summary of auto-install results.
@@ -86,6 +119,11 @@ export function formatAutoInstallSummary(result) {
     if (result.notFound.length > 0) {
         lines.push(`  Not found: ${result.notFound.join(", ")}`);
     }
+    if (result.blocked.length > 0) {
+        lines.push(`  Blocked: ${result.blocked
+            .map((b) => `${b.skillName} [${b.verdict.toUpperCase()}]`)
+            .join(", ")}`);
+    }
     return lines.join("\n");
 }
 //# sourceMappingURL=auto-skill-install.js.map

package/dist/lib/plugin.d.ts

@@ -9,10 +9,19 @@ export declare function validatePlugin(pluginDir: string): Promise<PluginValidat
  */
 export declare function installPlugin(source: string, options?: {
     dryRun?: boolean;
+    force?: boolean;
 }): Promise<{
     success: boolean;
     name?: string;
     error?: string;
+    /**
+     * FU-1 (R4-002): true when the failure is a skillguard gate refusal
+     * (manifest-integrity or verdict refusal, incl. a scanner-error deny).
+     * The CLI layer turns this into a non-zero exit code so scripted
+     * consumers can tell a refusal apart from success. Plain usage errors
+     * (invalid source, validation failed) leave it unset.
+     */
+    refused?: boolean;
 }>;
 /**
  * Remove an installed plugin by name.

package/dist/lib/plugin.js

@@ -4,6 +4,8 @@ import { PLUGIN_ASSET_DIRS, PLUGIN_MANIFEST_FILE, PLUGIN_REGISTRY_URL, PLUGINS_D
 import { generateAgentSkillsManifest } from "./agent-skills.js";
 import { autoWirePlugins } from "./auto-wire.js";
 import { execFileAsync } from "./exec.js";
+import { evaluateCoverageGate, scanFailureMessage, } from "./skill-install-gate.js";
+import { scanSkillsWithCoverage } from "./skill-scanner.js";
 const KEBAB_RE = /^[a-z0-9]+(-[a-z0-9]+)*$/;
 const SEMVER_RE = /^\d+\.\d+\.\d+$/;
 // ── Validation ──────────────────────────────────────────────────────────────
@@ -112,7 +114,7 @@ export async function validatePlugin(pluginDir) {
  * Clones the repo to a temp dir, validates, then copies to plugins dir.
  */
 export async function installPlugin(source, options = {}) {
-    const { dryRun = false } = options;
+    const { dryRun = false, force = false } = options;
     // Normalize source to a git URL
     const gitUrl = normalizeGitUrl(source);
     if (!gitUrl) {
@@ -151,6 +153,34 @@ export async function installPlugin(source, options = {}) {
         const pluginName = validation.manifest.name;
         const destDir = path.join(PLUGINS_DIR, pluginName);
         if (!dryRun) {
+            // ── SkillGuard runtime gate (D1/D3, JD-006/JD-007) ────────────
+            // Runs BEFORE the existing-install remove and fs.move: a refusal
+            // leaves staging intact (removed by `finally`) and never destroys a
+            // prior install. dryRun skips the gate entirely (no staged clone).
+            // Scanner/eval errors deny unconditionally (D7 — a throw is not a
+            // verdict, so no force branch consults it). The refusal policy +
+            // message-building is shared with plugin import via
+            // evaluateCoverageGate (R2-001).
+            let coverage;
+            try {
+                const declaredPaths = (validation.manifest.skills ?? []).map((skill) => path.join("skills", skill));
+                coverage = await scanSkillsWithCoverage(tmpDir, declaredPaths);
+            }
+            catch (scanError) {
+                return {
+                    success: false,
+                    refused: true,
+                    error: scanFailureMessage(scanError),
+                };
+            }
+            const decision = evaluateCoverageGate(coverage, { force });
+            if (decision.refusalError) {
+                return {
+                    success: false,
+                    refused: true,
+                    error: decision.refusalError,
+                };
+            }
             // Remove existing version if present
             if (await fs.pathExists(destDir)) {
                 await fs.remove(destDir);

package/dist/lib/skill-install-gate.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Shared install-gate evaluation for the skillguard runtime gate (D2).
+ *
+ * Pure helpers: verdict evaluation ({@link evaluateInstallGate}) and the
+ * coverage refusal policy + message-building ({@link evaluateCoverageGate},
+ * {@link scanFailureMessage}) live in exactly one place so all three
+ * entrypoints (plugin add, plugin import, skills auto-install) share
+ * identical force semantics and byte-identical refusal messages (R2-001).
+ * Scanning + try/catch stay at the call sites (a pure helper cannot own the
+ * I/O); this module imports no fs.
+ *
+ * Force rule (fail-closed): `block` always refuses; `--force` lifts ONLY
+ * `unscannable`. Manifest-integrity refusals (undeclared SKILL.md in the tree,
+ * any symlink, case-colliding declared dirs, empty/missing `skills` on import,
+ * declared paths escaping the source dir) are NOT verdicts —
+ * `evaluateCoverageGate` enforces the walk-derived ones BEFORE the verdict
+ * gate runs, so `force` can never lift them either.
+ */
+import type { SkillCoverageScan, SkillScanResult } from "./skill-scanner.js";
+export interface InstallGateDecision {
+    allowed: boolean;
+    /** Rejected results when `!allowed`, else `[]`. */
+    rejected: SkillScanResult[];
+}
+/**
+ * Evaluate a set of declared-skill scan results against the install gate.
+ *
+ * `allowed = !hasBlock && (rejected.length === 0 || force)` — a `block` verdict
+ * refuses unconditionally; `force` bypasses ONLY `unscannable`. Empty,
+ * pass, and warn results are allowed.
+ */
+export declare function evaluateInstallGate(results: SkillScanResult[], options?: {
+    force?: boolean;
+}): InstallGateDecision;
+export interface CoverageGateDecision {
+    /** Verdict-gate evaluation of the declared results. */
+    gate: InstallGateDecision;
+    /**
+     * Refusal message when the install must be refused, else `null`
+     * (⇔ the install proceeds). Manifest-integrity refusals come first
+     * (errors → symlinks → undeclared — block-level, force never lifts),
+     * then the verdict refusal (`!gate.allowed`). Messages are the
+     * byte-identical UX contract both package entrypoints share (spec:
+     * "refusal output reuses scanner reports"; R2-001: the refusal policy +
+     * message-building lives in exactly one place).
+     */
+    refusalError: string | null;
+}
+/**
+ * Shared refusal policy for the coverage walk + verdict gate (R2-001) — the
+ * chain both `plugin add` and `plugin import` run between
+ * `scanSkillsWithCoverage` and placement. A `null` refusalError means the
+ * install may proceed; any non-null message is a block-level refusal the
+ * caller returns verbatim (`force` never lifts integrity refusals; the
+ * verdict branch already encodes the force rule via {@link evaluateInstallGate}).
+ */
+export declare function evaluateCoverageGate(coverage: SkillCoverageScan, options?: {
+    force?: boolean;
+}): CoverageGateDecision;
+/**
+ * Byte-identical message for the scanner-error deny (D7): a throw from the
+ * coverage walk or verdict evaluation is not a verdict, so no force branch
+ * consults it — the install is denied unconditionally (R2-001: shared by
+ * both package entrypoints).
+ */
+export declare function scanFailureMessage(error: unknown): string;
+//# sourceMappingURL=skill-install-gate.d.ts.map

package/dist/lib/skill-install-gate.js

@@ -0,0 +1,99 @@
+/**
+ * Shared install-gate evaluation for the skillguard runtime gate (D2).
+ *
+ * Pure helpers: verdict evaluation ({@link evaluateInstallGate}) and the
+ * coverage refusal policy + message-building ({@link evaluateCoverageGate},
+ * {@link scanFailureMessage}) live in exactly one place so all three
+ * entrypoints (plugin add, plugin import, skills auto-install) share
+ * identical force semantics and byte-identical refusal messages (R2-001).
+ * Scanning + try/catch stay at the call sites (a pure helper cannot own the
+ * I/O); this module imports no fs.
+ *
+ * Force rule (fail-closed): `block` always refuses; `--force` lifts ONLY
+ * `unscannable`. Manifest-integrity refusals (undeclared SKILL.md in the tree,
+ * any symlink, case-colliding declared dirs, empty/missing `skills` on import,
+ * declared paths escaping the source dir) are NOT verdicts —
+ * `evaluateCoverageGate` enforces the walk-derived ones BEFORE the verdict
+ * gate runs, so `force` can never lift them either.
+ */
+import { formatBatchReport, isRejectedVerdict } from "./skill-scanner.js";
+/**
+ * Evaluate a set of declared-skill scan results against the install gate.
+ *
+ * `allowed = !hasBlock && (rejected.length === 0 || force)` — a `block` verdict
+ * refuses unconditionally; `force` bypasses ONLY `unscannable`. Empty,
+ * pass, and warn results are allowed.
+ */
+export function evaluateInstallGate(results, options) {
+    const rejected = results.filter((r) => isRejectedVerdict(r.verdict));
+    const hasBlock = results.some((r) => r.verdict === "block");
+    const force = options?.force ?? false;
+    const allowed = !hasBlock && (rejected.length === 0 || force);
+    return { allowed, rejected: allowed ? [] : rejected };
+}
+/**
+ * Shared refusal policy for the coverage walk + verdict gate (R2-001) — the
+ * chain both `plugin add` and `plugin import` run between
+ * `scanSkillsWithCoverage` and placement. A `null` refusalError means the
+ * install may proceed; any non-null message is a block-level refusal the
+ * caller returns verbatim (`force` never lifts integrity refusals; the
+ * verdict branch already encodes the force rule via {@link evaluateInstallGate}).
+ */
+export function evaluateCoverageGate(coverage, options) {
+    // Manifest-integrity refusals — block-level, force NEVER lifts
+    // (JD-007: ANY symlink; JD-006: undeclared SKILL.md incl.
+    // node_modules/.git). A walk with I/O errors cannot certify the
+    // installed footprint — refuse first, before symlink/undeclared
+    // checks, because the broken subtree may hide either (JD-013).
+    if (coverage.errors.length > 0) {
+        return {
+            gate: { allowed: false, rejected: [] },
+            refusalError: `skillguard: install refused — ${coverage.errors.length} path(s) could not be read (walk incomplete; manifest-integrity, force never lifts):\n${coverage.errors.map((p) => `  ${p}`).join("\n")}`,
+        };
+    }
+    // FU-5 (F3 residual): a declared dir with case-colliding on-disk twins
+    // is ambiguous — the declared scan read one twin while both install.
+    const ambiguous = coverage.ambiguousDeclaredDirs ?? [];
+    if (ambiguous.length > 0) {
+        return {
+            gate: { allowed: false, rejected: [] },
+            refusalError: `skillguard: install refused — ambiguous declared skill dir(s) (case-colliding on-disk dirs; manifest-integrity, force never lifts):\n${ambiguous.map((p) => `  ${p}`).join("\n")}`,
+        };
+    }
+    if (coverage.symlinks.length > 0) {
+        return {
+            gate: { allowed: false, rejected: [] },
+            refusalError: `skillguard: install refused — symlink(s) in tree (manifest-integrity, force never lifts):\n${coverage.symlinks.map((p) => `  ${p}`).join("\n")}`,
+        };
+    }
+    if (coverage.undeclared.length > 0) {
+        return {
+            gate: { allowed: false, rejected: [] },
+            refusalError: `skillguard: install refused — undeclared SKILL.md(s) in tree (every skill-shaped file must be declared; force never lifts):\n${coverage.undeclared.map((p) => `  ${p}`).join("\n")}`,
+        };
+    }
+    const gate = evaluateInstallGate(coverage.declared, options);
+    if (!gate.allowed) {
+        const blocked = gate.rejected.filter((r) => r.verdict === "block").length;
+        const unscannable = gate.rejected.filter((r) => r.verdict === "unscannable").length;
+        return {
+            gate,
+            // Lead line names the rejected count; the batch report renders
+            // the FULL declared set so the header/rows reflect every scanned
+            // skill (D6, JD-014).
+            refusalError: `skillguard: install refused — ${gate.rejected.length} rejected (${blocked} blocked, ${unscannable} unscannable)\n${formatBatchReport(coverage.declared)}`,
+        };
+    }
+    return { gate, refusalError: null };
+}
+/**
+ * Byte-identical message for the scanner-error deny (D7): a throw from the
+ * coverage walk or verdict evaluation is not a verdict, so no force branch
+ * consults it — the install is denied unconditionally (R2-001: shared by
+ * both package entrypoints).
+ */
+export function scanFailureMessage(error) {
+    const msg = error instanceof Error ? error.message : String(error);
+    return `skillguard scan failed — ${msg}`;
+}
+//# sourceMappingURL=skill-install-gate.js.map

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

@@ -78,6 +78,86 @@ export declare function scanSkillFile(filePath: string): Promise<SkillScanResult
  * Useful for scanning a plugin's skills directory before installation.
  */
 export declare function scanSkillsDirectory(dir: string): Promise<SkillScanResult[]>;
+export interface SkillCoverageScan {
+    /**
+     * Scan results for the declared-entry SKILL.md files — the ONLY files the
+     * walk content-scans (JD-005). A declared file that is a symlink is never
+     * read through (it is already in {@link symlinks}); a missing declared
+     * SKILL.md fails closed as `unscannable`.
+     */
+    declared: SkillScanResult[];
+    /**
+     * Skill-shaped files (basename `SKILL.md`/`skill.md`) found in the tree
+     * OUTSIDE the declared set — including under `node_modules`/`.git` (JD-007).
+     * Paths only; content is never read during the walk (JD-005).
+     */
+    undeclared: string[];
+    /**
+     * ANY symlink (file or dir) found in the tree. The caller refuses on this
+     * (manifest-integrity, block-level, force never lifts — JD-007); the walk
+     * never dereferences them (JD-003).
+     */
+    symlinks: string[];
+    /**
+     * Paths the walk could not enumerate or stat (realpath/readdir/lstat I/O
+     * failure — e.g. an unreadable subtree). An incomplete walk cannot certify
+     * the installed footprint, so the caller refuses on this (manifest-
+     * integrity, block-level, force never lifts — JD-013); a silent `return`/
+     * `continue` would treat the broken subtree as empty and let the install
+     * proceed un-scanned.
+     */
+    errors: string[];
+    /**
+     * Distinct real on-disk dirs that case-collide with a DECLARED dir (FU-5,
+     * F3 residual): two or more on-disk dirs whose lowercased paths are equal
+     * AND match a declared dir — e.g. declared `skills/alpha` with on-disk
+     * siblings `skills/alpha` + `skills/Alpha` on a case-sensitive FS.
+     * Lowercased declared-dir membership (R1-F2-N1) cannot tell the twins
+     * apart: both pass membership (neither SKILL.md lands in `undeclared`)
+     * while the declared scan reads only one of them — the other installs
+     * un-scanned. The caller refuses on this (manifest-integrity, block-
+     * level, force never lifts). Absent or empty when no declared dir
+     * case-collides; a single case-folded on-disk dir (no twin) is NOT
+     * ambiguous — it resolves via the normal case-fold lookup.
+     */
+    ambiguousDeclaredDirs?: string[];
+}
+/**
+ * SKILL.md-only coverage walk for the install gates (JD-006/JD-007).
+ *
+ * Visits the ENTIRE tree with NO `node_modules`/`.git` exemption, so the visit
+ * set is exactly the footprint `fs.move`/`fs.copy` will place (JD-007). Collects
+ * only basename `SKILL.md`/`skill.md` files — never `PLUGIN.md`/README content
+ * (JD-002) — and flags ANY symlink (file or dir) without dereferencing it
+ * (JD-007/JD-003). A realpath visited-set terminates cycles defensively even if
+ * a future caller ever recurses through a link (JD-003). The walk itself does NO
+ * content reads: only the declared-entry files are handed to
+ * {@link scanSkillFile} afterwards (JD-005).
+ */
+export declare function scanSkillsWithCoverage(dir: string, declaredPaths: string[]): Promise<SkillCoverageScan>;
+export interface PathContainmentCheck {
+    /** True when the entry stays inside the root lexically AND by realpath. */
+    ok: boolean;
+    /** Absolute lexical resolution of `entry` under `rootAbs`. */
+    entryAbs: string;
+    /** Which containment check failed when `!ok`. */
+    violation?: "lexical" | "realpath";
+}
+/**
+ * Containment core (R2-002) — the ONE implementation of the lexical +
+ * realpath containment policy (JD-003): an entry must stay inside the root
+ * both lexically (`../../x`, absolute paths) and by realpath, so an in-tree
+ * symlink cannot redirect a read outside the staged clone. Realpath
+ * resolution is best-effort: a missing declared dir has no realpath yet, in
+ * which case lexical containment is the whole guard (the coverage walk later
+ * reports it as a missing/unscannable declared skill).
+ *
+ * Two surfaces wrap this core with their own error shapes (both bound by
+ * tests — keep the messages distinct): {@link resolveContained} (throwing;
+ * used by the coverage walk) and `skillPathContained` in agent-skills.ts
+ * (non-throwing `{ ok, reason }`; the import gate refuses gracefully).
+ */
+export declare function checkPathContained(rootAbs: string, rootReal: string, entry: string): Promise<PathContainmentCheck>;
 export declare function formatScanReport(result: SkillScanResult): string;
 export declare function formatBatchReport(results: SkillScanResult[]): string;
 export {};

package/dist/lib/skill-scanner.js

@@ -394,6 +394,287 @@ export async function scanSkillsDirectory(dir) {
     await walk(dir);
     return results;
 }
+/**
+ * SKILL.md-only coverage walk for the install gates (JD-006/JD-007).
+ *
+ * Visits the ENTIRE tree with NO `node_modules`/`.git` exemption, so the visit
+ * set is exactly the footprint `fs.move`/`fs.copy` will place (JD-007). Collects
+ * only basename `SKILL.md`/`skill.md` files — never `PLUGIN.md`/README content
+ * (JD-002) — and flags ANY symlink (file or dir) without dereferencing it
+ * (JD-007/JD-003). A realpath visited-set terminates cycles defensively even if
+ * a future caller ever recurses through a link (JD-003). The walk itself does NO
+ * content reads: only the declared-entry files are handed to
+ * {@link scanSkillFile} afterwards (JD-005).
+ */
+export async function scanSkillsWithCoverage(dir, declaredPaths) {
+    // Resolve the scan root once. Declared entries must stay inside it — a
+    // hostile manifest can never make the gate read outside the staged clone
+    // (JD-003: "no read outside the staged clone"; the interface contract names
+    // declared paths realpath-contained).
+    const rootAbs = path.resolve(dir);
+    const rootReal = await fs.realpath(rootAbs);
+    // Resolve each declared entry once (containment-verified) and reuse it for
+    // both the coverage set and the content scan — never twice.
+    const declaredDirs = new Map();
+    for (const entry of declaredPaths) {
+        declaredDirs.set(entry, await resolveContained(rootAbs, rootReal, entry));
+    }
+    // Declared skill DIRECTORIES — membership is case-insensitive by declared
+    // directory, never by file-basename spelling (R1-001/R3-001/R4-001). The
+    // walk collects ANY entry whose lowercased basename is `skill.md`, because
+    // the installed footprint is the on-disk tree whether the author wrote
+    // `SKILL.md`, `Skill.md`, `SKILL.MD` or any other fold — a declared skill's
+    // file must be recognized as declared no matter its case. Seeding exact-case
+    // basenames (F1/JD-011 seeded `SKILL.md` + `skill.md`) still missed every
+    // other fold: the file was collected, failed membership, and landed in
+    // `undeclared` — a block-level refusal `--force` never lifts — while the
+    // declared scan reported `unscannable` (permanent lockout for a legit
+    // declared skill). Membership by declared DIRECTORY keeps the smuggling
+    // refusal intact: a skill-shaped file whose parent dir is NOT a declared
+    // dir still misses the set and refuses as undeclared (CASE3).
+    const declaredDirAbs = new Set(declaredDirs.values());
+    // R1-F2-N1: declared-dir membership must ALSO fold case on the DIRECTORY
+    // name. `declaredDirAbs` retains MANIFEST case (`resolveContained` returns
+    // the manifest-spelled `entryAbs`); a package authored on a case-
+    // insensitive FS can declare `skills/Alpha` while the disk tree carries
+    // `skills/alpha` — the on-disk footprint the walk actually sees. Exact-
+    // case membership left the walk's dirname check missing the set → the file
+    // landed `undeclared` (block-level, force never lifts) while the declared
+    // scan reported the manifest-case path `unscannable` — the third instance
+    // of the case-lockout class (JD-011 file, R1-001 file-fold, dir-name
+    // fold). Compare lowercased on BOTH sides; the real on-disk path is still
+    // the one scanned below (never invent casing for file access).
+    const declaredDirAbsLower = new Set([...declaredDirAbs].map((d) => d.toLowerCase()));
+    const undeclared = [];
+    const symlinks = [];
+    const errors = [];
+    // Real on-disk dirs the walk actually visited (readdir-spelled casing) —
+    // used AFTER the walk to resolve declared dirs whose manifest spelling
+    // differs in case from the disk (R1-F2-N1); see the declared scan below.
+    const walkDirs = [];
+    const visited = new Set();
+    async function walk(currentDir) {
+        // realpath visited-set: a defensive cycle invariant (JD-003). Symlinks are
+        // never recursed into, so no cycle can form through the walk itself; the
+        // set guarantees termination even if that ever changes.
+        let real;
+        try {
+            real = await fs.realpath(currentDir);
+        }
+        catch {
+            // Fail-closed (JD-013): an unlistable subtree must surface as an
+            // error the caller refuses on, not silently read as empty.
+            errors.push(currentDir);
+            return;
+        }
+        if (visited.has(real))
+            return;
+        visited.add(real);
+        walkDirs.push(currentDir);
+        let entries;
+        try {
+            entries = await fs.readdir(currentDir);
+        }
+        catch {
+            // Fail-closed (JD-013): same as realpath above — record, do not
+            // swallow, so the caller can refuse an incomplete walk.
+            errors.push(currentDir);
+            return;
+        }
+        for (const entry of entries) {
+            const fullPath = path.join(currentDir, entry);
+            let lst;
+            try {
+                lst = await fs.lstat(fullPath);
+            }
+            catch {
+                // Fail-closed (JD-013): a path we cannot stat (race, I/O, or
+                // permission) must not silently vanish from the footprint
+                // inventory — record it and keep walking the rest.
+                errors.push(fullPath);
+                continue;
+            }
+            // Symlinks are never dereferenced: flagged for the caller's
+            // manifest-integrity refusal, never recursed into, never scanned
+            // (JD-007/JD-003).
+            if (lst.isSymbolicLink()) {
+                symlinks.push(fullPath);
+                continue;
+            }
+            if (lst.isDirectory()) {
+                await walk(fullPath);
+                continue;
+            }
+            // SKILL.md-only collection: basename SKILL.md/skill.md (any case
+            // fold), never PLUGIN.md or README (JD-002). Declared-ness is
+            // decided by the parent DIRECTORY being declared (R1-001): any case
+            // fold of the file inside a declared dir is declared, so the file
+            // is scanned — never flagged undeclared (block-level, force never
+            // lifts) for the exact-case spelling it happens to carry on disk.
+            if (entry.toLowerCase() === "skill.md") {
+                const resolved = path.resolve(fullPath);
+                if (!declaredDirAbsLower.has(path.dirname(resolved).toLowerCase())) {
+                    undeclared.push(fullPath);
+                }
+            }
+        }
+    }
+    // R3-F3-N1: walk the ABSOLUTE root, never the caller's raw `dir`. With a
+    // relative invocation (`javi-forge plugin import <relative-dir>`), the
+    // walkDirs two-tier lookup below compares walk-visited paths against
+    // `declaredAbs` (always absolute) — a relative walk made every declared dir
+    // fall back to the manifest path, reporting an existing declared file as
+    // `unscannable` (force would lift it and install un-scanned content).
+    // Starting from `rootAbs` also keeps undeclared/symlinks/errors absolute
+    // and consistent with the gate's realpath expectations.
+    await walk(rootAbs);
+    // FU-5 (F3 residual): a declared dir whose lowercased path maps to MORE
+    // THAN ONE distinct real on-disk dir is ambiguous. Declared-dir
+    // membership is lowercased on both sides (R1-F2-N1), so a case-colliding
+    // TWIN (declared `skills/alpha` + on-disk siblings `skills/alpha` and
+    // `skills/Alpha` on a case-sensitive FS) passes membership for BOTH
+    // dirs — neither SKILL.md lands in `undeclared` — while the declared
+    // scan below reads only one of them; the other would install un-scanned.
+    // Surface the colliding dirs as a refusal-class condition (the gate
+    // refuses, manifest-integrity, force never lifts). A single case-folded
+    // dir (no twin) is unaffected — the two-tier lookup resolves it.
+    const dirsByLower = new Map();
+    for (const d of walkDirs) {
+        const key = d.toLowerCase();
+        const group = dirsByLower.get(key);
+        if (group) {
+            group.push(d);
+        }
+        else {
+            dirsByLower.set(key, [d]);
+        }
+    }
+    const ambiguousDeclaredDirs = [];
+    for (const [key, group] of dirsByLower) {
+        if (group.length > 1 && declaredDirAbsLower.has(key)) {
+            // Sorted for deterministic output (readdir order is OS-dependent).
+            ambiguousDeclaredDirs.push(...[...group].sort());
+        }
+    }
+    // Content-scanned results for declared entries only (JD-005), in declared
+    // order so reports are deterministic. A declared file that is a symlink is
+    // already in `symlinks` — reading through it would escape the tree (JD-003),
+    // so it is skipped here (the caller refuses on `symlinks` first anyway).
+    const symlinkSet = new Set(symlinks.map((p) => path.resolve(p)));
+    const declared = [];
+    // Iterating the map keeps declared order (insertion order == declaredPaths)
+    // and guarantees an entry cannot be absent once resolved.
+    for (const declaredAbs of declaredDirs.values()) {
+        // R1-F2-N1: the declared scan reads the REAL on-disk dir the walk saw —
+        // a manifest spelling `skills/Alpha` against a disk tree `skills/alpha`
+        // must scan the lowercase dir that exists. The two-tier lookup prefers
+        // the exact-case real dir when present, then a case-fold match; a truly
+        // missing declared dir (no real dir matches) falls back to the manifest
+        // path so it still fails closed as `unscannable` (unchanged). Only
+        // the real on-disk path is ever handed to
+        // `declaredSkillFileOnDisk`/`scanSkillFile` — no casing is invented for
+        // file access.
+        const realDir = walkDirs.find((d) => d === declaredAbs) ??
+            walkDirs.find((d) => d.toLowerCase() === declaredAbs.toLowerCase()) ??
+            declaredAbs;
+        // Case-tolerant resolution (JD-011/R1-001): a declared skill whose
+        // on-disk file is lowercase `skill.md` — or any other case fold
+        // (`Skill.md`, `SKILL.MD`, …) — is the same declared entry; scan the
+        // file that actually exists instead of reporting the exact-case path
+        // as a missing/unscannable file.
+        const file = await declaredSkillFileOnDisk(realDir);
+        // Whether the canonical or the lowercase variant, a symlinked declared
+        // file is already in `symlinks` — never read through it (JD-003/JD-007).
+        if (symlinkSet.has(path.resolve(file)))
+            continue;
+        declared.push(await scanSkillFile(file));
+    }
+    return { declared, undeclared, symlinks, errors, ambiguousDeclaredDirs };
+}
+/**
+ * Resolve the on-disk skill file for a declared skill directory. The coverage
+ * walk recognizes ANY case fold of the `skill.md`/`SKILL.md` basename in a
+ * declared dir as the declared file (R1-001), so a declared entry may
+ * legitimately carry any fold on disk; favor the conventional exact-case name,
+ * fall back to the lowercase variant (JD-011), then to any other case fold via
+ * a case-insensitive readdir. When no skill-shaped file exists at all, return
+ * the canonical path so `scanSkillFile` reports the declared skill as
+ * `unscannable` (fail-closed, unchanged behavior).
+ */
+async function declaredSkillFileOnDisk(absDir) {
+    const canonical = path.join(absDir, "SKILL.md");
+    if (await fs.pathExists(canonical))
+        return canonical;
+    const lower = path.join(absDir, "skill.md");
+    if (await fs.pathExists(lower))
+        return lower;
+    // Any other case fold (`Skill.md`, `SKILL.MD`, `skill.MD`, …) is the same
+    // declared file (R1-001): the declared scan must read what actually exists
+    // or the declared entry reports `unscannable` while the walk collects it as
+    // declared. Prefer the canonical name when both exist (JD-F1-N1 residual).
+    try {
+        const entries = await fs.readdir(absDir);
+        const fold = entries.find((e) => e.toLowerCase() === "skill.md");
+        if (fold)
+            return path.join(absDir, fold);
+    }
+    catch {
+        // Unreadable declared dir → return the canonical path so scanSkillFile
+        // fails closed as `unscannable` (no new behavior).
+    }
+    return canonical;
+}
+/**
+ * Containment core (R2-002) — the ONE implementation of the lexical +
+ * realpath containment policy (JD-003): an entry must stay inside the root
+ * both lexically (`../../x`, absolute paths) and by realpath, so an in-tree
+ * symlink cannot redirect a read outside the staged clone. Realpath
+ * resolution is best-effort: a missing declared dir has no realpath yet, in
+ * which case lexical containment is the whole guard (the coverage walk later
+ * reports it as a missing/unscannable declared skill).
+ *
+ * Two surfaces wrap this core with their own error shapes (both bound by
+ * tests — keep the messages distinct): {@link resolveContained} (throwing;
+ * used by the coverage walk) and `skillPathContained` in agent-skills.ts
+ * (non-throwing `{ ok, reason }`; the import gate refuses gracefully).
+ */
+export async function checkPathContained(rootAbs, rootReal, entry) {
+    const entryAbs = path.resolve(rootAbs, entry);
+    // Lexical containment — catches `../outside` and absolute entries.
+    const rel = path.relative(rootAbs, entryAbs);
+    if (rel.startsWith("..") || path.isAbsolute(rel)) {
+        return { ok: false, entryAbs, violation: "lexical" };
+    }
+    // Realpath containment — catches a directory inside the tree whose real
+    // location is outside it. A missing declared dir (later `unscannable`) has
+    // no realpath yet; its lexical containment above is then the whole guard.
+    let real;
+    try {
+        real = await fs.realpath(entryAbs);
+    }
+    catch {
+        return { ok: true, entryAbs };
+    }
+    const relReal = path.relative(rootReal, real);
+    if (relReal.startsWith("..") || path.isAbsolute(relReal)) {
+        return { ok: false, entryAbs, violation: "realpath" };
+    }
+    return { ok: true, entryAbs };
+}
+/**
+ * Resolve a declared skill entry to an absolute directory and verify it stays
+ * inside the scan root — both lexically (`../../x`, absolute paths) and by
+ * realpath, so an in-tree symlink cannot redirect the declared read outside the
+ * staged clone (JD-003). Throws when the entry escapes; the caller denies.
+ * Thin throwing surface over the shared containment core (R2-002).
+ */
+async function resolveContained(rootAbs, rootReal, entry) {
+    const check = await checkPathContained(rootAbs, rootReal, entry);
+    if (!check.ok) {
+        throw new Error(`skillguard: declared skill path escapes scan root — ${entry}`);
+    }
+    return check.entryAbs;
+}
 // =============================================================================
 // Report formatting
 // =============================================================================

package/dist/ui/AutoSkills.d.ts

@@ -3,7 +3,9 @@ interface AutoSkillsProps {
     projectDir: string;
     skillsDir?: string;
     dryRun?: boolean;
+    /** Bypass the skillguard gate for unscannable sources ONLY — block always refuses (D5) */
+    force?: boolean;
 }
-export default function AutoSkills({ projectDir, skillsDir, dryRun, }: AutoSkillsProps): React.JSX.Element;
+export default function AutoSkills({ projectDir, skillsDir, dryRun, force, }: AutoSkillsProps): React.JSX.Element;
 export {};
 //# sourceMappingURL=AutoSkills.d.ts.map

package/dist/ui/AutoSkills.js

@@ -2,10 +2,11 @@ import { Box, Text, useApp, useInput } from "ink";
 import Spinner from "ink-spinner";
 import React, { useCallback, useEffect, useState } from "react";
 import { autoInstallSkills } from "../lib/auto-skill-install.js";
+import { formatScanReport } from "../lib/skill-scanner.js";
 import { useCIMode } from "./CIContext.js";
 import Header from "./Header.js";
 import { theme } from "./theme.js";
-export default function AutoSkills({ projectDir, skillsDir, dryRun, }) {
+export default function AutoSkills({ projectDir, skillsDir, dryRun, force = false, }) {
     const { exit } = useApp();
     const isCI = useCIMode();
     const [result, setResult] = useState(null);
@@ -20,16 +21,27 @@ export default function AutoSkills({ projectDir, skillsDir, dryRun, }) {
             skillsSourceDir: skillsDir,
             skillsTargetDir: skillsDir,
             dryRun: dryRun ?? false,
+            force,
         })
             .then((r) => {
+            // FU-1 (R4-002): a refused batch (gate-blocked skills) must exit
+            // non-zero so scripted consumers can tell a refusal from success;
+            // `process.exitCode` (not `process.exit`) keeps Ink rendering.
+            // A clean run resets to 0 so an interactive re-scan (r) after a
+            // refusal can still exit 0. Force-lifted unscannable installs are
+            // NOT blocked — they keep exit 0.
+            process.exitCode = r.blocked.length > 0 ? 1 : 0;
             setResult(r);
             setLoading(false);
         })
             .catch((e) => {
+            // A scan throw is a gate deny (D7) — nothing was copied; exit
+            // non-zero like any other refusal.
+            process.exitCode = 1;
             setError(String(e));
             setLoading(false);
         });
-    }, [projectDir, skillsDir, dryRun]);
+    }, [projectDir, skillsDir, dryRun, force]);
     useEffect(() => {
         runDetection();
     }, [runDetection]);
@@ -116,6 +128,19 @@ export default function AutoSkills({ projectDir, skillsDir, dryRun, }) {
                     React.createElement(Text, { dimColor: true, color: theme.warning },
                         "  ",
                         "not found in source")))))),
+                result.blocked.length > 0 && (React.createElement(Box, { flexDirection: "column" }, result.blocked.map((scan) => (React.createElement(Box, { key: `blocked-${scan.skillName}`, flexDirection: "column" },
+                    React.createElement(Box, { marginLeft: 4 },
+                        React.createElement(Text, { color: theme.error },
+                            "\u2717",
+                            " ",
+                            scan.skillName,
+                            " \u2014 refused")),
+                    React.createElement(Box, { marginLeft: 6 },
+                        React.createElement(Text, { color: theme.muted, dimColor: true }, formatScanReport(scan)
+                            .split("\n")
+                            .map((l) => l.trim())
+                            .filter(Boolean)
+                            .join(" | ")))))))),
                 totalSkills === 0 && (React.createElement(Box, { marginLeft: 4 },
                     React.createElement(Text, { color: theme.muted }, "No skills recommended for this stack")))))),
         !loading && (React.createElement(Box, { marginTop: 1 },

package/dist/ui/Plugin.d.ts

@@ -4,7 +4,9 @@ interface PluginProps {
     target?: string;
     dryRun: boolean;
     codex?: boolean;
+    /** Bypass the skillguard gate for unscannable sources ONLY — block always refuses (D5) */
+    force?: boolean;
 }
-export default function Plugin({ action, target, dryRun, codex, }: PluginProps): React.JSX.Element;
+export default function Plugin({ action, target, dryRun, codex, force, }: PluginProps): React.JSX.Element;
 export {};
 //# sourceMappingURL=Plugin.d.ts.map

package/dist/ui/Plugin.js

@@ -16,7 +16,7 @@ const STATUS_COLOR = {
     error: theme.error,
     skipped: theme.muted,
 };
-export default function Plugin({ action, target, dryRun, codex = false, }) {
+export default function Plugin({ action, target, dryRun, codex = false, force = false, }) {
     const [steps, setSteps] = useState([]);
     const [done, setDone] = useState(false);
     const onStep = (step) => {
@@ -44,7 +44,7 @@ export default function Plugin({ action, target, dryRun, codex = false, }) {
                             });
                             break;
                         }
-                        await runPluginAdd(target, dryRun, onStep);
+                        await runPluginAdd(target, dryRun, onStep, { force });
                         break;
                     case "remove":
                         if (!target) {
@@ -106,7 +106,7 @@ export default function Plugin({ action, target, dryRun, codex = false, }) {
                             });
                             break;
                         }
-                        await runPluginImport(target, dryRun, onStep);
+                        await runPluginImport(target, dryRun, onStep, { force });
                         break;
                     case "export-skills":
                         if (target === "global") {
@@ -129,7 +129,7 @@ export default function Plugin({ action, target, dryRun, codex = false, }) {
             setDone(true);
         };
         run();
-    }, [action, target, dryRun]);
+    }, [action, target, dryRun, force]);
     return (React.createElement(Box, { flexDirection: "column", padding: 1 },
         React.createElement(Box, { marginBottom: 1 },
             React.createElement(Text, { bold: true, color: theme.primary }, "javi-forge"),

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "javi-forge",
-	"version": "1.27.0",
+	"version": "1.28.1",
 	"description": "Project scaffolding and AI-ready CI bootstrap",
 	"type": "module",
 	"bin": {
@@ -85,12 +85,16 @@
 		"overrides": {
 			"handlebars": "^4.7.9",
 			"picomatch": "^4.0.4",
-			"brace-expansion": "^5.0.5",
+			"brace-expansion": "^5.0.9",
 			"lodash": "^4.18.0",
 			"lodash-es": "^4.18.0",
-			"fast-uri": "^3.1.2",
-			"postcss": "^8.5.10",
-			"vite": "^8.0.5"
+			"fast-uri": "^3.1.5",
+			"postcss": "^8.5.18",
+			"vite": "^8.0.16",
+			"js-yaml": "^4.3.1",
+			"nanoid": "^3.3.17",
+			"undici": "^7.29.0",
+			"ws": "^8.21.0"
 		}
 	}
 }