javi-forge 1.7.1 → 1.9.0

package/assets/hooks/commit-msg

@@ -0,0 +1,30 @@
+#!/bin/bash
+# Commit-msg: block AI attribution in commit messages
+set -e
+COMMIT_MSG_FILE="$1"
+COMMIT_MSG=$(cat "$COMMIT_MSG_FILE")
+
+AI_PATTERNS=(
+  "co-authored-by:.*claude" "co-authored-by:.*anthropic"
+  "co-authored-by:.*gpt" "co-authored-by:.*openai"
+  "co-authored-by:.*copilot" "co-authored-by:.*gemini"
+  "co-authored-by:.*\\bai\\b"
+  "made by claude" "made by gpt" "made by ai"
+  "generated by claude" "generated by gpt" "generated by ai"
+  "written by claude" "written by ai"
+  "claude code" "claude opus" "claude sonnet" "claude haiku"
+  "gpt-4" "gpt-3" "chatgpt"
+  "@anthropic.com" "@openai.com"
+)
+
+for pattern in "${AI_PATTERNS[@]}"; do
+  if echo "$COMMIT_MSG" | grep -iqE "$pattern"; then
+    echo ""
+    echo "COMMIT BLOCKED: AI Attribution Detected"
+    echo "  Pattern: $pattern"
+    echo "  Remove AI attribution. You are the sole author."
+    echo ""
+    exit 1
+  fi
+done
+exit 0

package/assets/hooks/manifest.json

@@ -0,0 +1,32 @@
+{
+  "pre-commit": {
+    "version": 1,
+    "sha256": "811f34ce57517e129554bc9c09801a66c0207332cd3e7f2950db43a40580e914",
+    "historical": [
+      {
+        "sha256": "811f34ce57517e129554bc9c09801a66c0207332cd3e7f2950db43a40580e914",
+        "firstCommit": "5587b3b9b9ed3c86809c0a3d89a850dd2bce7e1a"
+      }
+    ]
+  },
+  "pre-push": {
+    "version": 1,
+    "sha256": "7de58640aeef33085a49f31f1d9d0c8bacde0069d6d3265ae41aa8d3cd14d7a5",
+    "historical": [
+      {
+        "sha256": "7de58640aeef33085a49f31f1d9d0c8bacde0069d6d3265ae41aa8d3cd14d7a5",
+        "firstCommit": "5587b3b9b9ed3c86809c0a3d89a850dd2bce7e1a"
+      }
+    ]
+  },
+  "commit-msg": {
+    "version": 1,
+    "sha256": "1c23a60cd4ba7f6bc666da400b5d2971c4294782c8d9ce41543e7815de11a1d6",
+    "historical": [
+      {
+        "sha256": "1c23a60cd4ba7f6bc666da400b5d2971c4294782c8d9ce41543e7815de11a1d6",
+        "firstCommit": "5587b3b9b9ed3c86809c0a3d89a850dd2bce7e1a"
+      }
+    ]
+  }
+}

package/assets/hooks/pre-commit

@@ -0,0 +1,15 @@
+#!/bin/bash
+# Pre-commit: quick CI check via javi-forge
+# To skip: git commit --no-verify
+set -e
+echo "PRE-COMMIT: Running quick check..."
+if command -v javi-forge &>/dev/null; then
+  javi-forge ci --quick --no-docker --no-security --no-ci-ghagga
+else
+  npx javi-forge ci --quick --no-docker --no-security --no-ci-ghagga
+fi || {
+  echo ""
+  echo "Quick check FAILED — fix the issues above before committing."
+  echo "To skip: git commit --no-verify"
+  exit 1
+}

package/assets/hooks/pre-push

@@ -0,0 +1,20 @@
+#!/bin/bash
+# Pre-push: full CI simulation via javi-forge
+# To skip: git push --no-verify
+set -e
+if ! docker info &>/dev/null; then
+  echo "PRE-PUSH: Docker is not running."
+  echo "  Start Docker or use: git push --no-verify"
+  exit 1
+fi
+echo "PRE-PUSH: Running CI simulation..."
+if command -v javi-forge &>/dev/null; then
+  javi-forge ci
+else
+  npx javi-forge ci
+fi || {
+  echo ""
+  echo "CI FAILED — push aborted. Fix the issues above."
+  echo "To skip: git push --no-verify"
+  exit 1
+}

package/dist/cli/dispatch/ci.js

