javi-forge 1.28.0 → 1.28.1

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  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";
+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

@@ -98,6 +98,9 @@ export const HELP_TEXT = `
     - 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

package/dist/commands/plugin.d.ts

@@ -37,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, force?: boolean): 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

@@ -18,6 +18,12 @@ export async function runPluginAdd(source, dryRun, onStep, options = {}) {
     }
     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, force = false) {
+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, force });
+    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, force = false)
     }
     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

@@ -35,6 +35,14 @@ export declare function importAgentSkillsPackage(sourceDir: string, options?: {
     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,8 +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 { evaluateInstallGate } from "./skill-install-gate.js";
-import { formatBatchReport, scanSkillsWithCoverage } from "./skill-scanner.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.
@@ -111,6 +111,7 @@ export async function importAgentSkillsPackage(sourceDir, options = {}) {
     if (typeof pluginName !== "string") {
         return {
             success: false,
+            refused: true,
             error: `skillguard: install refused — invalid manifest name "${pluginName}" (manifest-integrity, force never lifts)`,
         };
     }
@@ -122,6 +123,7 @@ export async function importAgentSkillsPackage(sourceDir, options = {}) {
         path.isAbsolute(pluginName)) {
         return {
             success: false,
+            refused: true,
             error: `skillguard: install refused — invalid manifest name "${pluginName}" (manifest-integrity, force never lifts)`,
         };
     }
@@ -133,6 +135,7 @@ export async function importAgentSkillsPackage(sourceDir, options = {}) {
         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)",
         };
     }
@@ -143,12 +146,14 @@ export async function importAgentSkillsPackage(sourceDir, options = {}) {
         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`,
             };
         }
