javi-forge 1.28.0 → 1.29.0

package/assets/claude-hooks/manifest.json

@@ -0,0 +1 @@
+{"schemaVersion":1,"asset":{"name":"javi-forge-skillguard-pre-tool-use.mjs","version":1,"policyVersion":1,"sha256":"78be7e6613c012280b7ad17886462ba166b63ebd031e34565d757b3a0796d7cc","historical":[]},"settingsEntries":{"current":{"version":1,"canonicalSha256":"038c59a91bf8967f6908afed74c465f1e7030254e11e4f8738975d6d708424d4"},"historical":[]},"installerHelpers":{"windowsSecureObject":null}}

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/constants.d.ts

@@ -11,6 +11,8 @@ export declare const WORKFLOWS_DIR: string;
 export declare const CI_LOCAL_DIR: string;
 /** Git hook assets directory (installed by `javi-forge ci init`) */
 export declare const HOOK_ASSETS_DIR: string;
+/** Standalone Claude command-hook assets directory */
+export declare const CLAUDE_HOOK_ASSETS_DIR: string;
 /** Security hooks template directory */
 export declare const SECURITY_HOOKS_DIR: string;
 /** Local AI stack template directory */

package/dist/constants.js

@@ -13,6 +13,8 @@ export const WORKFLOWS_DIR = path.join(FORGE_ROOT, "workflows");
 export const CI_LOCAL_DIR = path.join(FORGE_ROOT, "ci-local");
 /** Git hook assets directory (installed by `javi-forge ci init`) */
 export const HOOK_ASSETS_DIR = path.join(FORGE_ROOT, "assets", "hooks");
+/** Standalone Claude command-hook assets directory */
+export const CLAUDE_HOOK_ASSETS_DIR = path.join(FORGE_ROOT, "assets", "claude-hooks");
 /** Security hooks template directory */
 export const SECURITY_HOOKS_DIR = path.join(TEMPLATES_DIR, "security-hooks");
 /** Local AI stack template directory */