@@ -15,11 +15,22 @@ export async function handleCi(cli, ctx) {
     // Sub-command: javi-forge ci init → install git hooks
     if (cli.input[1] === "init") {
         const { installCIHooks } = await import("../../commands/ci.js");
-        const { installed, errors } = await installCIHooks(process.cwd());
+        const { installed, upgraded, backups, errors, states } = await installCIHooks(process.cwd(), {
+            force: cli.flags.force === true,
+        });
+        for (const backup of backups) {
+            console.log(`⚠ Backed up the previous hook → ${backup}`);
+        }
         if (installed.length > 0) {
             console.log(`✓ Installed git hooks: ${installed.join(", ")}`);
             console.log("  Hooks call javi-forge ci (with npx fallback)");
         }
+        // Upgrades are reported DISTINCTLY from fresh installs: replacing an
+        // older javi-forge hook is not the same event as writing a new one.
+        for (const hook of upgraded) {
+            const was = states.find((entry) => entry.name === hook)?.state;
+            console.log(`↑ Upgraded ${hook}${was === undefined ? "" : ` (was ${was})`}`);
+        }
         for (const err of errors) {
             console.error(`✗ ${err}`);
         }

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    tdd init          Install TDD-enforcing pre-commit hook (auto-detects stack)\n    tdd pipeline      Install TDD pipeline pre-push hook (--mode strict|warn)\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\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 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 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    tdd init          Install TDD-enforcing pre-commit hook (auto-detects stack)\n    tdd pipeline      Install TDD pipeline pre-push hook (--mode strict|warn)\n    analyze           Run repoforge skills analysis\n    doctor            Show health report\n    workflow show     Render a workflow graph as ASCII (--template <name> or file path)\n    workflow validate Validate project state against a workflow graph\n    workflow list     List available workflows and built-in templates\n    plugin add        Install a plugin from GitHub (org/repo)\n    plugin remove     Remove an installed plugin\n    plugin list       List installed plugins\n    plugin search     Search the plugin registry\n    plugin validate   Validate a local plugin directory\n    plugin sync       Auto-detect and wire installed plugins\n    plugin export     Export plugin to Agent Skills spec format (skills.json)\n    plugin export     --codex: Export plugin to Codex-compatible TOML subagent files\n    plugin export-skills  Generate aggregated skills.json from all installed plugins\n    plugin export-skills global  Generate global skills.json from all globally installed plugins\n    plugin import     Import an Agent Skills spec package as a javi-forge plugin\n    skills doctor     Show skills health report (add --deep for conflict detection)\n    skills budget     Show token cost of loaded skills (add -b N for custom budget)\n    skills score      Score a skill on quality dimensions (completeness, clarity, testability, token-efficiency)\n    skills benchmark  Benchmark a skill with structural quality checks\n    skills auto       Auto-detect project stack and suggest/install matching AI skills\n    skills auto-install  Alias for skills auto\n    skill publish     Package a skill directory for marketplace distribution (generates plugin.json)\n    security baseline   Create security baseline from current audit findings\n    security check      Check for regressions against baseline (exits non-zero if found)\n    security update     Re-snapshot baseline (acknowledge current vulns)\n    security allowlist  Add all current findings to the allowlist (suppress in future checks)\n    llms-txt          Generate AI-friendly llms.txt for current project\n\n  Options\n    --dry-run       Preview changes without writing files\n    --stack         Project stack (node, python, go, rust, java-gradle, java-maven, elixir)\n    --ci            CI provider (github, gitlab, woodpecker)\n    --memory        Memory module (engram, obsidian-brain, memory-simple, none)\n    --project-name  Project name (skips name prompt)\n    --ghagga        Enable GHAGGA review system\n    --mock          Enable mock-first mode (no real API keys needed)\n    --local-ai      Include local AI dev stack (Ollama + Docker Compose)\n    --batch         Non-interactive mode (auto-proceed, no keyboard input)\n    --deep          Enable deep analysis (conflict + duplicate detection)\n    --budget, -b    Token budget limit for skills (default: 8000)\n    --skills-dir    Custom skills directory path\n    --author        Author name for skill publish\n    --repo          Repository URL for skill publish\n    --version       Show version\n    --help          Show this help\n\n  CI options (javi-forge ci)\n    --quick         Lint + compile only (fast, for pre-commit)\n    --shell         Open interactive shell in CI container\n    --detect        Show detected stack and exit\n    --config PATH   Load ordered CI runners from a versioned config file\n                    (default discovery: .javi-forge/ci.yaml)\n    --stack STACK   Force a single explicit stack (single-stack repos only \u2014\n                    insufficient for hybrid repos; use --config instead)\n    --no-docker     Run commands natively (no Docker)\n    --no-ci-ghagga  Skip GHAGGA review\n    --no-security   Skip Semgrep security scan\n    --timeout N     Per-step timeout in seconds (default: 600)\n\n  CI hooks (javi-forge ci init)\n    Install git hooks that call javi-forge ci.\n    No files copied \u2014 hooks reference the global CLI.\n    Existing hooks javi-forge did not write are refused, never clobbered.\n    --force         Overwrite a foreign or locally modified hook. The previous\n                    content is copied to a .bak sibling first; if that backup\n                    cannot be written, the hook is left untouched. Symlinked\n                    hook paths are refused even with --force.\n\n  Examples\n    $ javi-forge\n    $ javi-forge init --dry-run\n    $ javi-forge init --stack node --ci github\n    $ javi-forge ci\n    $ javi-forge ci init\n    $ javi-forge ci init --force\n    $ javi-forge tdd init\n    $ javi-forge ci --quick\n    $ javi-forge ci --no-ci-ghagga --no-security\n    $ javi-forge ci --no-docker\n    $ javi-forge ci --shell\n    $ javi-forge ci --config .javi-forge/ci.yaml\n    $ javi-forge analyze\n    $ javi-forge doctor\n    $ javi-forge plugin add mapbox/agent-skills\n    $ javi-forge plugin list\n";
 export declare const FLAGS_SCHEMA: {
     readonly dryRun: {
         readonly type: "boolean";
@@ -78,6 +78,10 @@ export declare const FLAGS_SCHEMA: {
         readonly type: "number";
         readonly default: 600;
     };
+    readonly force: {
+        readonly type: "boolean";
+        readonly default: false;
+    };
     readonly minSeverity: {
         readonly type: "string";
         readonly default: "low";

package/dist/cli/help.js

@@ -80,6 +80,11 @@ export const HELP_TEXT = `
   CI hooks (javi-forge ci init)
     Install git hooks that call javi-forge ci.
     No files copied — hooks reference the global CLI.
+    Existing hooks javi-forge did not write are refused, never clobbered.
+    --force         Overwrite a foreign or locally modified hook. The previous
+                    content is copied to a .bak sibling first; if that backup
+                    cannot be written, the hook is left untouched. Symlinked
+                    hook paths are refused even with --force.
 
   Examples
     $ javi-forge
@@ -87,6 +92,7 @@ export const HELP_TEXT = `
     $ javi-forge init --stack node --ci github
     $ javi-forge ci
     $ javi-forge ci init
+    $ javi-forge ci init --force
     $ javi-forge tdd init
     $ javi-forge ci --quick
     $ javi-forge ci --no-ci-ghagga --no-security
@@ -117,6 +123,8 @@ export const FLAGS_SCHEMA = {
     ciGhagga: { type: "boolean", default: true },
     security: { type: "boolean", default: true },
     timeout: { type: "number", default: 600 },
+    // ci init: overwrite a foreign / locally modified hook (backs it up first)
+    force: { type: "boolean", default: false },
     // Security check flags
     minSeverity: { type: "string", default: "low" },
     staleDays: { type: "number", default: 30 },

package/dist/commands/ci.d.ts

@@ -77,8 +77,59 @@ export interface ResolveRunnerOptions {
  */
 export declare function resolveCIRunners(projectDir: string, options?: ResolveRunnerOptions): Promise<ResolvedRunners>;
 export declare function runCI(options: CIOptions, onStep: CIStepCallback): Promise<void>;
-export declare function installCIHooks(projectDir: string): Promise<{
+/**
+ * Classification of an existing `.git/hooks/<name>` before anything is written
+ * (design D6). Every state has exactly one write policy, so no hook is ever
+ * overwritten without a decision.
+ */
+export declare const HOOK_STATE: {
+    readonly ABSENT: "absent";
+    readonly MANAGED_CURRENT: "managed-current";
+    readonly MANAGED_OUTDATED: "managed-outdated";
+    readonly MANAGED_EDITED: "managed-edited";
+    readonly LEGACY_V0: "legacy-v0";
+    readonly FOREIGN: "foreign";
+    readonly SYMLINK: "symlink";
+    /** Exists but is not a regular file (directory, fifo, device) — never forceable. */
+    readonly NOT_A_FILE: "not-a-file";
+};
+export type HookState = (typeof HOOK_STATE)[keyof typeof HOOK_STATE];
+export interface HookHistoricalEntry {
+    sha256: string;
+    firstCommit: string;
+}
+export interface HookManifestEntry {
+    version: number;
+    sha256: string;
+    historical: HookHistoricalEntry[];
+}
+export interface HookStateReport {
+    name: string;
+    state: HookState;
+}
+export interface InstallHooksOptions {
+    /** Overwrite `foreign` / `managed-edited` hooks, backing them up first. */
+    force?: boolean;
+}
+export interface InstallHooksResult {
     installed: string[];
+    /** Hooks that were `managed-outdated` or `legacy-v0` and got REPLACED. */
+    upgraded: string[];
+    backups: string[];
     errors: string[];
-}>;
+    states: HookStateReport[];
+}
+/**
+ * Pure classification of hook CONTENT (D6 steps 1-5).
+ *
+ * The hash input is the body BELOW the marker block — the shebang stays in the
+ * body, the two marker lines are removed — so a version bump alone does not
+ * invalidate installed hooks. Lines are split on `\n` WITHOUT stripping a
+ * trailing `\r`: a CRLF-converted file fails the `$`-anchored marker regex,
+ * takes the unmarked path and classifies `foreign`, which is correct — it no
+ * longer matches anything released. The hash CLAIMED by the marker is never
+ * trusted; classification always recomputes against the shipped manifest.
+ */
+export declare function classifyHookContent(content: string, hookName: string, entry: HookManifestEntry): HookState;
+export declare function installCIHooks(projectDir: string, options?: InstallHooksOptions): Promise<InstallHooksResult>;
 //# sourceMappingURL=ci.d.ts.map

package/dist/commands/ci.js

@@ -1,6 +1,9 @@
 import { spawn } from "node:child_process";
+import { createHash } from "node:crypto";
+import { constants } from "node:fs";
 import path from "node:path";
 import fs from "fs-extra";
+import { HOOK_ASSETS_DIR } from "../constants.js";
 import { CI_STACKS, findCIConfig, loadCIConfig, } from "../lib/ci-config.js";
 import { refreshContextDir } from "../lib/context.js";
 import { ensureImage, isDockerAvailable, openShell, runInContainer, } from "../lib/docker.js";
@@ -680,121 +683,343 @@ async function runGhagga(projectDir) {
 // =============================================================================
 // CI Hooks Installation
 // =============================================================================
-const PRE_COMMIT_HOOK = `#!/bin/bash
-# Pre-commit: quick CI check via javi-forge
-# To skip: git commit --no-verify
-set -e
-echo "PRE-COMMIT: Running quick check..."
-if command -v javi-forge &>/dev/null; then
-  javi-forge ci --quick --no-docker --no-security --no-ci-ghagga
-else
-  npx javi-forge ci --quick --no-docker --no-security --no-ci-ghagga
-fi || {
-  echo ""
-  echo "Quick check FAILED — fix the issues above before committing."
-  echo "To skip: git commit --no-verify"
-  exit 1
-}
-`;
-const PRE_PUSH_HOOK = `#!/bin/bash
-# Pre-push: full CI simulation via javi-forge
-# To skip: git push --no-verify
-set -e
-if ! docker info &>/dev/null; then
-  echo "PRE-PUSH: Docker is not running."
-  echo "  Start Docker or use: git push --no-verify"
-  exit 1
-fi
-echo "PRE-PUSH: Running CI simulation..."
-if command -v javi-forge &>/dev/null; then
-  javi-forge ci
-else
-  npx javi-forge ci
-fi || {
-  echo ""
-  echo "CI FAILED — push aborted. Fix the issues above."
-  echo "To skip: git push --no-verify"
-  exit 1
-}
-`;
-const COMMIT_MSG_HOOK = `#!/bin/bash
-# Commit-msg: block AI attribution in commit messages
-set -e
-COMMIT_MSG_FILE="$1"
-COMMIT_MSG=$(cat "$COMMIT_MSG_FILE")
-
-AI_PATTERNS=(
-  "co-authored-by:.*claude" "co-authored-by:.*anthropic"
-  "co-authored-by:.*gpt" "co-authored-by:.*openai"
-  "co-authored-by:.*copilot" "co-authored-by:.*gemini"
-  "co-authored-by:.*\\\\bai\\\\b"
-  "made by claude" "made by gpt" "made by ai"
-  "generated by claude" "generated by gpt" "generated by ai"
-  "written by claude" "written by ai"
-  "claude code" "claude opus" "claude sonnet" "claude haiku"
-  "gpt-4" "gpt-3" "chatgpt"
-  "@anthropic.com" "@openai.com"
-)
-
-for pattern in "\${AI_PATTERNS[@]}"; do
-  if echo "$COMMIT_MSG" | grep -iqE "$pattern"; then
-    echo ""
-    echo "COMMIT BLOCKED: AI Attribution Detected"
-    echo "  Pattern: $pattern"
-    echo "  Remove AI attribution. You are the sole author."
-    echo ""
-    exit 1
-  fi
-done
-exit 0
-`;
-export async function installCIHooks(projectDir) {
+/**
+ * Classification of an existing `.git/hooks/<name>` before anything is written
+ * (design D6). Every state has exactly one write policy, so no hook is ever
+ * overwritten without a decision.
+ */
+export const HOOK_STATE = {
+    ABSENT: "absent",
+    MANAGED_CURRENT: "managed-current",
+    MANAGED_OUTDATED: "managed-outdated",
+    MANAGED_EDITED: "managed-edited",
+    LEGACY_V0: "legacy-v0",
+    FOREIGN: "foreign",
+    SYMLINK: "symlink",
+    /** Exists but is not a regular file (directory, fifo, device) — never forceable. */
+    NOT_A_FILE: "not-a-file",
+};
+const HOOK_NAMES = ["pre-commit", "pre-push", "commit-msg"];
+/** Bound on the `.bak.{epochMs}-{n}` ladder before a forced install gives up. */
+const BACKUP_RETRY_BUDGET = 8;
+const HOOK_MARKER_NAME_RE = /^# javi-forge-hook: (?<name>[a-z-]+) v(?<version>\d+)$/;
+const HOOK_MARKER_HASH_RE = /^# javi-forge-hash: sha256:[0-9a-f]{64}$/;
+function sha256Utf8(value) {
+    return createHash("sha256").update(Buffer.from(value, "utf8")).digest("hex");
+}
+function errorCode(error) {
+    return error && typeof error === "object" && "code" in error
+        ? String(error.code)
+        : "";
+}
+function isReleasedBody(entry, hash) {
+    return entry.historical.some((historical) => historical.sha256 === hash);
+}
+/**
+ * Pure classification of hook CONTENT (D6 steps 1-5).
+ *
+ * The hash input is the body BELOW the marker block — the shebang stays in the
+ * body, the two marker lines are removed — so a version bump alone does not
+ * invalidate installed hooks. Lines are split on `\n` WITHOUT stripping a
+ * trailing `\r`: a CRLF-converted file fails the `$`-anchored marker regex,
+ * takes the unmarked path and classifies `foreign`, which is correct — it no
+ * longer matches anything released. The hash CLAIMED by the marker is never
+ * trusted; classification always recomputes against the shipped manifest.
+ */
+export function classifyHookContent(content, hookName, entry) {
+    const lines = content.split("\n");
+    const marker = HOOK_MARKER_NAME_RE.exec(lines[1] ?? "");
+    if (lines[0]?.startsWith("#!") === true &&
+        marker?.groups !== undefined &&
+        HOOK_MARKER_HASH_RE.test(lines[2] ?? "")) {
+        // The marker name is BOUND to the slot: someone else's marker never
+        // grants us permission to overwrite this file.
+        if (marker.groups.name !== hookName) {
+            return HOOK_STATE.FOREIGN;
+        }
+        const body = [lines[0], ...lines.slice(3)].join("\n");
+        const computed = sha256Utf8(body);
+        if (computed === entry.sha256) {
+            return Number(marker.groups.version) === entry.version
+                ? HOOK_STATE.MANAGED_CURRENT
+                : HOOK_STATE.MANAGED_OUTDATED;
+        }
+        return isReleasedBody(entry, computed)
+            ? HOOK_STATE.MANAGED_OUTDATED
+            : HOOK_STATE.MANAGED_EDITED;
+    }
+    // Unmarked: the whole file is the candidate body. Bytes identical to the
+    // CURRENT asset still classify legacy-v0 — the marker, not the content, is
+    // what makes a hook managed.
+    return isReleasedBody(entry, sha256Utf8(content))
+        ? HOOK_STATE.LEGACY_V0
+        : HOOK_STATE.FOREIGN;
+}
+async function lstatOrNull(target) {
+    try {
+        return await fs.lstat(target);
+    }
+    catch (statErr) {
+        if (errorCode(statErr) === "ENOENT") {
+            return null;
+        }
+        throw statErr;
+    }
+}
+/** D6 step 0 — `lstat` first; only a regular file is ever read. */
+async function classifyHookPath(hookPath, hookName, entry) {
+    const stat = await lstatOrNull(hookPath);
+    if (stat === null) {
+        return HOOK_STATE.ABSENT;
+    }
+    if (stat.isSymbolicLink()) {
+        return HOOK_STATE.SYMLINK;
+    }
+    if (!stat.isFile()) {
+        return HOOK_STATE.NOT_A_FILE;
+    }
+    return classifyHookContent(await fs.readFile(hookPath, "utf8"), hookName, entry);
+}
+/**
+ * Splice the marker block in after the shebang. The body is written unmodified,
+ * so the round-trip is byte-exact and a re-install classifies `managed-current`
+ * with zero writes.
+ */
+function renderHook(body, hookName, entry) {
+    const [shebang, ...rest] = body.split("\n");
+    return [
+        shebang,
+        `# javi-forge-hook: ${hookName} v${entry.version}`,
+        `# javi-forge-hash: sha256:${sha256Utf8(body)}`,
+        ...rest,
+    ].join("\n");
+}
+/**
+ * What `--force` would ACTUALLY do with the backup, for the refusal message.
+ *
+ * Naming `.bak` unconditionally would be a lie whenever `.bak` is already taken
+ * by an earlier backup — and promising a backup at all would be a lie whenever
+ * the `.bak` path is a symlink or a directory, because `backupHook` refuses
+ * those EVEN WITH `--force`. The probe is `lstat`, never `pathExists`: the
+ * latter follows symlinks, so it reports `true` for a symlink to an existing
+ * file and `false` for a dangling one — both readings promise a backup that
+ * will never happen.
+ */
+async function describeBackupPlan(hookPath) {
+    const plain = `${hookPath}.bak`;
+    const existing = await lstatOrNull(plain);
+    if (existing !== null && (existing.isSymbolicLink() || !existing.isFile())) {
+        return `note that --force will REFUSE this hook until ${plain} is removed: it exists and is not a regular file, and javi-forge never writes a backup through it`;
+    }
+    const target = existing === null ? plain : `${plain}.<timestamp>`;
+    return `the current file is saved as ${target}`;
+}
+async function refusalMessage(hookPath, state) {
+    if (state === HOOK_STATE.SYMLINK) {
+        return `refusing to write through a symlink at ${hookPath}`;
+    }
+    if (state === HOOK_STATE.NOT_A_FILE) {
+        return `${hookPath} exists but is not a regular file. Refusing to overwrite; --force does not apply.`;
+    }
+    const plan = await describeBackupPlan(hookPath);
+    const reason = state === HOOK_STATE.MANAGED_EDITED
+        ? "carries a javi-forge marker but its contents were modified locally"
+        : "exists and is not a javi-forge hook (no marker, and its contents match no released javi-forge template)";
+    return `${hookPath} ${reason}. Refusing to overwrite. Inspect it, then re-run 'javi-forge ci init --force' (${plan}), or delete it.`;
+}
+/**
+ * Candidate backup targets, in order: `.bak`, `.bak.{epochMs}`, then
+ * `.bak.{epochMs}-{n}`. Bounded — a forced install never loops forever.
+ */
+function* backupCandidates(hookPath) {
+    yield `${hookPath}.bak`;
+    const stamp = Date.now();
+    yield `${hookPath}.bak.${stamp}`;
+    for (let n = 1; n <= BACKUP_RETRY_BUDGET; n += 1) {
+        yield `${hookPath}.bak.${stamp}-${n}`;
+    }
+}
+/**
+ * Copy the hook to a `.bak` sibling BEFORE a forced overwrite (D4).
+ *
+ * The backup path is a write target and gets the same protection as the hook
+ * path: every candidate is `lstat`ed and a symlink or non-regular file is
+ * refused EVEN WITH `--force`, otherwise a planted
+ * `pre-commit.bak -> ~/.ssh/authorized_keys` would turn `--force` into an
+ * arbitrary-write primitive. Creation goes through `COPYFILE_EXCL`, so
+ * "does it exist?" and "create it" are one atomic step: a backup can never
+ * clobber an earlier backup, same-millisecond collisions are impossible, and a
+ * symlink planted between the `lstat` and the copy loses the race. The copy is
+ * of the ORIGINAL BYTES — never a utf8 round-trip, which would corrupt a
+ * non-UTF8 hook — and the original mode is restored so a restored backup is
+ * still executable.
+ *
+ * Throwing here ABORTS the hook: the caller never reaches its write.
+ */
+async function backupHook(hookPath) {
+    const original = await fs.stat(hookPath);
+    for (const candidate of backupCandidates(hookPath)) {
+        const existing = await lstatOrNull(candidate);
+        if (existing !== null) {
+            if (existing.isSymbolicLink() || !existing.isFile()) {
+                throw new Error(`refusing to write the backup ${candidate}: it exists and is not a regular file. The hook was left unchanged.`);
+            }
+            // An earlier backup — keep it, try the next name.
+            continue;
+        }
+        try {
+            await fs.copyFile(hookPath, candidate, constants.COPYFILE_EXCL);
+        }
+        catch (copyErr) {
+            if (errorCode(copyErr) === "EEXIST") {
+                continue;
+            }
+            throw new Error(`could not write the backup ${candidate} (${errorCode(copyErr) || "unknown error"}): ${copyErr instanceof Error ? copyErr.message : String(copyErr)}. The hook was left unchanged.`);
+        }
+        await fs.chmod(candidate, original.mode);
+        return candidate;
+    }
+    throw new Error(`could not back up ${hookPath}: every candidate backup path is taken. The hook was left unchanged.`);
+}
+const MANIFEST_PATH = path.join(HOOK_ASSETS_DIR, "manifest.json");
+/** The mode every installed hook ends up with — git ignores a non-executable hook. */
+const HOOK_MODE = 0o755;
+const REINSTALL_REMEDY = "reinstall javi-forge (npm i -g javi-forge) or repack it from source";
+async function loadHookManifest() {
+    return (await fs.readJson(MANIFEST_PATH));
+}
+/**
+ * A broken INSTALL of javi-forge (missing, unreadable or truncated manifest) is
+ * an operator-actionable condition, not a stack trace: it surfaces as a named
+ * `errors[]` entry naming the path, the reason and the remedy. Without this the
+ * rejection escapes `installCIHooks` entirely and takes `handleCi` down with an
+ * unhandled promise rejection.
+ */
+function assertHookManifestEntry(entry, hookName) {
+    const problem = entry === undefined || entry === null
+        ? `has no "${hookName}" entry`
+        : typeof entry.sha256 !== "string" ||
+            typeof entry.version !== "number" ||
+            !Array.isArray(entry.historical)
+            ? `has a malformed "${hookName}" entry (expected version:number, sha256:string, historical:array)`
+            : "";
+    if (problem !== "") {
+        throw new Error(`${MANIFEST_PATH} ${problem}. The javi-forge install is incomplete; ${REINSTALL_REMEDY}.`);
+    }
+}
+/**
+ * Bring an already-current hook back to mode 0755 WITHOUT writing bytes.
+ *
+ * The chmod is skipped when the mode already matches, so the common path does
+ * no syscall beyond the `lstat`; when it does run, `chmod` changes `ctime` only
+ * — `mtime` and the contents are untouched, so the zero-write idempotence
+ * contract survives. The path was classified as a regular file moments earlier;
+ * the residual TOCTOU window is the one documented for the write path itself.
+ */
+async function repairHookMode(hookPath) {
+    const stat = await lstatOrNull(hookPath);
+    if (stat !== null && (stat.mode & 0o777) !== HOOK_MODE) {
+        await fs.chmod(hookPath, HOOK_MODE);
+    }
+}
+/**
+ * The hook body as SHIPPED. There is no inline copy of these templates any
+ * more: `assets/hooks/<name>` is the single source, hashed by the manifest and
+ * asserted present in the published tarball by the packaging check.
+ */
+async function readHookBody(hookName) {
+    return await fs.readFile(path.join(HOOK_ASSETS_DIR, hookName), "utf8");
+}
+export async function installCIHooks(projectDir, options = {}) {
+    const force = options.force === true;
+    const empty = { installed: [], upgraded: [], backups: [], states: [] };
     const gitDir = path.join(projectDir, ".git");
     if (!(await fs.pathExists(gitDir))) {
         return {
-            installed: [],
+            ...empty,
             errors: ["Not a git repository. Run git init first."],
         };
     }
     const hooksDir = path.join(gitDir, "hooks");
-    await fs.ensureDir(hooksDir);
-    const hooks = [
-        { name: "pre-commit", content: PRE_COMMIT_HOOK },
-        { name: "pre-push", content: PRE_PUSH_HOOK },
-        { name: "commit-msg", content: COMMIT_MSG_HOOK },
-    ];
+    let manifest;
+    try {
+        await fs.ensureDir(hooksDir);
+    }
+    catch (e) {
+        return {
+            ...empty,
+            errors: [
+                `could not create ${hooksDir} (${errorCode(e) || "unknown error"}): ${e instanceof Error ? e.message : String(e)}. No hook was installed.`,
+            ],
+        };
+    }
+    try {
+        manifest = await loadHookManifest();
+    }
+    catch (e) {
+        return {
+            ...empty,
+            errors: [
+                `could not read ${MANIFEST_PATH} (${errorCode(e) || "unknown error"}): ${e instanceof Error ? e.message : String(e)}. The javi-forge install is incomplete; ${REINSTALL_REMEDY}.`,
+            ],
+        };
+    }
     const installed = [];
+    const upgraded = [];
+    const backups = [];
     const errors = [];
-    for (const hook of hooks) {
-        const hookPath = path.join(hooksDir, hook.name);
+    const states = [];
+    for (const name of HOOK_NAMES) {
+        const hookPath = path.join(hooksDir, name);
+        const entry = manifest[name];
         try {
-            // Refuse to follow symlinks. .git/hooks/<name> as a symlink to a
-            // sensitive file (e.g., ~/.ssh/authorized_keys) would otherwise be
-            // clobbered by writeFile. lstat reports the link, not the target.
-            let isSymlink = false;
-            try {
-                const stat = await fs.lstat(hookPath);
-                isSymlink = stat.isSymbolicLink();
+            assertHookManifestEntry(entry, name);
+            const state = await classifyHookPath(hookPath, name, entry);
+            states.push({ name, state });
+            if (state === HOOK_STATE.MANAGED_CURRENT) {
+                // Content is already correct, so nothing is REWRITTEN — but a hook
+                // stripped of its exec bit is dead weight (git skips it silently),
+                // so the mode is repaired in place. `chmod` leaves both the bytes
+                // and the mtime untouched, so idempotence still holds.
+                await repairHookMode(hookPath);
+                continue;
+            }
+            // A symlink or a non-regular path is refused ALWAYS — `--force` is
+            // consent to lose YOUR file, not permission to write through a link.
+            if (state === HOOK_STATE.SYMLINK || state === HOOK_STATE.NOT_A_FILE) {
+                throw new Error(await refusalMessage(hookPath, state));
             }
-            catch (statErr) {
-                const code = statErr && typeof statErr === "object" && "code" in statErr
-                    ? statErr.code
-                    : "";
-                if (code !== "ENOENT") {
-                    throw statErr;
+            if (state === HOOK_STATE.MANAGED_EDITED || state === HOOK_STATE.FOREIGN) {
+                if (!force) {
+                    throw new Error(await refusalMessage(hookPath, state));
                 }
-                // ENOENT is expected if the hook file doesn't exist yet.
+                // Backup FIRST. If it throws, the write below is never reached.
+                backups.push(await backupHook(hookPath));
+            }
+            const body = await readHookBody(name);
+            // The `mode` option applies ONLY when the file is CREATED: overwriting
+            // an existing 0644 hook would leave it non-executable and git would
+            // silently skip it. The chmod is therefore unconditional, on every
+            // write path, which also makes the mode independent of the umask.
+            await fs.writeFile(hookPath, renderHook(body, name, entry), {
+                mode: HOOK_MODE,
+            });
+            await fs.chmod(hookPath, HOOK_MODE);
+            // `upgraded` means "javi-forge content was replaced by newer
+            // javi-forge content". A forced overwrite of someone else's file is a
+            // fresh install, not an upgrade.
+            if (state === HOOK_STATE.MANAGED_OUTDATED ||
+                state === HOOK_STATE.LEGACY_V0) {
+                upgraded.push(name);
             }
-            if (isSymlink) {
-                throw new Error(`refusing to write through a symlink at ${hookPath}`);
+            else {
+                installed.push(name);
             }
-            await fs.writeFile(hookPath, hook.content, { mode: 0o755 });
-            installed.push(hook.name);
         }
         catch (e) {
-            errors.push(`${hook.name}: ${e instanceof Error ? e.message : String(e)}`);
+            errors.push(`${name}: ${e instanceof Error ? e.message : String(e)}`);
         }
     }
-    return { installed, errors };
+    return { installed, upgraded, backups, errors, states };
 }
 //# sourceMappingURL=ci.js.map

package/dist/constants.d.ts

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

package/dist/constants.js

@@ -11,6 +11,8 @@ export const MODULES_DIR = path.join(FORGE_ROOT, "modules");
 export const WORKFLOWS_DIR = path.join(FORGE_ROOT, "workflows");
 /** CI-local directory */
 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");
 /** Security hooks template directory */
 export const SECURITY_HOOKS_DIR = path.join(TEMPLATES_DIR, "security-hooks");
 /** Local AI stack template directory */

package/package.json

@@ -1,94 +1,95 @@
 {
-  "name": "javi-forge",
-  "version": "1.7.1",
-  "description": "Project scaffolding and AI-ready CI bootstrap",
-  "type": "module",
-  "bin": {
-    "javi-forge": "dist/index.js"
-  },
-  "scripts": {
-    "build": "tsc",
-    "dev": "tsx watch src/index.tsx",
-    "start": "node dist/index.js",
-    "typecheck": "tsc --noEmit",
-    "typecheck:test": "tsc --project tsconfig.test.json --noEmit",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "test:coverage": "vitest run --coverage",
-    "test:mutation": "stryker run",
-    "test:hooks": "bash ci-local/hooks/commit-msg.test.sh",
-    "lint": "biome check src/",
-    "lint:fix": "biome check --write src/",
-    "format": "biome format --write src/",
-    "validate": "pnpm typecheck && pnpm typecheck:test && pnpm lint && pnpm test",
-    "package:check": "npm pack --dry-run --json --cache /tmp/javi-forge-npm-pack-cache > /tmp/javi-forge-pack.json && node scripts/verify-package-contents.mjs /tmp/javi-forge-pack.json"
-  },
-  "files": [
-    "dist/**/*.js",
-    "dist/**/*.d.ts",
-    "!dist/__integration__/**",
-    "!dist/e2e/**",
-    "ci-local/",
-    "modules/",
-    "templates/",
-    "workflows/",
-    "lib/",
-    "README.md",
-    "LICENSE*",
-    ".gitignore.template"
-  ],
-  "author": "JNZader",
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/JNZader/javi-forge.git"
-  },
-  "engines": {
-    "node": ">=22"
-  },
-  "dependencies": {
-    "chalk": "^5.6.2",
-    "fs-extra": "^11.3.5",
-    "glob": "^13.0.6",
-    "ink": "^7.0.3",
-    "ink-spinner": "^5.0.0",
-    "meow": "^14.1.0",
-    "react": "^19.2.6",
-    "update-notifier": "^7.3.1",
-    "yaml": "^2.9.0"
-  },
-  "devDependencies": {
-    "@biomejs/biome": "^2.4.15",
-    "@semantic-release/changelog": "^6.0.3",
-    "@semantic-release/exec": "^7.1.0",
-    "@semantic-release/git": "^10.0.1",
-    "@semantic-release/github": "^12.0.8",
-    "@stryker-mutator/core": "^9.6.1",
-    "@stryker-mutator/typescript-checker": "^9.6.1",
-    "@stryker-mutator/vitest-runner": "^9.6.1",
-    "@types/fs-extra": "^11.0.4",
-    "@types/node": "^25.8.0",
-    "@types/react": "^19.2.14",
-    "@types/update-notifier": "^6.0.8",
-    "@vitest/coverage-v8": "^4.1.6",
-    "conventional-changelog-conventionalcommits": "^9.3.1",
-    "ink-testing-library": "^4.0.0",
-    "semantic-release": "^25.0.3",
-    "tsx": "^4.22.1",
-    "typescript": "^6.0.3",
-    "vite": "^8.0.13",
-    "vitest": "^4.1.6"
-  },
-  "pnpm": {
-    "overrides": {
-      "handlebars": "^4.7.9",
-      "picomatch": "^4.0.4",
-      "brace-expansion": "^5.0.5",
-      "lodash": "^4.18.0",
-      "lodash-es": "^4.18.0",
-      "fast-uri": "^3.1.2",
-      "postcss": "^8.5.10",
-      "vite": "^8.0.5"
-    }
-  }
+	"name": "javi-forge",
+	"version": "1.9.0",
+	"description": "Project scaffolding and AI-ready CI bootstrap",
+	"type": "module",
+	"bin": {
+		"javi-forge": "dist/index.js"
+	},
+	"scripts": {
+		"build": "tsc",
+		"dev": "tsx watch src/index.tsx",
+		"start": "node dist/index.js",
+		"typecheck": "tsc --noEmit",
+		"typecheck:test": "tsc --project tsconfig.test.json --noEmit",
+		"test": "vitest run",
+		"test:watch": "vitest",
+		"test:coverage": "vitest run --coverage",
+		"test:mutation": "stryker run",
+		"test:hooks": "bash ci-local/hooks/commit-msg.test.sh",
+		"lint": "biome check src/",
+		"lint:fix": "biome check --write src/",
+		"format": "biome format --write src/",
+		"validate": "pnpm typecheck && pnpm typecheck:test && pnpm lint && pnpm test",
+		"package:check": "npm pack --dry-run --json --cache /tmp/javi-forge-npm-pack-cache > /tmp/javi-forge-pack.json && node scripts/verify-package-contents.mjs /tmp/javi-forge-pack.json"
+	},
+	"files": [
+		"dist/**/*.js",
+		"dist/**/*.d.ts",
+		"!dist/__integration__/**",
+		"!dist/e2e/**",
+		"assets/",
+		"ci-local/",
+		"modules/",
+		"templates/",
+		"workflows/",
+		"lib/",
+		"README.md",
+		"LICENSE*",
+		".gitignore.template"
+	],
+	"author": "JNZader",
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/JNZader/javi-forge.git"
+	},
+	"engines": {
+		"node": ">=22"
+	},
+	"dependencies": {
+		"chalk": "^5.6.2",
+		"fs-extra": "^11.3.5",
+		"glob": "^13.0.6",
+		"ink": "^7.0.3",
+		"ink-spinner": "^5.0.0",
+		"meow": "^14.1.0",
+		"react": "^19.2.6",
+		"update-notifier": "^7.3.1",
+		"yaml": "^2.9.0"
+	},
+	"devDependencies": {
+		"@biomejs/biome": "^2.4.15",
+		"@semantic-release/changelog": "^6.0.3",
+		"@semantic-release/exec": "^7.1.0",
+		"@semantic-release/git": "^10.0.1",
+		"@semantic-release/github": "^12.0.8",
+		"@stryker-mutator/core": "^9.6.1",
+		"@stryker-mutator/typescript-checker": "^9.6.1",
+		"@stryker-mutator/vitest-runner": "^9.6.1",
+		"@types/fs-extra": "^11.0.4",
+		"@types/node": "^25.8.0",
+		"@types/react": "^19.2.14",
+		"@types/update-notifier": "^6.0.8",
+		"@vitest/coverage-v8": "^4.1.6",
+		"conventional-changelog-conventionalcommits": "^9.3.1",
+		"ink-testing-library": "^4.0.0",
+		"semantic-release": "^25.0.3",
+		"tsx": "^4.22.1",
+		"typescript": "^6.0.3",
+		"vite": "^8.0.13",
+		"vitest": "^4.1.6"
+	},
+	"pnpm": {
+		"overrides": {
+			"handlebars": "^4.7.9",
+			"picomatch": "^4.0.4",
+			"brace-expansion": "^5.0.5",
+			"lodash": "^4.18.0",
+			"lodash-es": "^4.18.0",
+			"fast-uri": "^3.1.2",
+			"postcss": "^8.5.10",
+			"vite": "^8.0.5"
+		}
+	}
 }