@@ -156,6 +161,7 @@ export async function importAgentSkillsPackage(sourceDir, options = {}) {
         if (!contained.ok) {
             return {
                 success: false,
+                refused: true,
                 error: `skills.json skills entry "${entry.name}" path escapes package root (${contained.reason}) — refusing`,
             };
         }
@@ -169,49 +175,25 @@ export async function importAgentSkillsPackage(sourceDir, options = {}) {
     // 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 {
-        const coverage = await scanSkillsWithCoverage(sourceDir, declaredPaths);
-        // Manifest-integrity refusals — block-level, force NEVER lifts
-        // (JD-007: ANY symlink; JD-006: undeclared SKILL.md incl. node_modules).
-        // A walk with I/O errors cannot certify the copied footprint — refuse
-        // first, because the broken subtree may hide symlinks or undeclared
-        // files (JD-013).
-        if (coverage.errors.length > 0) {
-            return {
-                success: false,
-                error: `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")}`,
-            };
-        }
-        if (coverage.symlinks.length > 0) {
-            return {
-                success: false,
-                error: `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 {
-                success: false,
-                error: `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, { force });
-        if (!gate.allowed) {
-            const blocked = gate.rejected.filter((r) => r.verdict === "block").length;
-            const unscannable = gate.rejected.filter((r) => r.verdict === "unscannable").length;
-            return {
-                success: false,
-                // 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).
-                error: `skillguard: install refused — ${gate.rejected.length} rejected (${blocked} blocked, ${unscannable} unscannable)\n${formatBatchReport(coverage.declared)}`,
-            };
-        }
+        coverage = await scanSkillsWithCoverage(sourceDir, declaredPaths);
     }
     catch (scanError) {
-        const msg = scanError instanceof Error ? scanError.message : String(scanError);
         return {
             success: false,
-            error: `skillguard scan failed — ${msg}`,
+            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
@@ -242,33 +224,18 @@ export async function importAgentSkillsPackage(sourceDir, options = {}) {
  * 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).
- * 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
- * will later report it as a missing/unscannable declared skill).
+ * 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 entryAbs = path.resolve(rootAbs, entryPath);
-    const rel = path.relative(rootAbs, entryAbs);
-    if (rel.startsWith("..") || path.isAbsolute(rel)) {
+    const check = await checkPathContained(rootAbs, rootReal, entryPath);
+    if (!check.ok) {
         return {
             ok: false,
-            reason: `path "${entryPath}" resolves outside the package root`,
+            reason: `path "${entryPath}" resolves outside the package root${check.violation === "realpath" ? " (realpath)" : ""}`,
         };
     }
-    try {
-        const entryReal = await fs.realpath(entryAbs);
-        const relReal = path.relative(rootReal, entryReal);
-        if (relReal.startsWith("..") || path.isAbsolute(relReal)) {
-            return {
-                ok: false,
-                reason: `path "${entryPath}" resolves outside the package root (realpath)`,
-            };
-        }
-    }
-    catch {
-        // Declared dir does not exist yet — lexical containment stands; the
-        // coverage walk reports it as a missing declared skill later.
-    }
     return { ok: true };
 }
 // ── Aggregation ──────────────────────────────────────────────────────────

package/dist/lib/plugin.d.ts

@@ -14,6 +14,14 @@ export declare function installPlugin(source: string, options?: {
     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,8 +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 { evaluateInstallGate } from "./skill-install-gate.js";
-import { formatBatchReport, scanSkillsWithCoverage } from "./skill-scanner.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 ──────────────────────────────────────────────────────────────
@@ -158,54 +158,27 @@ export async function installPlugin(source, options = {}) {
             // 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).
-            let gate;
-            // Declared results, hoisted for the refusal report: the batch report
-            // renders the FULL declared set (header "Scanned: N" + per-skill rows,
-            // D6) while the lead line still names the rejected count (JD-014).
-            let declaredResults = [];
+            // 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));
-                const coverage = await scanSkillsWithCoverage(tmpDir, declaredPaths);
-                // 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 {
-                        success: false,
-                        error: `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")}`,
-                    };
-                }
-                if (coverage.symlinks.length > 0) {
-                    return {
-                        success: false,
-                        error: `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 {
-                        success: false,
-                        error: `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")}`,
-                    };
-                }
-                declaredResults = coverage.declared;
-                gate = evaluateInstallGate(coverage.declared, { force });
+                coverage = await scanSkillsWithCoverage(tmpDir, declaredPaths);
             }
             catch (scanError) {
-                const msg = scanError instanceof Error ? scanError.message : String(scanError);
                 return {
                     success: false,
-                    error: `skillguard scan failed — ${msg}`,
+                    refused: true,
+                    error: scanFailureMessage(scanError),
                 };
             }
-            if (!gate.allowed) {
-                const blocked = gate.rejected.filter((r) => r.verdict === "block").length;
-                const unscannable = gate.rejected.filter((r) => r.verdict === "unscannable").length;
+            const decision = evaluateCoverageGate(coverage, { force });
+            if (decision.refusalError) {
                 return {
                     success: false,
-                    error: `skillguard: install refused — ${gate.rejected.length} rejected (${blocked} blocked, ${unscannable} unscannable)\n${formatBatchReport(declaredResults)}`,
+                    refused: true,
+                    error: decision.refusalError,
                 };
             }
             // Remove existing version if present

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

@@ -1,18 +1,22 @@
 /**
  * Shared install-gate evaluation for the skillguard runtime gate (D2).
  *
- * Pure helper: verdict evaluation for a set of declared skill scans lives in
- * exactly one place so all three entrypoints (plugin add, plugin import, skills
- * auto-install) share identical force semantics. Scanning + try/catch stay at
- * the call sites (a pure helper cannot own the I/O); this module imports no fs.
+ * 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, empty/missing `skills` on import, declared paths escaping the
- * source dir) are NOT verdicts — call sites enforce them BEFORE this helper
- * runs, so `force` can never lift them either.
+ * 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 { SkillScanResult } from "./skill-scanner.js";
+import type { SkillCoverageScan, SkillScanResult } from "./skill-scanner.js";
 export interface InstallGateDecision {
     allowed: boolean;
     /** Rejected results when `!allowed`, else `[]`. */
@@ -28,4 +32,36 @@ export interface InstallGateDecision {
 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

@@ -1,18 +1,22 @@
 /**
  * Shared install-gate evaluation for the skillguard runtime gate (D2).
  *
- * Pure helper: verdict evaluation for a set of declared skill scans lives in
- * exactly one place so all three entrypoints (plugin add, plugin import, skills
- * auto-install) share identical force semantics. Scanning + try/catch stay at
- * the call sites (a pure helper cannot own the I/O); this module imports no fs.
+ * 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, empty/missing `skills` on import, declared paths escaping the
- * source dir) are NOT verdicts — call sites enforce them BEFORE this helper
- * runs, so `force` can never lift them either.
+ * 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 { isRejectedVerdict } from "./skill-scanner.js";
+import { formatBatchReport, isRejectedVerdict } from "./skill-scanner.js";
 /**
  * Evaluate a set of declared-skill scan results against the install gate.
  *
@@ -27,4 +31,69 @@ export function evaluateInstallGate(results, options) {
     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

@@ -107,6 +107,20 @@ export interface SkillCoverageScan {
      * 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).
@@ -121,6 +135,29 @@ export interface SkillCoverageScan {
  * {@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

@@ -528,6 +528,34 @@ export async function scanSkillsWithCoverage(dir, declaredPaths) {
     // 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),
@@ -561,7 +589,7 @@ export async function scanSkillsWithCoverage(dir, declaredPaths) {
             continue;
         declared.push(await scanSkillFile(file));
     }
-    return { declared, undeclared, symlinks, errors };
+    return { declared, undeclared, symlinks, errors, ambiguousDeclaredDirs };
 }
 /**
  * Resolve the on-disk skill file for a declared skill directory. The coverage
@@ -597,17 +625,25 @@ async function declaredSkillFileOnDisk(absDir) {
     return canonical;
 }
 /**
- * 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.
+ * 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).
  */
-async function resolveContained(rootAbs, rootReal, entry) {
+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)) {
-        throw new Error(`skillguard: declared skill path escapes scan root — ${entry}`);
+        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
@@ -617,13 +653,27 @@ async function resolveContained(rootAbs, rootReal, entry) {
         real = await fs.realpath(entryAbs);
     }
     catch {
-        return entryAbs;
+        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 entryAbs;
+    return check.entryAbs;
 }
 // =============================================================================
 // Report formatting

package/dist/ui/AutoSkills.js

@@ -24,10 +24,20 @@ export default function AutoSkills({ projectDir, skillsDir, dryRun, force = fals
             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);
         });

package/dist/ui/Plugin.js

@@ -106,7 +106,7 @@ export default function Plugin({ action, target, dryRun, codex = false, force =
                             });
                             break;
                         }
-                        await runPluginImport(target, dryRun, onStep, force);
+                        await runPluginImport(target, dryRun, onStep, { force });
                         break;
                     case "export-skills":
                         if (target === "global") {

package/package.json

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