package/dist/lib/__fixtures__/claude-hook-ownership.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Shared frozen ownership fixtures for the SkillGuard Claude PreToolUse guard.
+ *
+ * This module is the single source of truth for the byte/structure-exact
+ * identities the read-only recognition layer (Slice 2) classifies against:
+ *
+ * - the managed settings-entry handler group the Slice-3 writer installs;
+ * - the four v0 legacy cohort objects, copied verbatim from
+ *   `templates/security-hooks/claude-settings-security.json` (never normalized);
+ * - the marker/placeholder/hash constants.
+ *
+ * Everything here is data only (frozen literals plus a couple of pure
+ * builders) so it is deterministic, host-independent, and trivially testable.
+ * The production classifier imports the constants and the legacy cohort from
+ * here; the tests additionally use the one-byte-edited and duplicate variants.
+ */
+/** Exact managed marker prefix on the settings handler's `statusMessage`. */
+export declare const MANAGED_STATUS_PREFIX = "javi-forge-global-pretooluse:v1:sha256:";
+/** Placeholder the canonical hash normalizes the live asset SHA token to. */
+export declare const ASSET_SHA_PLACEHOLDER = "<ASSET_SHA256>";
+/** Whole-file SHA-256 of the retained v0 legacy scaffold template. */
+export declare const LEGACY_FILE_SHA256 = "b4638222ecddc2daac6ec3339596d853a626906bbd1233d789d80a319325c68d";
+/** Exact managed matcher — an exact-name alternative list, never a wildcard. */
+export declare const MANAGED_MATCHER = "Bash|PowerShell|Read|Write|Edit";
+/** Single project-local MJS argument, kept as a literal placeholder path. */
+export declare const MANAGED_ASSET_ARG = "${CLAUDE_PROJECT_DIR}/.claude/hooks/javi-forge-skillguard-pre-tool-use.mjs";
+/** Exact asset filename under `.claude/hooks/`. */
+export declare const ASSET_NAME = "javi-forge-skillguard-pre-tool-use.mjs";
+/** Exact first-line comment marking the managed asset. */
+export declare const ASSET_MANAGED_MARKER = "// javi-forge-managed: claude-pretooluse v1";
+/**
+ * A representative live asset SHA. Used only to build marker `statusMessage`
+ * values in fixtures; the canonical settings identity is invariant under this
+ * value (Decision ②), which the rotation-invariance test proves.
+ */
+export declare const SAMPLE_ASSET_SHA256 = "78be7e6613c012280b7ad17886462ba166b63ebd031e34565d757b3a0796d7cc";
+/** Build the exact marker `statusMessage` for a given live asset SHA. */
+export declare function managedStatusMessage(assetSha?: string): string;
+/** Build the exact managed command handler for a given live asset SHA. */
+export declare function managedHandler(assetSha?: string): {
+    type: string;
+    command: string;
+    args: string[];
+    timeout: number;
+    statusMessage: string;
+};
+/** Build the exact managed matcher group for a given live asset SHA. */
+export declare function managedGroup(assetSha?: string): {
+    matcher: string;
+    hooks: {
+        type: string;
+        command: string;
+        args: string[];
+        timeout: number;
+        statusMessage: string;
+    }[];
+};
+/** Build a valid settings container around the given hook sections. */
+export declare function settingsContainer(pre?: unknown[], post?: unknown[], extra?: Record<string, unknown>): Record<string, unknown>;
+export declare const L1_BASH_DANGEROUS: {
+    readonly matcher: "Bash";
+    readonly hook: "COMMAND=\"$CLAUDE_TOOL_INPUT\"\nBLOCKED_PATTERNS=(\n  'rm -rf /'\n  'rm -rf ~'\n  'chmod 777'\n  'curl.*|.*sh'\n  'wget.*|.*sh'\n  'eval.*\\$'\n  'base64.*-d.*|.*sh'\n  ':(){:|:&};:'\n)\nfor pattern in \"${BLOCKED_PATTERNS[@]}\"; do\n  if echo \"$COMMAND\" | grep -qE \"$pattern\"; then\n    echo \"BLOCKED: Dangerous command pattern detected: $pattern\"\n    exit 2\n  fi\ndone\nexit 0";
+    readonly description: "Block dangerous shell commands (rm -rf /, chmod 777, pipe-to-sh, fork bombs)";
+};
+export declare const L2_BASH_SENSITIVE_READ: {
+    readonly matcher: "Bash";
+    readonly hook: "COMMAND=\"$CLAUDE_TOOL_INPUT\"\nSENSITIVE_PATHS=(\n  '.env'\n  '.env.local'\n  '.env.production'\n  'credentials'\n  'secrets'\n  '.ssh'\n  '.gnupg'\n  '.aws/credentials'\n)\nfor path in \"${SENSITIVE_PATHS[@]}\"; do\n  if echo \"$COMMAND\" | grep -qE \"(cat|less|head|tail|bat|read).*$path\"; then\n    echo \"BLOCKED: Attempt to read sensitive file: $path\"\n    exit 2\n  fi\ndone\nexit 0";
+    readonly description: "Prevent reading sensitive files (.env, credentials, SSH keys)";
+};
+export declare const L3_WRITE_EDIT_PROTECTED: {
+    readonly matcher: "Write|Edit";
+    readonly hook: "INPUT=\"$CLAUDE_TOOL_INPUT\"\nPROTECTED_FILES=(\n  '.env'\n  '.env.production'\n  'credentials.json'\n  'serviceAccountKey.json'\n  '.ssh/'\n  '.gnupg/'\n)\nfor pf in \"${PROTECTED_FILES[@]}\"; do\n  if echo \"$INPUT\" | grep -q \"$pf\"; then\n    echo \"BLOCKED: Cannot modify protected file: $pf\"\n    exit 2\n  fi\ndone\nexit 0";
+    readonly description: "Prevent writing to credential and secret files";
+};
+export declare const L4_BASH_POST_SECRET_SCAN: {
+    readonly matcher: "Bash";
+    readonly hook: "OUTPUT=\"$CLAUDE_TOOL_OUTPUT\"\nLEAK_PATTERNS=(\n  'AKIA[0-9A-Z]{16}'\n  'ghp_[A-Za-z0-9]{36}'\n  'sk_live_[0-9a-zA-Z]{24,}'\n  'xox[baprs]-[0-9a-zA-Z-]+'\n  '-----BEGIN.*PRIVATE KEY-----'\n)\nfor pattern in \"${LEAK_PATTERNS[@]}\"; do\n  if echo \"$OUTPUT\" | grep -qE \"$pattern\"; then\n    echo \"WARNING: Command output may contain secrets. Review carefully.\"\n    exit 0\n  fi\ndone\nexit 0";
+    readonly description: "Warn if command output contains potential secrets";
+};
+/** The complete four-object v0 legacy cohort in committed order (L1–L3 Pre, L4 Post). */
+export declare const LEGACY_COHORT: {
+    readonly L1: {
+        readonly matcher: "Bash";
+        readonly hook: "COMMAND=\"$CLAUDE_TOOL_INPUT\"\nBLOCKED_PATTERNS=(\n  'rm -rf /'\n  'rm -rf ~'\n  'chmod 777'\n  'curl.*|.*sh'\n  'wget.*|.*sh'\n  'eval.*\\$'\n  'base64.*-d.*|.*sh'\n  ':(){:|:&};:'\n)\nfor pattern in \"${BLOCKED_PATTERNS[@]}\"; do\n  if echo \"$COMMAND\" | grep -qE \"$pattern\"; then\n    echo \"BLOCKED: Dangerous command pattern detected: $pattern\"\n    exit 2\n  fi\ndone\nexit 0";
+        readonly description: "Block dangerous shell commands (rm -rf /, chmod 777, pipe-to-sh, fork bombs)";
+    };
+    readonly L2: {
+        readonly matcher: "Bash";
+        readonly hook: "COMMAND=\"$CLAUDE_TOOL_INPUT\"\nSENSITIVE_PATHS=(\n  '.env'\n  '.env.local'\n  '.env.production'\n  'credentials'\n  'secrets'\n  '.ssh'\n  '.gnupg'\n  '.aws/credentials'\n)\nfor path in \"${SENSITIVE_PATHS[@]}\"; do\n  if echo \"$COMMAND\" | grep -qE \"(cat|less|head|tail|bat|read).*$path\"; then\n    echo \"BLOCKED: Attempt to read sensitive file: $path\"\n    exit 2\n  fi\ndone\nexit 0";
+        readonly description: "Prevent reading sensitive files (.env, credentials, SSH keys)";
+    };
+    readonly L3: {
+        readonly matcher: "Write|Edit";
+        readonly hook: "INPUT=\"$CLAUDE_TOOL_INPUT\"\nPROTECTED_FILES=(\n  '.env'\n  '.env.production'\n  'credentials.json'\n  'serviceAccountKey.json'\n  '.ssh/'\n  '.gnupg/'\n)\nfor pf in \"${PROTECTED_FILES[@]}\"; do\n  if echo \"$INPUT\" | grep -q \"$pf\"; then\n    echo \"BLOCKED: Cannot modify protected file: $pf\"\n    exit 2\n  fi\ndone\nexit 0";
+        readonly description: "Prevent writing to credential and secret files";
+    };
+    readonly L4: {
+        readonly matcher: "Bash";
+        readonly hook: "OUTPUT=\"$CLAUDE_TOOL_OUTPUT\"\nLEAK_PATTERNS=(\n  'AKIA[0-9A-Z]{16}'\n  'ghp_[A-Za-z0-9]{36}'\n  'sk_live_[0-9a-zA-Z]{24,}'\n  'xox[baprs]-[0-9a-zA-Z-]+'\n  '-----BEGIN.*PRIVATE KEY-----'\n)\nfor pattern in \"${LEAK_PATTERNS[@]}\"; do\n  if echo \"$OUTPUT\" | grep -qE \"$pattern\"; then\n    echo \"WARNING: Command output may contain secrets. Review carefully.\"\n    exit 0\n  fi\ndone\nexit 0";
+        readonly description: "Warn if command output contains potential secrets";
+    };
+};
+/**
+ * One-byte-edited L1: a single trailing character removed from the description.
+ * It must fail deep-structural equality against the exact cohort member.
+ */
+export declare const L1_ONE_BYTE_EDITED: {
+    readonly description: string;
+    readonly matcher: "Bash";
+    readonly hook: "COMMAND=\"$CLAUDE_TOOL_INPUT\"\nBLOCKED_PATTERNS=(\n  'rm -rf /'\n  'rm -rf ~'\n  'chmod 777'\n  'curl.*|.*sh'\n  'wget.*|.*sh'\n  'eval.*\\$'\n  'base64.*-d.*|.*sh'\n  ':(){:|:&};:'\n)\nfor pattern in \"${BLOCKED_PATTERNS[@]}\"; do\n  if echo \"$COMMAND\" | grep -qE \"$pattern\"; then\n    echo \"BLOCKED: Dangerous command pattern detected: $pattern\"\n    exit 2\n  fi\ndone\nexit 0";
+};
+//# sourceMappingURL=claude-hook-ownership.d.ts.map

