javi-forge 1.24.0 → 1.25.1

package/dist/cli/dispatch/ci.js

@@ -70,9 +70,14 @@ 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, upgraded, backups, errors, states } = await installCIHooks(process.cwd(), {
+        const { installed, upgraded, backups, errors, states, notes } = await installCIHooks(process.cwd(), {
             force: cli.flags.force === true,
         });
+        // Migration notes (e.g. "legacy javi-forge hooksPath removed") come first:
+        // they explain a config change the operator did not explicitly ask for.
+        for (const note of notes) {
+            console.log(`ℹ ${note}`);
+        }
         for (const backup of backups) {
             console.log(`⚠ Backed up the previous hook → ${backup}`);
         }

package/dist/cli/dispatch/tdd.d.ts

@@ -2,9 +2,12 @@
  * `javi-forge tdd <init|pipeline>` handler.
  *
  * Console-only (no Ink, no React, no CIContextProvider).
- * Lazy-loads ./commands/tdd.js or ./commands/tdd-pipeline.js INSIDE the function
- * to preserve cold-start performance — heavy command modules MUST NOT be
- * eager-imported at the top of this file.
+ *
+ * hook-consolidation S3: the handlers no longer WRITE `.git/hooks` themselves.
+ * They flip the `hooks.*.tdd` flag in `.javi-forge/ci.yaml` and delegate the
+ * hook install to the hardened `installCIHooks` — the single writer of
+ * `.git/hooks`. Heavy modules are lazy-imported INSIDE the function to preserve
+ * cold-start performance.
  */
 import type { CLI } from "./types.js";
 export declare function handleTdd(cli: CLI): Promise<void>;

package/dist/cli/dispatch/tdd.js

@@ -2,43 +2,74 @@
  * `javi-forge tdd <init|pipeline>` handler.
  *
  * Console-only (no Ink, no React, no CIContextProvider).
- * Lazy-loads ./commands/tdd.js or ./commands/tdd-pipeline.js INSIDE the function
- * to preserve cold-start performance — heavy command modules MUST NOT be
- * eager-imported at the top of this file.
+ *
+ * hook-consolidation S3: the handlers no longer WRITE `.git/hooks` themselves.
+ * They flip the `hooks.*.tdd` flag in `.javi-forge/ci.yaml` and delegate the
+ * hook install to the hardened `installCIHooks` — the single writer of
+ * `.git/hooks`. Heavy modules are lazy-imported INSIDE the function to preserve
+ * cold-start performance.
  */
+/** Surface an installCIHooks result to the console (notes → backups → installed
+ * → upgraded → errors), matching the `ci init` output contract. */
+function reportInstall(result) {
+    for (const note of result.notes) {
+        console.log(`ℹ ${note}`);
+    }
+    for (const backup of result.backups) {
+        console.log(`⚠ Backed up the previous hook → ${backup}`);
+    }
+    if (result.installed.length > 0) {
+        console.log(`✓ Installed git hooks: ${result.installed.join(", ")}`);
+    }
+    for (const hook of result.upgraded) {
+        const was = result.states.find((entry) => entry.name === hook)?.state;
+        console.log(`↑ Upgraded ${hook}${was === undefined ? "" : ` (was ${was})`}`);
+    }
+    for (const err of result.errors) {
+        console.error(`✗ ${err}`);
+    }
+}
 export async function handleTdd(cli) {
-    if (cli.input[1] === "init") {
-        const { installTddHooks } = await import("../../commands/tdd.js");
-        const { installed, errors } = await installTddHooks(process.cwd());
-        if (installed.length > 0) {
-            console.log(`\u2713 Installed TDD hooks: ${installed.join(", ")}`);
-            console.log("  Pre-commit hook enforces tests must pass before commit");
-        }
-        for (const err of errors) {
-            console.error(`\u2717 ${err}`);
-        }
-        process.exit(errors.length > 0 ? 1 : 0);
-    }
-    else if (cli.input[1] === "pipeline") {
-        const { installTddPipelineHook } = await import("../../commands/tdd-pipeline.js");
+    const sub = cli.input[1];
+    const force = cli.flags.force === true;
+    if (sub === "init") {
+        const { setHookFeature } = await import("../../lib/ci-config.js");
+        const { installCIHooks } = await import("../../commands/ci.js");
+        // Install FIRST: installCIHooks writes generic static shims and does not
+        // depend on the tdd flag (the flag is read at hook-RUN time). Only once the
+        // managed hook is actually in place do we flip the config — otherwise a
+        // refused install (foreign hook / husky core.hooksPath) would leave ci.yaml
+        // claiming tdd:true while no managed hook exists.
+        const result = await installCIHooks(process.cwd(), { force });
+        reportInstall(result);
+        if (result.errors.length > 0)
+            process.exit(1);
+        const configPath = await setHookFeature(process.cwd(), "pre-commit", "tdd", true);
+        console.log(`✓ Enabled TDD in ${configPath} (hooks.pre-commit.tdd: true)`);
+        console.log("  The pre-commit hook now runs the stack test command via the dispatcher.");
+        process.exit(0);
+    }
+    else if (sub === "pipeline") {
         const mode = cli.flags.mode === "warn" ? "warn" : "strict";
-        const result = await installTddPipelineHook(process.cwd(), mode);
-        if (result.installed.length > 0) {
-            console.log(`\u2713 Installed TDD pipeline hook: ${result.installed.join(", ")} [${result.mode}]`);
-            console.log(`  Pre-push hook enforces TDD pipeline (${result.mode} mode)`);
-        }
-        for (const skip of result.skipped) {
-            console.log(`\u26A0 ${skip}`);
-        }
-        for (const err of result.errors) {
-            console.error(`\u2717 ${err}`);
-        }
-        process.exit(result.errors.length > 0 ? 1 : 0);
+        const { setHookFeature } = await import("../../lib/ci-config.js");
+        const { installCIHooks } = await import("../../commands/ci.js");
+        // Install FIRST (see `init` above): never leave the config ahead of a
+        // refused install.
+        const result = await installCIHooks(process.cwd(), { force });
+        reportInstall(result);
+        if (result.errors.length > 0)
+            process.exit(1);
+        const configPath = await setHookFeature(process.cwd(), "pre-push", "tdd", mode);
+        console.log(`✓ Enabled TDD pipeline in ${configPath} (hooks.pre-push.tdd: ${mode})`);
+        console.log(mode === "warn"
+            ? "  The pre-push hook runs tests as an ADVISORY section (never blocks)."
+            : "  The pre-push hook BLOCKS the push when tests fail.");
+        process.exit(0);
     }
     else {
         console.error("Usage: javi-forge tdd <command>");
-        console.error("  init      Install TDD-enforcing pre-commit hook");
-        console.error("  pipeline  Install TDD pipeline pre-push hook (--mode strict|warn)");
+        console.error("  init      Enable the TDD pre-commit section and install the managed hooks");
+        console.error("  pipeline  Enable the TDD pre-push section (--mode strict|warn)");
         process.exit(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          Install TDD-enforcing pre-commit hook (auto-detects stack)\n    tdd pipeline      Install TDD pipeline pre-push hook (--mode strict|warn)\n    hooks run         Run a git hook's composed sections (pre-commit | pre-push)\n    analyze           Run repoforge skills analysis\n    doctor            Show health report\n    workflow show     Render a workflow graph as ASCII (--template <name> or file path)\n    workflow validate Validate project state against a workflow graph\n    workflow list     List available workflows and built-in templates\n    plugin add        Install a plugin from GitHub (org/repo)\n    plugin remove     Remove an installed plugin\n    plugin list       List installed plugins\n    plugin search     Search the plugin registry\n    plugin validate   Validate a local plugin directory\n    plugin sync       Auto-detect and wire installed plugins\n    plugin export     Export plugin to Agent Skills spec format (skills.json)\n    plugin export     --codex: Export plugin to Codex-compatible TOML subagent files\n    plugin export-skills  Generate aggregated skills.json from all installed plugins\n    plugin export-skills global  Generate global skills.json from all globally installed plugins\n    plugin import     Import an Agent Skills spec package as a javi-forge plugin\n    skills doctor     Show skills health report (add --deep for conflict detection)\n    skills budget     Show token cost of loaded skills (add -b N for custom budget)\n    skills score      Score a skill on quality dimensions (completeness, clarity, testability, token-efficiency)\n    skills benchmark  Benchmark a skill with structural quality checks\n    skills auto       Auto-detect project stack and suggest/install matching AI skills\n    skills auto-install  Alias for skills auto\n    skill publish     Package a skill directory for marketplace distribution (generates plugin.json)\n    security baseline   Create security baseline from current audit findings\n    security check      Check for regressions against baseline (exits non-zero if found)\n    security update     Re-snapshot baseline (acknowledge current vulns)\n    security allowlist  Add all current findings to the allowlist (suppress in future checks)\n    llms-txt          Generate AI-friendly llms.txt for current project\n\n  Options\n    --dry-run       Preview changes without writing files\n    --stack         Project stack (node, python, go, rust, java-gradle, java-maven, elixir)\n    --ci            CI provider (github, gitlab, woodpecker)\n    --memory        Memory module (engram, obsidian-brain, memory-simple, none)\n    --project-name  Project name (skips name prompt)\n    --ghagga        Enable GHAGGA review system\n    --mock          Enable mock-first mode (no real API keys needed)\n    --local-ai      Include local AI dev stack (Ollama + Docker Compose)\n    --batch         Non-interactive mode (auto-proceed, no keyboard input)\n    --deep          Enable deep analysis (conflict + duplicate detection)\n    --budget, -b    Token budget limit for skills (default: 8000)\n    --skills-dir    Custom skills directory path\n    --author        Author name for skill publish\n    --repo          Repository URL for skill publish\n    --version       Show version\n    --help          Show this help\n\n  CI options (javi-forge ci)\n    --quick         Lint + compile only (fast, for pre-commit)\n    --shell         Open interactive shell in CI container\n    --detect        Show detected stack and exit\n    --config PATH   Load ordered CI runners from a versioned config file\n                    (default discovery: .javi-forge/ci.yaml)\n    --stack STACK   Force a single explicit stack (single-stack repos only \u2014\n                    insufficient for hybrid repos; use --config instead)\n    --no-docker     Run commands natively (no Docker)\n    --no-ci-ghagga  Skip GHAGGA review\n    --no-security   Skip Semgrep security scan\n    --timeout N     Per-step timeout in seconds (default: 600)\n\n  CI hooks (javi-forge ci init)\n    Install git hooks that call javi-forge ci.\n    No files copied \u2014 hooks reference the global CLI.\n    Existing hooks javi-forge did not write are refused, never clobbered.\n    --force         Overwrite a foreign or locally modified hook. The previous\n                    content is copied to a .bak sibling first; if that backup\n                    cannot be written, the hook is left untouched. Symlinked\n                    hook paths are refused even with --force.\n\n  Examples\n    $ javi-forge\n    $ javi-forge init --dry-run\n    $ javi-forge init --stack node --ci github\n    $ javi-forge ci\n    $ javi-forge ci init\n    $ javi-forge ci init --force\n    $ javi-forge tdd init\n    $ javi-forge ci --quick\n    $ javi-forge ci --no-ci-ghagga --no-security\n    $ javi-forge ci --no-docker\n    $ javi-forge ci --shell\n    $ javi-forge ci --config .javi-forge/ci.yaml\n    $ javi-forge ci validate\n    $ javi-forge ci --help\n    $ javi-forge analyze\n    $ javi-forge doctor\n    $ javi-forge plugin add mapbox/agent-skills\n    $ javi-forge plugin list\n";
+export declare const HELP_TEXT = "\n  Usage\n    $ javi-forge [command] [options]\n\n  Commands\n    init              Bootstrap a new project (default)\n    ci                Run CI simulation (lint + compile + test + security + ghagga)\n    ci validate       Validate .javi-forge/ci.yaml without running anything\n    ci init           Install git hooks that call javi-forge ci\n    tdd init          Enable the TDD pre-commit section + install managed hooks\n    tdd pipeline      Enable the TDD pre-push section (--mode strict|warn)\n    hooks run         Run a git hook's composed sections (pre-commit | pre-push)\n    analyze           Run repoforge skills analysis\n    doctor            Show health report\n    workflow show     Render a workflow graph as ASCII (--template <name> or file path)\n    workflow validate Validate project state against a workflow graph\n    workflow list     List available workflows and built-in templates\n    plugin add        Install a plugin from GitHub (org/repo)\n    plugin remove     Remove an installed plugin\n    plugin list       List installed plugins\n    plugin search     Search the plugin registry\n    plugin validate   Validate a local plugin directory\n    plugin sync       Auto-detect and wire installed plugins\n    plugin export     Export plugin to Agent Skills spec format (skills.json)\n    plugin export     --codex: Export plugin to Codex-compatible TOML subagent files\n    plugin export-skills  Generate aggregated skills.json from all installed plugins\n    plugin export-skills global  Generate global skills.json from all globally installed plugins\n    plugin import     Import an Agent Skills spec package as a javi-forge plugin\n    skills doctor     Show skills health report (add --deep for conflict detection)\n    skills budget     Show token cost of loaded skills (add -b N for custom budget)\n    skills score      Score a skill on quality dimensions (completeness, clarity, testability, token-efficiency)\n    skills benchmark  Benchmark a skill with structural quality checks\n    skills auto       Auto-detect project stack and suggest/install matching AI skills\n    skills auto-install  Alias for skills auto\n    skill publish     Package a skill directory for marketplace distribution (generates plugin.json)\n    security baseline   Create security baseline from current audit findings\n    security check      Check for regressions against baseline (exits non-zero if found)\n    security update     Re-snapshot baseline (acknowledge current vulns)\n    security allowlist  Add all current findings to the allowlist (suppress in future checks)\n    llms-txt          Generate AI-friendly llms.txt for current project\n\n  Options\n    --dry-run       Preview changes without writing files\n    --stack         Project stack (node, python, go, rust, java-gradle, java-maven, elixir)\n    --ci            CI provider (github, gitlab, woodpecker)\n    --memory        Memory module (engram, obsidian-brain, memory-simple, none)\n    --project-name  Project name (skips name prompt)\n    --ghagga        Enable GHAGGA review system\n    --mock          Enable mock-first mode (no real API keys needed)\n    --local-ai      Include local AI dev stack (Ollama + Docker Compose)\n    --batch         Non-interactive mode (auto-proceed, no keyboard input)\n    --deep          Enable deep analysis (conflict + duplicate detection)\n    --budget, -b    Token budget limit for skills (default: 8000)\n    --skills-dir    Custom skills directory path\n    --author        Author name for skill publish\n    --repo          Repository URL for skill publish\n    --version       Show version\n    --help          Show this help\n\n  CI options (javi-forge ci)\n    --quick         Lint + compile only (fast, for pre-commit)\n    --shell         Open interactive shell in CI container\n    --detect        Show detected stack and exit\n    --config PATH   Load ordered CI runners from a versioned config file\n                    (default discovery: .javi-forge/ci.yaml)\n    --stack STACK   Force a single explicit stack (single-stack repos only \u2014\n                    insufficient for hybrid repos; use --config instead)\n    --no-docker     Run commands natively (no Docker)\n    --no-ci-ghagga  Skip GHAGGA review\n    --no-security   Skip Semgrep security scan\n    --timeout N     Per-step timeout in seconds (default: 600)\n\n  CI hooks (javi-forge ci init)\n    Install git hooks that call javi-forge ci.\n    No files copied \u2014 hooks reference the global CLI.\n    Existing hooks javi-forge did not write are refused, never clobbered.\n    --force         Overwrite a foreign or locally modified hook. The previous\n                    content is copied to a .bak sibling first; if that backup\n                    cannot be written, the hook is left untouched. Symlinked\n                    hook paths are refused even with --force.\n\n  Examples\n    $ javi-forge\n    $ javi-forge init --dry-run\n    $ javi-forge init --stack node --ci github\n    $ javi-forge ci\n    $ javi-forge ci init\n    $ javi-forge ci init --force\n    $ javi-forge tdd init\n    $ javi-forge ci --quick\n    $ javi-forge ci --no-ci-ghagga --no-security\n    $ javi-forge ci --no-docker\n    $ javi-forge ci --shell\n    $ javi-forge ci --config .javi-forge/ci.yaml\n    $ javi-forge ci validate\n    $ javi-forge ci --help\n    $ javi-forge analyze\n    $ javi-forge doctor\n    $ javi-forge plugin add mapbox/agent-skills\n    $ javi-forge plugin list\n";
 /**
  * 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

@@ -17,8 +17,8 @@ export const HELP_TEXT = `
     ci                Run CI simulation (lint + compile + test + security + ghagga)
     ci validate       Validate .javi-forge/ci.yaml without running anything
     ci init           Install git hooks that call javi-forge ci
-    tdd init          Install TDD-enforcing pre-commit hook (auto-detects stack)
-    tdd pipeline      Install TDD pipeline pre-push hook (--mode strict|warn)
+    tdd init          Enable the TDD pre-commit section + install managed hooks
+    tdd pipeline      Enable the TDD pre-push section (--mode strict|warn)
     hooks run         Run a git hook's composed sections (pre-commit | pre-push)
     analyze           Run repoforge skills analysis
     doctor            Show health report

package/dist/commands/ci.d.ts

@@ -212,6 +212,12 @@ export interface InstallHooksResult {
     backups: string[];
     errors: string[];
     states: HookStateReport[];
+    /**
+     * Informational messages from the hooksPath guard (D6) — e.g. the "legacy
+     * javi-forge hooksPath removed" note emitted when the migration path unsets
+     * a `ci-local/hooks` local value. NOT errors; surfaced to the operator.
+     */
+    notes: string[];
 }
 /**
  * Pure classification of hook CONTENT (D6 steps 1-5).

package/dist/commands/ci.js

@@ -1548,9 +1548,227 @@ async function repairHookMode(hookPath) {
 async function readHookBody(hookName) {
     return await fs.readFile(path.join(HOOK_ASSETS_DIR, hookName), "utf8");
 }
+/** The exact — and ONLY — value javi-forge itself ever wrote (git.ts:83). */
+const LEGACY_HOOKSPATH = "ci-local/hooks";
+/**
+ * Read a higher-scope `core.hooksPath` with `git config <scope> --get`.
+ *
+ * `--global`/`--system` reads return each scope's OWN value regardless of the
+ * local value, so a shadowing higher-scope hooksPath is visible with ZERO
+ * mutation. git exits 1 (no section / no config file) or 5 (key unset) for "no
+ * value" → `{ value: "" }`. ANY other failure is surfaced as `failed` so the
+ * guard can fail CLOSED: a blind spot on a possible shadow must never let the
+ * migration unset the local value and half-migrate the repo.
+ */
+async function readScopedHooksPath(projectDir, scope) {
+    try {
+        const { stdout } = await execFileAsync("git", ["config", scope, "--get", "core.hooksPath"], { cwd: projectDir });
+        return { value: stdout.trim() };
+    }
+    catch (e) {
+        const code = e.code;
+        if (code === 1 || code === 5) {
+            return { value: "" };
+        }
+        return { value: "", failed: e instanceof Error ? e.message : String(e) };
+    }
+}
+/**
+ * Read the LOCAL `core.hooksPath` with the SAME fail-closed discipline as
+ * {@link readScopedHooksPath} (JDA-001).
+ *
+ * git exits 1 (no section / no config file) or 5 (key unset) for a genuine "no
+ * value" → `{ value: "" }`, the safe fresh-install path. ANY OTHER failure
+ * (config lock, I/O error, a corrupt `.git/config`, a git fault) is surfaced as
+ * `failed` so the guard can REFUSE. Swallowing such a failure to `""` would be a
+ * FAIL-OPEN: a local value genuinely = `ci-local/hooks` that transiently fails
+ * to read would look like a fresh repo, so step 5 would never unset it and the
+ * shims would be installed into `.git/hooks` while the still-present local value
+ * keeps SHADOWING them — `installCIHooks` would report installed/upgraded while
+ * git runs the OLD ci-local bodies. An unknown-state local read must never be
+ * treated as a fresh install.
+ */
+async function readLocalHooksPath(projectDir) {
+    try {
+        const { stdout } = await execFileAsync("git", ["config", "--local", "--get", "core.hooksPath"], { cwd: projectDir });
+        return { value: stdout.trim() };
+    }
+    catch (e) {
+        const code = e.code;
+        if (code === 1 || code === 5) {
+            return { value: "" };
+        }
+        return { value: "", failed: e instanceof Error ? e.message : String(e) };
+    }
+}
+/**
+ * Read a WORKTREE-scoped `core.hooksPath` (JDA-002), which — with
+ * `extensions.worktreeConfig` enabled — ALSO shadows `.git/hooks`.
+ *
+ * The extension is checked FIRST for a load-bearing reason: when it is OFF, `git
+ * config --worktree` silently behaves like `--local` (verified), so reading it
+ * here would double-count the LOCAL value and refuse a valid legacy migration.
+ * It is a DISTINCT scope only when the extension is enabled, and only then does
+ * `--worktree --get` read from `$GIT_DIR/config.worktree` WITHOUT falling back to
+ * local. Gating on the extension also handles the multiple-worktree + extension-off
+ * case where `--worktree` errors out ("not enabled"): we never issue that read, so
+ * that specific error can never surface as a spurious refuse.
+ *
+ * Same fail-closed discipline as the scoped reads: exit 1/5 → genuine no value;
+ * any OTHER failure → `failed` so the guard REFUSES rather than fail open.
+ */
+async function readWorktreeHooksPath(projectDir) {
+    // Determine whether the worktree config extension is enabled.
+    let enabled = false;
+    try {
+        const { stdout } = await execFileAsync("git", ["config", "--bool", "--get", "extensions.worktreeConfig"], { cwd: projectDir });
+        enabled = stdout.trim() === "true";
+    }
+    catch (e) {
+        const code = e.code;
+        if (code === 1 || code === 5) {
+            // Extension unset/disabled → no DISTINCT worktree scope exists; the local
+            // read (step 3) already covers the --worktree==--local fallback. Treat as
+            // no worktree value, never a refuse.
+            return { value: "" };
+        }
+        // Cannot determine the extension state → fail CLOSED.
+        return { value: "", failed: e instanceof Error ? e.message : String(e) };
+    }
+    if (!enabled) {
+        return { value: "" };
+    }
+    try {
+        const { stdout } = await execFileAsync("git", ["config", "--worktree", "--get", "core.hooksPath"], { cwd: projectDir });
+        return { value: stdout.trim() };
+    }
+    catch (e) {
+        const code = e.code;
+        if (code === 1 || code === 5) {
+            return { value: "" };
+        }
+        return { value: "", failed: e instanceof Error ? e.message : String(e) };
+    }
+}
+/**
+ * The ATOMIC `core.hooksPath` guard (design D6). Runs BEFORE the install loop
+ * mutates anything.
+ *
+ * DETECT-BEFORE-MUTATE — steps 1-4 are pure reads; only step 5 writes (unset
+ * the legacy local value). EVERY refuse path returns `{ refuse }` having mutated
+ * NOTHING, so the repo is left in its EXACT prior state and can never land
+ * half-migrated (JDA-001 / JDA-008). The single write (`--local --unset`) and
+ * the subsequent shim install happen ONLY on the fully-validated success/force
+ * path.
+ */
+async function guardHooksPath(projectDir, hooksDir, manifest, force) {
+    // ── Step 1: classify the managed slots (pure read), exactly as the install
+    //   loop will. A manifest problem is NOT classified here — it surfaces
+    //   per-hook in the loop; an unclassifiable slot is treated as ABSENT (never
+    //   fabricate a foreign refusal from a manifest error).
+    const foreignSlots = [];
+    for (const name of HOOK_NAMES) {
+        const entry = manifest[name];
+        try {
+            assertHookManifestEntry(entry, name);
+        }
+        catch {
+            continue;
+        }
+        const state = await classifyHookPath(path.join(hooksDir, name), name, entry);
+        if (state === HOOK_STATE.FOREIGN) {
+            foreignSlots.push(name);
+        }
+    }
+    // ── Step 2: DETECT a shadowing higher-scope hooksPath via SCOPED reads (ZERO
+    //   mutation). A global/system value shadows .git/hooks the moment git
+    //   consults hooksPath, so installing there would be INERT — refuse rather
+    //   than fail open. Detected WITHOUT unsetting local, so a
+    //   `local-unset + global-present` half-migration is impossible.
+    for (const scope of ["--system", "--global"]) {
+        const probe = await readScopedHooksPath(projectDir, scope);
+        if (probe.failed !== undefined) {
+            return {
+                refuse: `could not read ${scope} git config core.hooksPath (${probe.failed}). Refusing to install: a higher-scope hooksPath could silently shadow .git/hooks and the hooks would not run. Resolve the git error and re-run.`,
+            };
+        }
+        if (probe.value !== "") {
+            const label = scope === "--global" ? "global" : "system";
+            return {
+                refuse: `a ${label} core.hooksPath='${probe.value}' would redirect git away from .git/hooks — the installed hooks would NOT run. Resolve it first (git config ${scope} --unset core.hooksPath) and re-run.`,
+            };
+        }
+    }
+    // ── Step 2b (JDA-002): a WORKTREE-scoped hooksPath (with
+    //   extensions.worktreeConfig enabled) ALSO shadows .git/hooks. Same
+    //   fail-closed handling: a non-1/5 read failure REFUSES rather than fail open.
+    const worktree = await readWorktreeHooksPath(projectDir);
+    if (worktree.failed !== undefined) {
+        return {
+            refuse: `could not read --worktree git config core.hooksPath (${worktree.failed}). Refusing to install: a worktree-scoped hooksPath could silently shadow .git/hooks and the hooks would not run. Resolve the git error and re-run.`,
+        };
+    }
+    if (worktree.value !== "") {
+        return {
+            refuse: `a worktree core.hooksPath='${worktree.value}' would redirect git away from .git/hooks — the installed hooks would NOT run. Resolve it first (git config --worktree --unset core.hooksPath) and re-run.`,
+        };
+    }
+    // Shadow reads now cover --global, --system and --worktree. The includeIf
+    // residual edge remains: a hooksPath injected only through a
+    // [includeIf "gitdir:…"] conditional include is NOT returned by
+    // --global/--system/--worktree --get and would surface only in an effective
+    // read — a documented residual edge, not covered by these scoped reads.
+    // ── Step 3: the LOCAL value. A foreign local manager (husky/lefthook/custom)
+    //   owns this repo's hooks; never hijack it. --force does NOT override (force
+    //   is consent to lose a file, not to seize another manager's config). The read
+    //   fails CLOSED (JDA-001): a non-1/5 failure REFUSES rather than mistake an
+    //   unreadable local value for a fresh repo and install over a shadowing value.
+    const localProbe = await readLocalHooksPath(projectDir);
+    if (localProbe.failed !== undefined) {
+        return {
+            refuse: `could not read --local git config core.hooksPath (${localProbe.failed}). Refusing to install: a local hooksPath could silently shadow .git/hooks and the installed hooks would not run. Resolve the git error and re-run.`,
+        };
+    }
+    const local = localProbe.value;
+    if (local !== "" && local !== LEGACY_HOOKSPATH) {
+        return {
+            refuse: `core.hooksPath is set to '${local}' — another hook manager owns this repo's hooks. javi-forge refuses to install or change it. Unset it yourself (git config --local --unset core.hooksPath) if you want javi-forge hooks.`,
+        };
+    }
+    const legacy = local === LEGACY_HOOKSPATH;
+    // ── Step 4: installability, ONLY on the migration path. Unsetting the legacy
+    //   value ACTIVATES whatever sits in .git/hooks; if a slot is FOREIGN without
+    //   --force, migrating now would activate a dormant foreign hook → ATOMIC
+    //   REFUSE, leave core.hooksPath SET, install NOTHING. When there is no legacy
+    //   value to unset, foreign slots are handled per-hook by the install loop as
+    //   before — nothing is being activated.
+    if (legacy && !force && foreignSlots.length > 0) {
+        const slot = foreignSlots[0];
+        return {
+            refuse: `core.hooksPath=${LEGACY_HOOKSPATH} would be removed, but .git/hooks/${slot} holds a foreign hook (a prior 'tdd init' or hand-written hook). Migrating now would activate it. Resolve it (delete/back it up) or re-run with --force.`,
+        };
+    }
+    // ── Step 5: ONLY NOW mutate. Every check passed (or --force). Unset the
+    //   legacy local value — the ONLY value javi-forge ever wrote, and only the
+    //   --local scope is ever touched — then let the caller install. The install
+    //   NEVER runs before steps 2 and 4.
+    if (legacy) {
+        await execFileAsync("git", ["config", "--local", "--unset", "core.hooksPath"], { cwd: projectDir });
+        return {
+            note: "legacy javi-forge hooksPath removed; hooks now live in .git/hooks",
+        };
+    }
+    return {};
+}
 export async function installCIHooks(projectDir, options = {}) {
     const force = options.force === true;
-    const empty = { installed: [], upgraded: [], backups: [], states: [] };
+    const empty = {
+        installed: [],
+        upgraded: [],
+        backups: [],
+        states: [],
+        notes: [],
+    };
     const gitDir = path.join(projectDir, ".git");
     if (!(await fs.pathExists(gitDir))) {
         return {
@@ -1587,6 +1805,19 @@ export async function installCIHooks(projectDir, options = {}) {
     const backups = [];
     const errors = [];
     const states = [];
+    const notes = [];
+    // The ATOMIC core.hooksPath guard (D6) is the SINGLE choke point shared by
+    // `ci init` and `init`. It runs DETECT-BEFORE-MUTATE: on refuse it has
+    // mutated nothing and we return without installing; on the success/force
+    // path it has already unset any legacy `ci-local/hooks` value and we
+    // proceed to install the shims.
+    const guard = await guardHooksPath(projectDir, hooksDir, manifest, force);
+    if ("refuse" in guard) {
+        return { ...empty, errors: [guard.refuse] };
+    }
+    if (guard.note !== undefined) {
+        notes.push(guard.note);
+    }
     for (const name of HOOK_NAMES) {
         const hookPath = path.join(hooksDir, name);
         const entry = manifest[name];
@@ -1631,6 +1862,6 @@ export async function installCIHooks(projectDir, options = {}) {
             errors.push(`${name}: ${e instanceof Error ? e.message : String(e)}`);
         }
     }
-    return { installed, upgraded, backups, errors, states };
+    return { installed, upgraded, backups, errors, states, notes };
 }
 //# sourceMappingURL=ci.js.map

package/dist/commands/hooks.d.ts

@@ -10,12 +10,15 @@
  * behavior); a config that FAILS to validate exits 1 — a broken config never
  * silently skips a gate.
  *
- * S1a scope: only the `ci` section has a body. The tdd/secrets/permissions/deps
- * sections have no factory yet (they land in S3/S4); an enabled-but-unregistered
- * feature is skipped by `composeSections` until its slice wires a factory.
+ * S1a/S3 scope: the `ci` and `tdd` sections have bodies. The
+ * secrets/permissions/deps sections have no factory yet (they land in S4); an
+ * enabled-but-unregistered feature is skipped by `composeSections` until its
+ * slice wires a factory.
  */
 import { type CIHooksConfig } from "../lib/ci-config.js";
+import type { Stack } from "../types/index.js";
 import { runCI } from "./ci.js";
+import { getTddTestCommand } from "./tdd.js";
 /** A single composable unit of hook work. */
 export interface HookSection {
     /** stable id — "secrets" | "permissions" | "tdd" | "deps" | "ci" */
@@ -41,6 +44,39 @@ export type HookName = "pre-commit" | "pre-push";
  * in later slices.
  */
 export declare function composeSections(name: HookName, config: CIHooksConfig | null, registry: SectionRegistry): HookSection[];
+/**
+ * Injectable seams for the `tdd` section. The section resolves the project's
+ * test command at HOOK-RUN time (never interpolated into a file), so the stack
+ * detector, the command resolver and the command runner are all overridable in
+ * tests. Every field defaults to the real implementation in `defaultRegistry`.
+ */
+export interface TddSectionDeps {
+    /** Only the stack + build tool are consumed — the wider CIStackInfo is fine. */
+    detectStack: (projectDir: string) => Promise<{
+        stackType: Stack;
+        buildTool: string;
+    }>;
+    resolveTestCmd: typeof getTddTestCommand;
+    runCommand: (cmd: string, projectDir: string) => Promise<{
+        ok: boolean;
+        detail?: string;
+    }>;
+    log: (msg: string) => void;
+}
+/**
+ * The `tdd` section: at hook-run time it detects the stack, resolves the stack
+ * test command and runs it. A null command (no test runner configured) is NOT a
+ * failure — it prints an honest skip notice and returns ok:true (parity with the
+ * old warning-only generated hook). A missing test runner must never block a
+ * commit or push. When the command resolves it runs and its exit code decides.
+ */
+export declare function tddSection(deps: TddSectionDeps): HookSection;
+/**
+ * The default section registry: the real `ci` and `tdd` factories. `tddDeps`
+ * overrides the tdd section's seams in tests (stack/command/runner); every
+ * omitted seam falls back to the real implementation.
+ */
+export declare function defaultRegistry(runCIImpl: typeof runCI, log: (msg: string) => void, tddDeps?: Partial<TddSectionDeps>): SectionRegistry;
 /** Resolve the parsed `hooks:` config for a project (null → default [ci]). */
 export declare function loadHooksConfig(projectDir: string): Promise<CIHooksConfig | null>;
 /** Injectable seams for tests; every field defaults to the real implementation. */

package/dist/commands/hooks.js

@@ -10,12 +10,15 @@
  * behavior); a config that FAILS to validate exits 1 — a broken config never
  * silently skips a gate.
  *
- * S1a scope: only the `ci` section has a body. The tdd/secrets/permissions/deps
- * sections have no factory yet (they land in S3/S4); an enabled-but-unregistered
- * feature is skipped by `composeSections` until its slice wires a factory.
+ * S1a/S3 scope: the `ci` and `tdd` sections have bodies. The
+ * secrets/permissions/deps sections have no factory yet (they land in S4); an
+ * enabled-but-unregistered feature is skipped by `composeSections` until its
+ * slice wires a factory.
  */
+import { spawn } from "node:child_process";
 import { findCIConfig, loadCIConfig, } from "../lib/ci-config.js";
-import { runCI } from "./ci.js";
+import { detectCIStack, runCI } from "./ci.js";
+import { getTddTestCommand } from "./tdd.js";
 /** Fixed cheap→expensive order per hook (deterministic is a feature). */
 const PRE_COMMIT_ORDER = ["secrets", "permissions", "tdd", "ci"];
 const PRE_PUSH_ORDER = ["deps", "tdd", "ci"];
@@ -114,8 +117,83 @@ function reportStep(step, log) {
     else if (step.status === "warning")
         log(`  ⚠ ${step.label}`);
 }
-function defaultRegistry(runCIImpl, log) {
-    return { ci: () => ciSection(runCIImpl, log) };
+/**
+ * Run a resolved test command through `bash -c`, matching the rest of the
+ * codebase's project-command idiom (`runStep` in ci.ts). `getTddTestCommand`
+ * only ever returns a fixed, controlled set of commands (`npm test`,
+ * `<buildTool> run test`, `pytest`, `go test ./...`) — never user input — so
+ * `bash -c` introduces no injection vector, and it fixes native Windows where
+ * `npm`/`pnpm`/`yarn` are `.cmd` shims that a shell-less `spawn` cannot exec
+ * (ENOENT). A non-zero exit or a spawn error is a blocking failure; a passing
+ * command is ok:true.
+ */
+function runTestCommand(cmd, projectDir) {
+    return new Promise((resolve) => {
+        const proc = spawn("bash", ["-c", cmd], {
+            cwd: projectDir,
+            stdio: "inherit",
+            env: { ...process.env, CI: "true" },
+        });
+        proc.on("close", (code) => resolve(code === 0
+            ? { ok: true }
+            : { ok: false, detail: `tests failed (exit ${code ?? "unknown"})` }));
+        proc.on("error", (e) => resolve({
+            ok: false,
+            detail: e instanceof Error ? e.message : String(e),
+        }));
+    });
+}
+/**
+ * The `tdd` section: at hook-run time it detects the stack, resolves the stack
+ * test command and runs it. A null command (no test runner configured) is NOT a
+ * failure — it prints an honest skip notice and returns ok:true (parity with the
+ * old warning-only generated hook). A missing test runner must never block a
+ * commit or push. When the command resolves it runs and its exit code decides.
+ */
+export function tddSection(deps) {
+    return {
+        id: "tdd",
+        blocking: true,
+        async run({ projectDir }) {
+            // A thrown detector / resolver / runner must NEVER propagate out of the
+            // section — an unhandled rejection would crash the hook (raw stack trace)
+            // and, for an advisory pre-push tdd:"warn", would BLOCK the push,
+            // violating the advisory-never-blocks invariant. Mirror ciSection: on a
+            // throw, report a blocking-mappable failure instead.
+            try {
+                const { stackType, buildTool } = await deps.detectStack(projectDir);
+                const testCmd = await deps.resolveTestCmd(stackType, buildTool, projectDir);
+                if (testCmd === null) {
+                    deps.log(`  ⓘ tdd: no test command detected for stack '${stackType}' — skipping (a missing test runner does not block).`);
+                    return { ok: true };
+                }
+                deps.log(`  ▶ tdd: ${testCmd}`);
+                return await deps.runCommand(testCmd, projectDir);
+            }
+            catch (e) {
+                return {
+                    ok: false,
+                    detail: e instanceof Error ? e.message : String(e),
+                };
+            }
+        },
+    };
+}
+/**
+ * The default section registry: the real `ci` and `tdd` factories. `tddDeps`
+ * overrides the tdd section's seams in tests (stack/command/runner); every
+ * omitted seam falls back to the real implementation.
+ */
+export function defaultRegistry(runCIImpl, log, tddDeps = {}) {
+    return {
+        ci: () => ciSection(runCIImpl, log),
+        tdd: () => tddSection({
+            detectStack: tddDeps.detectStack ?? detectCIStack,
+            resolveTestCmd: tddDeps.resolveTestCmd ?? getTddTestCommand,
+            runCommand: tddDeps.runCommand ?? runTestCommand,
+            log: tddDeps.log ?? log,
+        }),
+    };
 }
 /** Resolve the parsed `hooks:` config for a project (null → default [ci]). */
 export async function loadHooksConfig(projectDir) {

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

@@ -11,15 +11,17 @@ import type { StepFn } from "../types.js";
  */
 export declare const stepGitInit: StepFn;
 /**
- * Step 2: Configure git hooks path.
+ * Step 2: Install managed git hooks (D7 reconciliation).
  *
- * - Copies templates/ci-local/ → <project>/ci-local/ (no overwrite).
- * - chmod 0755 on hook files.
- * - Sets git config core.hooksPath to ci-local/hooks.
- * - Skips entirely when CI_LOCAL_DIR template is missing.
- * - Errors are swallowed and reported as status:"error" — never thrown.
+ * Init no longer copies `ci-local/` hook bodies into the project nor flips
+ * `core.hooksPath` — both were the pre-consolidation mechanism. It now delegates
+ * to `installCIHooks`, the SINGLE writer of `.git/hooks` and the choke point for
+ * the ATOMIC `core.hooksPath` guard (D6). A foreign/global hooksPath, or a
+ * dormant foreign slot, is REFUSED there with zero mutation and surfaced as an
+ * error here — init never overrides the user's hook manager.
  *
- * Extracted VERBATIM from src/commands/init.ts (PR 1 of 6).
+ * - dry-run: reports "would install managed hooks", calls nothing.
+ * - Errors are swallowed and reported as status:"error" — never thrown.
  */
 export declare const stepGitHooks: StepFn;
 //# sourceMappingURL=git.d.ts.map

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

@@ -1,6 +1,5 @@
 import path from "node:path";
 import fs from "fs-extra";
-import { CI_LOCAL_DIR } from "../../../constants.js";
 import { execFileAsync } from "../../../lib/exec.js";
 import { report } from "../report.js";
 /**
@@ -34,48 +33,46 @@ export const stepGitInit = async (ctx) => {
     }
 };
 /**
- * Step 2: Configure git hooks path.
+ * Step 2: Install managed git hooks (D7 reconciliation).
  *
- * - Copies templates/ci-local/ → <project>/ci-local/ (no overwrite).
- * - chmod 0755 on hook files.
- * - Sets git config core.hooksPath to ci-local/hooks.
- * - Skips entirely when CI_LOCAL_DIR template is missing.
- * - Errors are swallowed and reported as status:"error" — never thrown.
+ * Init no longer copies `ci-local/` hook bodies into the project nor flips
+ * `core.hooksPath` — both were the pre-consolidation mechanism. It now delegates
+ * to `installCIHooks`, the SINGLE writer of `.git/hooks` and the choke point for
+ * the ATOMIC `core.hooksPath` guard (D6). A foreign/global hooksPath, or a
+ * dormant foreign slot, is REFUSED there with zero mutation and surfaced as an
+ * error here — init never overrides the user's hook manager.
  *
- * Extracted VERBATIM from src/commands/init.ts (PR 1 of 6).
+ * - dry-run: reports "would install managed hooks", calls nothing.
+ * - Errors are swallowed and reported as status:"error" — never thrown.
  */
 export const stepGitHooks = async (ctx) => {
     const { projectDir, dryRun, onStep } = ctx;
     const stepId = "git-hooks";
-    report(onStep, stepId, "Configure git hooks path", "running");
+    const label = "Install git hooks";
+    report(onStep, stepId, label, "running");
+    if (dryRun) {
+        report(onStep, stepId, label, "done", "would install managed hooks");
+        return;
+    }
     try {
-        const ciLocalSrc = CI_LOCAL_DIR;
-        const ciLocalDest = path.join(projectDir, "ci-local");
-        if (await fs.pathExists(ciLocalSrc)) {
-            if (!dryRun) {
-                await fs.copy(ciLocalSrc, ciLocalDest, {
-                    overwrite: false,
-                    errorOnExist: false,
-                });
-                // Set core.hooksPath to ci-local/hooks
-                const hooksDir = path.join(ciLocalDest, "hooks");
-                if (await fs.pathExists(hooksDir)) {
-                    // Ensure hooks are executable
-                    const hookFiles = await fs.readdir(hooksDir);
-                    for (const hook of hookFiles) {
-                        await fs.chmod(path.join(hooksDir, hook), 0o755);
-                    }
-                    await execFileAsync("git", ["config", "core.hooksPath", "ci-local/hooks"], { cwd: projectDir });
-                }
-            }
-            report(onStep, stepId, "Configure git hooks path", "done", "ci-local/hooks");
-        }
-        else {
-            report(onStep, stepId, "Configure git hooks path", "skipped", "no ci-local dir");
+        // Lazy import: installCIHooks pulls in the CI command surface; keep it off
+        // the init cold-start path, exactly like the `ci init` dispatch branch.
+        const { installCIHooks } = await import("../../ci.js");
+        const { installed, upgraded, backups, errors, notes } = await installCIHooks(projectDir);
+        if (errors.length > 0) {
+            report(onStep, stepId, label, "error", errors.join("; "));
+            return;
         }
+        const detail = [
+            ...installed.map((h) => `installed ${h}`),
+            ...upgraded.map((h) => `upgraded ${h}`),
+            ...notes,
+            ...backups.map((b) => `backup ${b}`),
+        ].join("; ") || "managed hooks installed";
+        report(onStep, stepId, label, "done", detail);
     }
     catch (e) {
-        report(onStep, stepId, "Configure git hooks path", "error", String(e));
+        report(onStep, stepId, label, "error", String(e));
     }
 };
 //# sourceMappingURL=git.js.map

package/dist/commands/tdd.d.ts

@@ -1,21 +1,7 @@
 import type { Stack } from "../types/index.js";
-export interface TddHookResult {
-    installed: string[];
-    errors: string[];
-}
 /**
  * Resolve the correct test command for TDD hook based on stack and build tool.
  * Returns null if no test command can be determined.
  */
 export declare function getTddTestCommand(stack: Stack, buildTool: string, projectDir: string): Promise<string | null>;
-/**
- * Generate a TDD-enforcing pre-commit hook script.
- * If testCmd is null, generates a warning-only hook.
- */
-export declare function generateTddHook(testCmd: string | null, stack: Stack): string;
-/**
- * Install TDD pre-commit hook into .git/hooks/.
- * Detects the project stack automatically and generates the appropriate hook.
- */
-export declare function installTddHooks(projectDir: string): Promise<TddHookResult>;
 //# sourceMappingURL=tdd.d.ts.map

package/dist/commands/tdd.js

@@ -1,6 +1,5 @@
 import path from "node:path";
 import fs from "fs-extra";
-import { detectCIStack } from "./ci.js";
 // =============================================================================
 // Test command resolution
 // =============================================================================
@@ -30,91 +29,4 @@ export async function getTddTestCommand(stack, buildTool, projectDir) {
             return null;
     }
 }
-// =============================================================================
-// Hook generation
-// =============================================================================
-/**
- * Generate a TDD-enforcing pre-commit hook script.
- * If testCmd is null, generates a warning-only hook.
- */
-export function generateTddHook(testCmd, stack) {
-    if (!testCmd) {
-        return `#!/bin/bash
-# =============================================================================
-# TDD PRE-COMMIT: No test command detected for stack "${stack}"
-# =============================================================================
-# Install a test runner and re-run: javi-forge tdd init
-# =============================================================================
-
-echo "TDD HOOK: No test command configured for stack '${stack}' — skipping."
-exit 0
-`;
-    }
-    return `#!/bin/bash
-# =============================================================================
-# TDD PRE-COMMIT: Enforced test-driven development
-# =============================================================================
-# Flow: Tests MUST pass before commit is allowed.
-# Stack: ${stack} | Command: ${testCmd}
-# To skip: git commit --no-verify
-# =============================================================================
-
-set -e
-
-echo "TDD PRE-COMMIT: Running tests..."
-echo "  Stack: ${stack}"
-echo "  Command: ${testCmd}"
-echo ""
-
-${testCmd} || {
-    echo ""
-    echo "TDD FAILED — Tests did not pass."
-    echo "  Fix failing tests before committing."
-    echo "  To skip: git commit --no-verify"
-    exit 1
-}
-
-echo ""
-echo "TDD PASSED — All tests green. Commit allowed."
-`;
-}
-// =============================================================================
-// Hook installation
-// =============================================================================
-/**
- * Install TDD pre-commit hook into .git/hooks/.
- * Detects the project stack automatically and generates the appropriate hook.
- */
-export async function installTddHooks(projectDir) {
-    const gitDir = path.join(projectDir, ".git");
-    if (!(await fs.pathExists(gitDir))) {
-        return {
-            installed: [],
-            errors: ["Not a git repository. Run git init first."],
-        };
-    }
-    const hooksDir = path.join(gitDir, "hooks");
-    await fs.ensureDir(hooksDir);
-    // Detect stack
-    let stackInfo;
-    try {
-        stackInfo = await detectCIStack(projectDir);
-    }
-    catch {
-        return { installed: [], errors: ["Failed to detect project stack."] };
-    }
-    const testCmd = await getTddTestCommand(stackInfo.stackType, stackInfo.buildTool, projectDir);
-    const hookContent = generateTddHook(testCmd, stackInfo.stackType);
-    const installed = [];
-    const errors = [];
-    const hookPath = path.join(hooksDir, "pre-commit");
-    try {
-        await fs.writeFile(hookPath, hookContent, { mode: 0o755 });
-        installed.push("pre-commit");
-    }
-    catch (e) {
-        errors.push(`pre-commit: ${e instanceof Error ? e.message : String(e)}`);
-    }
-    return { installed, errors };
-}
 //# sourceMappingURL=tdd.js.map

package/dist/lib/ci-config.d.ts

@@ -144,6 +144,16 @@ export declare function parseCIConfig(rawYaml: string, source?: string): CIConfi
  * validation error throws — no config is ever silently ignored.
  */
 export declare function loadCIConfig(configPath: string): Promise<CIConfig>;
+/**
+ * Set a single `hooks.<hook>.<feature>` flag in a project's CI config, creating
+ * a minimal `version: 2` `.javi-forge/ci.yaml` when none exists. Existing
+ * content — runners, gates, other hooks, comments and formatting — is preserved
+ * via a YAML document round-trip (`parseDocument`), so this NEVER clobbers a
+ * hand-authored config. `hooks:` is a v2-only key, so the version is bumped to 2
+ * when a hook feature is written into an older document. Returns the path
+ * written. Fail-closed callers still validate on the next `loadCIConfig`.
+ */
+export declare function setHookFeature(projectDir: string, hook: "pre-commit" | "pre-push", feature: string, value: boolean | string): Promise<string>;
 /**
  * Discover the default CI config for a project directory.
  * Returns the config path, or null when the project has no config

package/dist/lib/ci-config.js

@@ -633,6 +633,39 @@ export async function loadCIConfig(configPath) {
     const raw = await fs.readFile(configPath, "utf-8");
     return parseCIConfig(raw, configPath);
 }
+/**
+ * Set a single `hooks.<hook>.<feature>` flag in a project's CI config, creating
+ * a minimal `version: 2` `.javi-forge/ci.yaml` when none exists. Existing
+ * content — runners, gates, other hooks, comments and formatting — is preserved
+ * via a YAML document round-trip (`parseDocument`), so this NEVER clobbers a
+ * hand-authored config. `hooks:` is a v2-only key, so the version is bumped to 2
+ * when a hook feature is written into an older document. Returns the path
+ * written. Fail-closed callers still validate on the next `loadCIConfig`.
+ */
+export async function setHookFeature(projectDir, hook, feature, value) {
+    const existing = await findCIConfig(projectDir);
+    const configPath = existing ?? path.join(projectDir, CI_CONFIG_CANDIDATES[0]);
+    const doc = existing
+        ? YAML.parseDocument(await fs.readFile(existing, "utf-8"))
+        : YAML.parseDocument("version: 2\n");
+    // Fail-closed: never write over a malformed config. A parse error means the
+    // document is only partially represented, so setIn + write would silently
+    // drop the unparseable remainder of a hand-authored file.
+    if (doc.errors.length > 0) {
+        throw new CIConfigError(doc.errors.map((e) => ({
+            path: "<document>",
+            message: `invalid YAML: ${e.message.split("\n")[0]}`,
+        })), configPath);
+    }
+    // `hooks:` requires version 2; bump an older/unset document in place.
+    if (doc.get("version") !== 2) {
+        doc.set("version", 2);
+    }
+    doc.setIn(["hooks", hook, feature], value);
+    await fs.ensureDir(path.dirname(configPath));
+    await fs.writeFile(configPath, doc.toString());
+    return configPath;
+}
 /**
  * Discover the default CI config for a project directory.
  * Returns the config path, or null when the project has no config

package/dist/types/index.d.ts

@@ -67,13 +67,6 @@ export interface DoctorSection {
 export interface DoctorResult {
     sections: DoctorSection[];
 }
-export type TddPipelineMode = "strict" | "warn";
-export interface TddPipelineResult {
-    installed: string[];
-    skipped: string[];
-    errors: string[];
-    mode: TddPipelineMode;
-}
 export interface PluginManifest {
     name: string;
     version: string;

package/package.json

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

package/dist/commands/tdd-pipeline.d.ts

@@ -1,17 +0,0 @@
-import type { Stack, TddPipelineMode, TddPipelineResult } from "../types/index.js";
-/**
- * Generate a TDD pipeline enforcement pre-push hook script.
- *
- * - strict: tests MUST pass or push is blocked (exit 1).
- * - warn:   tests are run and results shown, but push is never blocked.
- *
- * If testCmd is null, generates a skip-only hook regardless of mode.
- */
-export declare function generateTddPipelineHook(mode: TddPipelineMode, testCmd: string | null, stack: Stack): string;
-/**
- * Install TDD pipeline pre-push hook into .git/hooks/.
- * Detects the project stack automatically and generates the appropriate hook.
- * Backs up any existing pre-push hook to pre-push.bak.
- */
-export declare function installTddPipelineHook(projectDir: string, mode: TddPipelineMode): Promise<TddPipelineResult>;
-//# sourceMappingURL=tdd-pipeline.d.ts.map

package/dist/commands/tdd-pipeline.js

@@ -1,144 +0,0 @@
-import path from "node:path";
-import fs from "fs-extra";
-import { detectCIStack } from "./ci.js";
-import { getTddTestCommand } from "./tdd.js";
-// =============================================================================
-// Hook generation
-// =============================================================================
-/**
- * Generate a TDD pipeline enforcement pre-push hook script.
- *
- * - strict: tests MUST pass or push is blocked (exit 1).
- * - warn:   tests are run and results shown, but push is never blocked.
- *
- * If testCmd is null, generates a skip-only hook regardless of mode.
- */
-export function generateTddPipelineHook(mode, testCmd, stack) {
-    if (!testCmd) {
-        return `#!/bin/bash
-# =============================================================================
-# TDD PIPELINE (pre-push): No test command detected for stack "${stack}"
-# =============================================================================
-# Install a test runner and re-run: javi-forge tdd pipeline --mode ${mode}
-# =============================================================================
-
-echo "TDD PIPELINE: No test command configured for stack '${stack}' — skipping."
-exit 0
-`;
-    }
-    if (mode === "warn") {
-        return `#!/bin/bash
-# =============================================================================
-# TDD PIPELINE (pre-push): WARN mode
-# =============================================================================
-# Flow: Spec → Tests → Fail → Implement → Pass
-# Stack: ${stack} | Command: ${testCmd}
-# Mode: warn — tests run but push is NEVER blocked
-# To skip: git push --no-verify
-# =============================================================================
-
-echo "TDD PIPELINE [WARN]: Running tests before push..."
-echo "  Stack: ${stack}"
-echo "  Command: ${testCmd}"
-echo "  Mode: warn (push will proceed regardless)"
-echo ""
-
-${testCmd} && {
-    echo ""
-    echo "TDD PIPELINE [WARN]: All tests passed."
-} || {
-    echo ""
-    echo "TDD PIPELINE [WARN]: Tests FAILED — but push will proceed (warn mode)."
-    echo "  Consider fixing tests before merging."
-}
-
-exit 0
-`;
-    }
-    // strict mode (default)
-    return `#!/bin/bash
-# =============================================================================
-# TDD PIPELINE (pre-push): STRICT mode
-# =============================================================================
-# Flow: Spec → Tests → Fail → Implement → Pass
-# Stack: ${stack} | Command: ${testCmd}
-# Mode: strict — push is BLOCKED if tests fail
-# To skip: git push --no-verify
-# =============================================================================
-
-set -e
-
-echo "TDD PIPELINE [STRICT]: Running tests before push..."
-echo "  Stack: ${stack}"
-echo "  Command: ${testCmd}"
-echo "  Mode: strict (push blocked on failure)"
-echo ""
-
-${testCmd} || {
-    echo ""
-    echo "TDD PIPELINE [STRICT]: FAILED — Tests did not pass."
-    echo "  Fix failing tests before pushing."
-    echo "  To skip: git push --no-verify"
-    exit 1
-}
-
-echo ""
-echo "TDD PIPELINE [STRICT]: All tests passed. Push allowed."
-`;
-}
-// =============================================================================
-// Hook installation
-// =============================================================================
-/**
- * Install TDD pipeline pre-push hook into .git/hooks/.
- * Detects the project stack automatically and generates the appropriate hook.
- * Backs up any existing pre-push hook to pre-push.bak.
- */
-export async function installTddPipelineHook(projectDir, mode) {
-    const result = {
-        installed: [],
-        skipped: [],
-        errors: [],
-        mode,
-    };
-    const gitDir = path.join(projectDir, ".git");
-    if (!(await fs.pathExists(gitDir))) {
-        result.errors.push("Not a git repository. Run git init first.");
-        return result;
-    }
-    const hooksDir = path.join(gitDir, "hooks");
-    await fs.ensureDir(hooksDir);
-    // Detect stack
-    let stackInfo;
-    try {
-        stackInfo = await detectCIStack(projectDir);
-    }
-    catch {
-        result.errors.push("Failed to detect project stack.");
-        return result;
-    }
-    const testCmd = await getTddTestCommand(stackInfo.stackType, stackInfo.buildTool, projectDir);
-    const hookContent = generateTddPipelineHook(mode, testCmd, stackInfo.stackType);
-    const hookPath = path.join(hooksDir, "pre-push");
-    // Backup existing hook
-    if (await fs.pathExists(hookPath)) {
-        const backupPath = path.join(hooksDir, "pre-push.bak");
-        try {
-            await fs.copy(hookPath, backupPath, { overwrite: true });
-            result.skipped.push("pre-push (backed up to pre-push.bak)");
-        }
-        catch (e) {
-            result.errors.push(`backup: ${e instanceof Error ? e.message : String(e)}`);
-            return result;
-        }
-    }
-    try {
-        await fs.writeFile(hookPath, hookContent, { mode: 0o755 });
-        result.installed.push("pre-push");
-    }
-    catch (e) {
-        result.errors.push(`pre-push: ${e instanceof Error ? e.message : String(e)}`);
-    }
-    return result;
-}
-//# sourceMappingURL=tdd-pipeline.js.map