package/dist/lib/__fixtures__/claude-hook-ownership.js

@@ -0,0 +1,96 @@
+// biome-ignore-all lint/suspicious/noTemplateCurlyInString: verbatim shell `${…}` and the literal Claude `${CLAUDE_PROJECT_DIR}` placeholder — never JS templates.
+/**
+ * Shared frozen ownership fixtures for the SkillGuard Claude PreToolUse guard.
+ *
+ * This module is the single source of truth for the byte/structure-exact
+ * identities the read-only recognition layer (Slice 2) classifies against:
+ *
+ * - the managed settings-entry handler group the Slice-3 writer installs;
+ * - the four v0 legacy cohort objects, copied verbatim from
+ *   `templates/security-hooks/claude-settings-security.json` (never normalized);
+ * - the marker/placeholder/hash constants.
+ *
+ * Everything here is data only (frozen literals plus a couple of pure
+ * builders) so it is deterministic, host-independent, and trivially testable.
+ * The production classifier imports the constants and the legacy cohort from
+ * here; the tests additionally use the one-byte-edited and duplicate variants.
+ */
+/** Exact managed marker prefix on the settings handler's `statusMessage`. */
+export const MANAGED_STATUS_PREFIX = "javi-forge-global-pretooluse:v1:sha256:";
+/** Placeholder the canonical hash normalizes the live asset SHA token to. */
+export const ASSET_SHA_PLACEHOLDER = "<ASSET_SHA256>";
+/** Whole-file SHA-256 of the retained v0 legacy scaffold template. */
+export const LEGACY_FILE_SHA256 = "b4638222ecddc2daac6ec3339596d853a626906bbd1233d789d80a319325c68d";
+/** Exact managed matcher — an exact-name alternative list, never a wildcard. */
+export const MANAGED_MATCHER = "Bash|PowerShell|Read|Write|Edit";
+/** Single project-local MJS argument, kept as a literal placeholder path. */
+export const MANAGED_ASSET_ARG = "${CLAUDE_PROJECT_DIR}/.claude/hooks/javi-forge-skillguard-pre-tool-use.mjs";
+/** Exact asset filename under `.claude/hooks/`. */
+export const ASSET_NAME = "javi-forge-skillguard-pre-tool-use.mjs";
+/** Exact first-line comment marking the managed asset. */
+export const ASSET_MANAGED_MARKER = "// javi-forge-managed: claude-pretooluse v1";
+/**
+ * A representative live asset SHA. Used only to build marker `statusMessage`
+ * values in fixtures; the canonical settings identity is invariant under this
+ * value (Decision ②), which the rotation-invariance test proves.
+ */
+export const SAMPLE_ASSET_SHA256 = "78be7e6613c012280b7ad17886462ba166b63ebd031e34565d757b3a0796d7cc";
+/** Build the exact marker `statusMessage` for a given live asset SHA. */
+export function managedStatusMessage(assetSha = SAMPLE_ASSET_SHA256) {
+    return `${MANAGED_STATUS_PREFIX}${assetSha}`;
+}
+/** Build the exact managed command handler for a given live asset SHA. */
+export function managedHandler(assetSha = SAMPLE_ASSET_SHA256) {
+    return {
+        type: "command",
+        command: "node",
+        args: [MANAGED_ASSET_ARG],
+        timeout: 30,
+        statusMessage: managedStatusMessage(assetSha),
+    };
+}
+/** Build the exact managed matcher group for a given live asset SHA. */
+export function managedGroup(assetSha = SAMPLE_ASSET_SHA256) {
+    return { matcher: MANAGED_MATCHER, hooks: [managedHandler(assetSha)] };
+}
+/** Build a valid settings container around the given hook sections. */
+export function settingsContainer(pre = [], post = [], extra = {}) {
+    return { ...extra, hooks: { PreToolUse: pre, PostToolUse: post } };
+}
+// --- v0 legacy cohort (verbatim from the retained template) ------------------
+export const L1_BASH_DANGEROUS = {
+    matcher: "Bash",
+    hook: "COMMAND=\"$CLAUDE_TOOL_INPUT\"\nBLOCKED_PATTERNS=(\n  'rm -rf /'\n  'rm -rf ~'\n  'chmod 777'\n  'curl.*|.*sh'\n  'wget.*|.*sh'\n  'eval.*\\$'\n  'base64.*-d.*|.*sh'\n  ':(){:|:&};:'\n)\nfor pattern in \"${BLOCKED_PATTERNS[@]}\"; do\n  if echo \"$COMMAND\" | grep -qE \"$pattern\"; then\n    echo \"BLOCKED: Dangerous command pattern detected: $pattern\"\n    exit 2\n  fi\ndone\nexit 0",
+    description: "Block dangerous shell commands (rm -rf /, chmod 777, pipe-to-sh, fork bombs)",
+};
+export const L2_BASH_SENSITIVE_READ = {
+    matcher: "Bash",
+    hook: "COMMAND=\"$CLAUDE_TOOL_INPUT\"\nSENSITIVE_PATHS=(\n  '.env'\n  '.env.local'\n  '.env.production'\n  'credentials'\n  'secrets'\n  '.ssh'\n  '.gnupg'\n  '.aws/credentials'\n)\nfor path in \"${SENSITIVE_PATHS[@]}\"; do\n  if echo \"$COMMAND\" | grep -qE \"(cat|less|head|tail|bat|read).*$path\"; then\n    echo \"BLOCKED: Attempt to read sensitive file: $path\"\n    exit 2\n  fi\ndone\nexit 0",
+    description: "Prevent reading sensitive files (.env, credentials, SSH keys)",
+};
+export const L3_WRITE_EDIT_PROTECTED = {
+    matcher: "Write|Edit",
+    hook: "INPUT=\"$CLAUDE_TOOL_INPUT\"\nPROTECTED_FILES=(\n  '.env'\n  '.env.production'\n  'credentials.json'\n  'serviceAccountKey.json'\n  '.ssh/'\n  '.gnupg/'\n)\nfor pf in \"${PROTECTED_FILES[@]}\"; do\n  if echo \"$INPUT\" | grep -q \"$pf\"; then\n    echo \"BLOCKED: Cannot modify protected file: $pf\"\n    exit 2\n  fi\ndone\nexit 0",
+    description: "Prevent writing to credential and secret files",
+};
+export const L4_BASH_POST_SECRET_SCAN = {
+    matcher: "Bash",
+    hook: "OUTPUT=\"$CLAUDE_TOOL_OUTPUT\"\nLEAK_PATTERNS=(\n  'AKIA[0-9A-Z]{16}'\n  'ghp_[A-Za-z0-9]{36}'\n  'sk_live_[0-9a-zA-Z]{24,}'\n  'xox[baprs]-[0-9a-zA-Z-]+'\n  '-----BEGIN.*PRIVATE KEY-----'\n)\nfor pattern in \"${LEAK_PATTERNS[@]}\"; do\n  if echo \"$OUTPUT\" | grep -qE \"$pattern\"; then\n    echo \"WARNING: Command output may contain secrets. Review carefully.\"\n    exit 0\n  fi\ndone\nexit 0",
+    description: "Warn if command output contains potential secrets",
+};
+/** The complete four-object v0 legacy cohort in committed order (L1–L3 Pre, L4 Post). */
+export const LEGACY_COHORT = {
+    L1: L1_BASH_DANGEROUS,
+    L2: L2_BASH_SENSITIVE_READ,
+    L3: L3_WRITE_EDIT_PROTECTED,
+    L4: L4_BASH_POST_SECRET_SCAN,
+};
+/**
+ * One-byte-edited L1: a single trailing character removed from the description.
+ * It must fail deep-structural equality against the exact cohort member.
+ */
+export const L1_ONE_BYTE_EDITED = {
+    ...L1_BASH_DANGEROUS,
+    description: "Block dangerous shell commands (rm -rf /, chmod 777, pipe-to-sh, fork bombs)".slice(0, -1),
+};
+//# sourceMappingURL=claude-hook-ownership.js.map

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/claude-hook-manager.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Read-only Claude PreToolUse ownership manager (Slice 2). Its only filesystem
+ * surface is `safeReadFile` plus one isolated no-follow `lstat` helper — it never
+ * writes, creates directories, or makes backups. It owns asset byte
+ * classification (always recompute the full-file SHA), the settings read+parse
+ * wrapper (identity delegated to `claude-hook-settings`), the Node `>=22` check,
+ * and the component-level doctor. Install/repair are declared but unimplemented
+ * Slice-3 seams — Slice 3 GROWS this file, it does not relocate this code.
+ */
+import { type ClaudeHookComponentState, type SettingsClassification, type SettingsIdentityManifest } from "./claude-hook-settings.js";
+declare const COVERAGE: readonly ["Bash", "PowerShell", "Read", "Write", "Edit"];
+export interface AssetManifestEntry {
+    name: string;
+    version: number;
+    sha256: string;
+    historical: string[];
+}
+export interface Manifest {
+    asset: AssetManifestEntry;
+    settingsEntries: SettingsIdentityManifest;
+}
+export interface ClaudeHookAssetClassification {
+    state: ClaudeHookComponentState;
+    version?: number;
+    sha256?: string;
+    detail?: string;
+}
+export interface ClaudeHookDoctorReport {
+    healthy: boolean;
+    settings: {
+        state: ClaudeHookComponentState;
+        version?: number;
+        canonicalSha256?: string;
+        detail: string;
+    };
+    asset: {
+        state: ClaudeHookComponentState;
+        version?: number;
+        sha256?: string;
+        detail: string;
+    };
+    node: {
+        available: boolean;
+        version?: string;
+        satisfiesMinimum: boolean;
+    };
+    matcherExact: boolean;
+    commandShapeExact: boolean;
+    assetSettingsConsistent: boolean;
+    coverage: typeof COVERAGE;
+    hostResidual: string;
+    remediation: readonly string[];
+}
+/**
+ * Classify the asset into one of nine states from observed bytes only. Never
+ * trusts a claimed hash: the full-file SHA is always recomputed and compared to
+ * the manifest.
+ */
+export declare function classifyAssetState(assetPath: string, manifest: Manifest): Promise<ClaudeHookAssetClassification>;
+/** Read `.claude/settings.json` and classify it (lstat → bounded read → legacy SHA → pure classifier). */
+export declare function classifySettingsFile(settingsPath: string, currentAssetSha: string, identities: SettingsIdentityManifest): Promise<SettingsClassification>;
+/** Node availability + `>=22` check from a version string (no spawn). */
+export declare function detectNode(nodeVersion: string | undefined): {
+    available: boolean;
+    version?: string;
+    satisfiesMinimum: boolean;
+};
+/**
+ * Assemble the read-only component-level doctor report (no writes). `healthy` is
+ * exactly: both components `managed-current`, matcher and command shape exact,
+ * Node `>=22`. `assetSettingsConsistent` is a reported advisory, NOT part of it.
+ */
+export declare function doctorClaudePreToolUse(projectDir: string, options?: {
+    manifest?: Manifest;
+    nodeVersion?: string;
+}): Promise<ClaudeHookDoctorReport>;
+export interface ClaudeHookMutationResult {
+    ok: boolean;
+    changed: string[];
+    backups: string[];
+    errors: string[];
+}
+export declare function installClaudePreToolUse(_projectDir: string): Promise<ClaudeHookMutationResult>;
+export declare function repairClaudePreToolUse(_projectDir: string, _options?: {
+    force?: boolean;
+}): Promise<ClaudeHookMutationResult>;
+export {};
+//# sourceMappingURL=claude-hook-manager.d.ts.map