javi-forge 1.22.3 → 1.23.1

package/ci-local/README.md

@@ -174,7 +174,7 @@ Developer workflow:
 │   ├── commit-msg    # Valida mensaje sin AI attribution
 │   └── pre-push      # CI simulation en Docker
 └── docker/
-    └── *.Dockerfile  # Se generan automáticamente
+    └── *.Dockerfile  # Incluidos para cada stack (fallback: se regeneran si faltan)
 
 lib/                  # Dependencia requerida (copiar junto con .ci-local/)
 ├── common.sh         # Funciones compartidas (Bash)
@@ -193,7 +193,7 @@ Editar `lib/common.sh` (detección de stack) o `setup_ci_commands()` en `ci-loca
 
 ### Docker image custom
 
-Editar los Dockerfiles en `.ci-local/docker/` después de la primera ejecución.
+Editar los Dockerfiles en `.ci-local/docker/` (incluidos por stack).
 
 ## FAQ
 

package/ci-local/ci-local.ps1

@@ -177,7 +177,6 @@ RUN apt-get update && apt-get install -y git curl unzip && rm -rf /var/lib/apt/l
 RUN useradd -m -s /bin/bash runner
 USER runner
 WORKDIR /home/runner/work
-ENV GRADLE_USER_HOME=/home/runner/.gradle
 ENTRYPOINT ["/bin/bash", "-c"]
 '@
         }
@@ -207,8 +206,7 @@ ENTRYPOINT ["/bin/bash", "-c"]
 @'
 FROM golang:1.23-bookworm@sha256:167053a2bb901972bf2c1611f8f52c44d5fe7e762e5cab213708d82c421614db
 RUN apt-get update && apt-get install -y git && rm -rf /var/lib/apt/lists/*
-RUN go install github.com/golangci/golangci-lint/cmd/golangci-lint@v1.62.0 && \
-    mv /root/go/bin/golangci-lint /usr/local/bin/
+RUN go install github.com/golangci/golangci-lint/cmd/golangci-lint@v1.62.0 && mv /root/go/bin/golangci-lint /usr/local/bin/
 RUN useradd -m -s /bin/bash runner
 USER runner
 WORKDIR /home/runner/work

package/ci-local/ci-local.sh

@@ -174,7 +174,6 @@ RUN apt-get update && apt-get install -y git curl unzip && rm -rf /var/lib/apt/l
 RUN useradd -m -s /bin/bash runner
 USER runner
 WORKDIR /home/runner/work
-ENV GRADLE_USER_HOME=/home/runner/.gradle
 ENTRYPOINT ["/bin/bash", "-c"]
 DOCKERFILE
             ;;
@@ -204,8 +203,7 @@ DOCKERFILE
             cat > "$docker_dir/$DOCKERFILE" << 'DOCKERFILE'
 FROM golang:1.23-bookworm@sha256:167053a2bb901972bf2c1611f8f52c44d5fe7e762e5cab213708d82c421614db
 RUN apt-get update && apt-get install -y git && rm -rf /var/lib/apt/lists/*
-RUN go install github.com/golangci/golangci-lint/cmd/golangci-lint@v1.62.0 && \
-    mv /root/go/bin/golangci-lint /usr/local/bin/
+RUN go install github.com/golangci/golangci-lint/cmd/golangci-lint@v1.62.0 && mv /root/go/bin/golangci-lint /usr/local/bin/
 RUN useradd -m -s /bin/bash runner
 USER runner
 WORKDIR /home/runner/work

package/ci-local/docker/elixir.Dockerfile

@@ -0,0 +1,6 @@
+FROM ubuntu:24.04@sha256:c4a8d5503dfb2a3eb8ab5f807da5bc69a85730fb49b5cfca2330194ebcc41c7b
+RUN apt-get update && apt-get install -y git curl && rm -rf /var/lib/apt/lists/*
+RUN useradd -m -s /bin/bash runner
+USER runner
+WORKDIR /home/runner/work
+ENTRYPOINT ["/bin/bash", "-c"]

package/ci-local/docker/go.Dockerfile

@@ -0,0 +1,7 @@
+FROM golang:1.23-bookworm@sha256:167053a2bb901972bf2c1611f8f52c44d5fe7e762e5cab213708d82c421614db
+RUN apt-get update && apt-get install -y git && rm -rf /var/lib/apt/lists/*
+RUN go install github.com/golangci/golangci-lint/cmd/golangci-lint@v1.62.0 && mv /root/go/bin/golangci-lint /usr/local/bin/
+RUN useradd -m -s /bin/bash runner
+USER runner
+WORKDIR /home/runner/work
+ENTRYPOINT ["/bin/bash", "-c"]

package/ci-local/docker/java-gradle.Dockerfile

@@ -0,0 +1,7 @@
+ARG JAVA_VERSION=21
+FROM eclipse-temurin:${JAVA_VERSION}-jdk-noble
+RUN apt-get update && apt-get install -y git curl unzip && rm -rf /var/lib/apt/lists/*
+RUN useradd -m -s /bin/bash runner
+USER runner
+WORKDIR /home/runner/work
+ENTRYPOINT ["/bin/bash", "-c"]

package/ci-local/docker/java-maven.Dockerfile

@@ -0,0 +1,7 @@
+ARG JAVA_VERSION=21
+FROM eclipse-temurin:${JAVA_VERSION}-jdk-noble
+RUN apt-get update && apt-get install -y git curl unzip && rm -rf /var/lib/apt/lists/*
+RUN useradd -m -s /bin/bash runner
+USER runner
+WORKDIR /home/runner/work
+ENTRYPOINT ["/bin/bash", "-c"]

package/ci-local/docker/java.Dockerfile

@@ -0,0 +1,7 @@
+ARG JAVA_VERSION=21
+FROM eclipse-temurin:${JAVA_VERSION}-jdk-noble
+RUN apt-get update && apt-get install -y git curl unzip && rm -rf /var/lib/apt/lists/*
+RUN useradd -m -s /bin/bash runner
+USER runner
+WORKDIR /home/runner/work
+ENTRYPOINT ["/bin/bash", "-c"]

package/ci-local/docker/python.Dockerfile

@@ -0,0 +1,7 @@
+FROM python:3.12-slim@sha256:401f6e1a67dad31a1bd78e9ad22d0ee0a3b52154e6bd30e90be696bb6a3d7461
+RUN apt-get update && apt-get install -y git && rm -rf /var/lib/apt/lists/*
+RUN pip install --no-cache-dir pytest ruff pylint poetry
+RUN useradd -m -s /bin/bash runner
+USER runner
+WORKDIR /home/runner/work
+ENTRYPOINT ["/bin/bash", "-c"]

package/ci-local/docker/rust.Dockerfile

@@ -0,0 +1,7 @@
+FROM rust:1.83-slim@sha256:540c902e99c384163b688bbd8b5b8520e94e7731b27f7bd0eaa56ae1960627ab
+RUN apt-get update && apt-get install -y git pkg-config libssl-dev && rm -rf /var/lib/apt/lists/*
+RUN rustup component add clippy rustfmt
+RUN useradd -m -s /bin/bash runner
+USER runner
+WORKDIR /home/runner/work
+ENTRYPOINT ["/bin/bash", "-c"]

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

@@ -0,0 +1,12 @@
+/**
+ * `javi-forge hooks` handler — console-only (no Ink; a git hook runs in a
+ * terminal git owns). Mirrors the `ci init` branch: the command module
+ * (`./commands/hooks.js`) is lazy-imported inside the handler to keep cold-start
+ * minimal, because hooks are on the commit/push hot path.
+ *
+ * Only subcommand: `hooks run <pre-commit|pre-push>` → dispatches to runHook and
+ * exits with its code. Any other subcommand or a missing name → usage + exit 1.
+ */
+import type { CLI } from "./types.js";
+export declare function handleHooks(cli: CLI): Promise<void>;
+//# sourceMappingURL=hooks.d.ts.map

package/dist/cli/dispatch/hooks.js

@@ -0,0 +1,31 @@
+/**
+ * `javi-forge hooks` handler — console-only (no Ink; a git hook runs in a
+ * terminal git owns). Mirrors the `ci init` branch: the command module
+ * (`./commands/hooks.js`) is lazy-imported inside the handler to keep cold-start
+ * minimal, because hooks are on the commit/push hot path.
+ *
+ * Only subcommand: `hooks run <pre-commit|pre-push>` → dispatches to runHook and
+ * exits with its code. Any other subcommand or a missing name → usage + exit 1.
+ */
+import { HOOKS_HELP_TEXT } from "../help.js";
+export async function handleHooks(cli) {
+    if (cli.flags.help === true) {
+        console.log(HOOKS_HELP_TEXT);
+        process.exit(0);
+    }
+    if (cli.input[1] === "run") {
+        const name = cli.input[2];
+        if (name === undefined) {
+            console.error("Usage: javi-forge hooks run <pre-commit|pre-push>");
+            process.exit(1);
+        }
+        const { runHook } = await import("../../commands/hooks.js");
+        const code = await runHook(name, process.cwd());
+        process.exit(code);
+    }
+    // No subcommand → show usage (exit 0). An unknown subcommand is a typo →
+    // show usage but exit 1 rather than run nothing silently.
+    console.log(HOOKS_HELP_TEXT);
+    process.exit(cli.input[1] === undefined ? 0 : 1);
+}
+//# sourceMappingURL=hooks.js.map

package/dist/cli/help.d.ts

@@ -8,13 +8,18 @@
  * 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    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          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";
 /**
  * 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
  * layout — whitespace is significant.
  */
 export declare const CI_HELP_TEXT = "\n  Usage\n    $ javi-forge ci [subcommand] [options]\n\n    Run a local CI simulation (lint + compile + test + security + ghagga).\n    With no subcommand, the full pipeline runs.\n\n  Subcommands\n    init            Install git hooks that call javi-forge ci\n    validate        Validate .javi-forge/ci.yaml without running anything\n\n  Options\n    --quick         Lint + compile only (fast, for pre-commit)\n    --no-docker     Run commands natively (no Docker)\n    --no-security   Skip Semgrep security scan\n    --no-ci-ghagga  Skip GHAGGA review\n    --force         (ci init) Overwrite a foreign or modified hook (backs up first)\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)\n    --json          (ci validate) Emit the result as JSON\n    --help          Show this help\n\n  Examples\n    $ javi-forge ci\n    $ javi-forge ci --quick\n    $ javi-forge ci validate\n    $ javi-forge ci validate --json\n    $ javi-forge ci init --force\n";
+/**
+ * Per-command help for `hooks`, shown by `javi-forge hooks --help` (or when
+ * `hooks` is given an unknown subcommand). Whitespace is significant.
+ */
+export declare const HOOKS_HELP_TEXT = "\n  Usage\n    $ javi-forge hooks run <pre-commit|pre-push>\n\n    Run the sections enabled under hooks: in .javi-forge/ci.yaml, in a fixed\n    cheap\u2192expensive order, fail-fast. With no hooks: config the default is the\n    quick native CI gate (setup + lint + compile + gates \u2014 no tests, no coverage).\n\n  Subcommands\n    run pre-commit  Run the composed pre-commit sections\n    run pre-push    Run the composed pre-push sections\n\n  Notes\n    A blocking section failure exits non-zero and blocks the commit/push.\n    A broken .javi-forge/ci.yaml exits 1 (fail-closed \u2014 never skips a gate).\n    To skip: git commit --no-verify   (pre-push: git push --no-verify)\n\n  Examples\n    $ javi-forge hooks run pre-commit\n    $ javi-forge hooks run pre-push\n";
 export declare const FLAGS_SCHEMA: {
     readonly help: {
         readonly type: "boolean";

package/dist/cli/help.js

@@ -19,6 +19,7 @@ export const HELP_TEXT = `
     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)
+    hooks run         Run a git hook's composed sections (pre-commit | pre-push)
     analyze           Run repoforge skills analysis
     doctor            Show health report
     workflow show     Render a workflow graph as ASCII (--template <name> or file path)
@@ -143,6 +144,31 @@ export const CI_HELP_TEXT = `
     $ javi-forge ci validate --json
     $ javi-forge ci init --force
 `;
+/**
+ * Per-command help for `hooks`, shown by `javi-forge hooks --help` (or when
+ * `hooks` is given an unknown subcommand). Whitespace is significant.
+ */
+export const HOOKS_HELP_TEXT = `
+  Usage
+    $ javi-forge hooks run <pre-commit|pre-push>
+
+    Run the sections enabled under hooks: in .javi-forge/ci.yaml, in a fixed
+    cheap→expensive order, fail-fast. With no hooks: config the default is the
+    quick native CI gate (setup + lint + compile + gates — no tests, no coverage).
+
+  Subcommands
+    run pre-commit  Run the composed pre-commit sections
+    run pre-push    Run the composed pre-push sections
+
+  Notes
+    A blocking section failure exits non-zero and blocks the commit/push.
+    A broken .javi-forge/ci.yaml exits 1 (fail-closed — never skips a gate).
+    To skip: git commit --no-verify   (pre-push: git push --no-verify)
+
+  Examples
+    $ javi-forge hooks run pre-commit
+    $ javi-forge hooks run pre-push
+`;
 export const FLAGS_SCHEMA = {
     // `--help` is handled manually (autoHelp is disabled at the entrypoint so
     // `ci --help` can show ci-specific usage instead of the global banner).

package/dist/commands/hooks.d.ts

@@ -0,0 +1,60 @@
+/**
+ * `javi-forge hooks run <name>` dispatcher (hook-consolidation S1a).
+ *
+ * Pure logic, no Ink: composes the ENABLED sections for a hook from the
+ * `hooks:` section of `.javi-forge/ci.yaml`, in a fixed cheap→expensive order,
+ * and runs them fail-fast. A blocking section failure exits non-zero; only an
+ * advisory section (pre-push `tdd: "warn"`) prints and continues.
+ *
+ * Fail-closed: a missing config means the default `[ci]` composition (today's
+ * 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.
+ */
+import { type CIHooksConfig } from "../lib/ci-config.js";
+import { runCI } from "./ci.js";
+/** A single composable unit of hook work. */
+export interface HookSection {
+    /** stable id — "secrets" | "permissions" | "tdd" | "deps" | "ci" */
+    id: string;
+    /** false ONLY for an advisory section (pre-push tdd:"warn") */
+    blocking: boolean;
+    run(ctx: {
+        projectDir: string;
+    }): Promise<{
+        ok: boolean;
+        detail?: string;
+    }>;
+}
+export type SectionId = "secrets" | "permissions" | "tdd" | "deps" | "ci";
+export type SectionFactory = () => HookSection;
+export type SectionRegistry = Partial<Record<SectionId, SectionFactory>>;
+export type HookName = "pre-commit" | "pre-push";
+/**
+ * Compose the enabled, implemented sections for a hook in fixed order. The
+ * section's blocking flag is derived from config (so pre-push tdd:"warn" is
+ * advisory) regardless of the factory's own default. An enabled feature with no
+ * registered factory is skipped — the S1a gate for tdd/security bodies that land
+ * in later slices.
+ */
+export declare function composeSections(name: HookName, config: CIHooksConfig | null, registry: SectionRegistry): HookSection[];
+/** 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. */
+export interface RunHookDeps {
+    loadConfig?: (projectDir: string) => Promise<CIHooksConfig | null>;
+    registry?: SectionRegistry;
+    runCIImpl?: typeof runCI;
+    log?: (msg: string) => void;
+    logError?: (msg: string) => void;
+}
+/**
+ * Run the composed sections for `name`. Returns the process exit code:
+ * 0 iff every blocking section passed. Fail-fast on the first blocking failure;
+ * fail-closed (exit 1) on an unknown hook name or an unparseable config.
+ */
+export declare function runHook(name: string, projectDir: string, deps?: RunHookDeps): Promise<number>;
+//# sourceMappingURL=hooks.d.ts.map

package/dist/commands/hooks.js

@@ -0,0 +1,169 @@
+/**
+ * `javi-forge hooks run <name>` dispatcher (hook-consolidation S1a).
+ *
+ * Pure logic, no Ink: composes the ENABLED sections for a hook from the
+ * `hooks:` section of `.javi-forge/ci.yaml`, in a fixed cheap→expensive order,
+ * and runs them fail-fast. A blocking section failure exits non-zero; only an
+ * advisory section (pre-push `tdd: "warn"`) prints and continues.
+ *
+ * Fail-closed: a missing config means the default `[ci]` composition (today's
+ * 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.
+ */
+import { findCIConfig, loadCIConfig, } from "../lib/ci-config.js";
+import { runCI } from "./ci.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"];
+/** No config / no `hooks:` section → the [ci]-only default (byte-for-byte today). */
+const DEFAULT_HOOKS = {
+    preCommit: { ci: true, tdd: false, secrets: false, permissions: false },
+    prePush: { ci: true, tdd: false, deps: false },
+};
+function featureState(id, name, config) {
+    if (name === "pre-commit") {
+        const pc = config.preCommit;
+        switch (id) {
+            case "secrets":
+                return { enabled: pc.secrets, blocking: true };
+            case "permissions":
+                return { enabled: pc.permissions, blocking: true };
+            case "tdd":
+                return { enabled: pc.tdd, blocking: true };
+            case "ci":
+                return { enabled: pc.ci, blocking: true };
+            default:
+                return { enabled: false, blocking: true };
+        }
+    }
+    const pp = config.prePush;
+    switch (id) {
+        case "deps":
+            return { enabled: pp.deps, blocking: true };
+        case "tdd":
+            // "warn" is advisory (never blocks); false is off; "strict"/true block.
+            return { enabled: pp.tdd !== false, blocking: pp.tdd !== "warn" };
+        case "ci":
+            return { enabled: pp.ci, blocking: true };
+        default:
+            return { enabled: false, blocking: true };
+    }
+}
+/**
+ * Compose the enabled, implemented sections for a hook in fixed order. The
+ * section's blocking flag is derived from config (so pre-push tdd:"warn" is
+ * advisory) regardless of the factory's own default. An enabled feature with no
+ * registered factory is skipped — the S1a gate for tdd/security bodies that land
+ * in later slices.
+ */
+export function composeSections(name, config, registry) {
+    const cfg = config ?? DEFAULT_HOOKS;
+    const order = name === "pre-commit" ? PRE_COMMIT_ORDER : PRE_PUSH_ORDER;
+    const sections = [];
+    for (const id of order) {
+        const state = featureState(id, name, cfg);
+        if (!state.enabled)
+            continue;
+        const factory = registry[id];
+        if (!factory)
+            continue; // S1a: enabled but not yet implemented → skip
+        const section = factory();
+        sections.push({ ...section, blocking: state.blocking });
+    }
+    return sections;
+}
+/**
+ * The `ci` section: runs the quick native CI gate IN-PROCESS (no subprocess, no
+ * PATH/version skew). `runCI` throws on a blocking failure → the section reports
+ * ok:false. `quick` runs setup + lint + compile + gates — NO tests, NO coverage.
+ */
+function ciSection(runCIImpl, log) {
+    return {
+        id: "ci",
+        blocking: true,
+        async run({ projectDir }) {
+            try {
+                await runCIImpl({
+                    projectDir,
+                    mode: "quick",
+                    noDocker: true,
+                    noSecurity: true,
+                    noGhagga: true,
+                }, (step) => reportStep(step, log));
+                return { ok: true };
+            }
+            catch (e) {
+                return {
+                    ok: false,
+                    detail: e instanceof Error ? e.message : String(e),
+                };
+            }
+        },
+    };
+}
+/** Console step feedback (no Ink in a git hook). Honest — never claims tests. */
+function reportStep(step, log) {
+    if (step.status === "done")
+        log(`  ✓ ${step.label}`);
+    else if (step.status === "error")
+        log(`  ✗ ${step.label}${step.detail ? ` — ${step.detail}` : ""}`);
+    else if (step.status === "warning")
+        log(`  ⚠ ${step.label}`);
+}
+function defaultRegistry(runCIImpl, log) {
+    return { ci: () => ciSection(runCIImpl, log) };
+}
+/** Resolve the parsed `hooks:` config for a project (null → default [ci]). */
+export async function loadHooksConfig(projectDir) {
+    const configPath = await findCIConfig(projectDir);
+    if (!configPath)
+        return null;
+    // Throws CIConfigError on an invalid config → runHook maps that to exit 1.
+    const config = await loadCIConfig(configPath);
+    return config.hooks ?? null;
+}
+const USAGE = "Usage: javi-forge hooks run <pre-commit|pre-push>";
+/**
+ * Run the composed sections for `name`. Returns the process exit code:
+ * 0 iff every blocking section passed. Fail-fast on the first blocking failure;
+ * fail-closed (exit 1) on an unknown hook name or an unparseable config.
+ */
+export async function runHook(name, projectDir, deps = {}) {
+    const log = deps.log ?? ((m) => console.log(m));
+    const logError = deps.logError ?? ((m) => console.error(m));
+    if (name !== "pre-commit" && name !== "pre-push") {
+        logError(USAGE);
+        return 1;
+    }
+    const loadConfig = deps.loadConfig ?? loadHooksConfig;
+    let config;
+    try {
+        config = await loadConfig(projectDir);
+    }
+    catch (e) {
+        // Fail-closed: a broken config never silently skips a gate.
+        logError(e instanceof Error ? e.message : String(e));
+        return 1;
+    }
+    const runCIImpl = deps.runCIImpl ?? runCI;
+    const registry = deps.registry ?? defaultRegistry(runCIImpl, log);
+    const sections = composeSections(name, config, registry);
+    for (const section of sections) {
+        log(`▶ ${section.id}`);
+        const result = await section.run({ projectDir });
+        if (result.ok)
+            continue;
+        const detail = result.detail ? `: ${result.detail}` : "";
+        if (section.blocking) {
+            logError(`✗ ${section.id} failed${detail}`);
+            return 1; // fail-fast
+        }
+        log(`⚠ ${section.id} (advisory) failed${detail}`);
+    }
+    return 0;
+}
+//# sourceMappingURL=hooks.js.map

package/dist/index.js

@@ -2,6 +2,7 @@
 import { createRequire } from "node:module";
 import meow from "meow";
 import { handleCi } from "./cli/dispatch/ci.js";
+import { handleHooks } from "./cli/dispatch/hooks.js";
 import { handleSecurity } from "./cli/dispatch/security.js";
 import { handleAnalyze, handleDoctor, handleInitDefault, handleLlmsTxt, handlePlugin, } from "./cli/dispatch/simple-renderers.js";
 import { handleSkillPublish } from "./cli/dispatch/skill-publish.js";
@@ -22,9 +23,9 @@ const cli = meow(HELP_TEXT, {
     autoHelp: false,
 });
 const subcommand = cli.input[0] ?? "init";
-// Global --help: every command except `ci` shows the global banner here. `ci`
-// owns its per-command help inside handleCi.
-if (cli.flags.help && subcommand !== "ci") {
+// Global --help: every command except `ci` and `hooks` shows the global banner
+// here. Those two own their per-command help inside their handlers.
+if (cli.flags.help && subcommand !== "ci" && subcommand !== "hooks") {
     console.log(HELP_TEXT);
     process.exit(0);
 }
@@ -39,6 +40,10 @@ switch (subcommand) {
         await handleCi(cli, { inkStdin, isCI });
         break;
     }
+    case "hooks": {
+        await handleHooks(cli);
+        break;
+    }
     case "doctor": {
         handleDoctor(cli, { inkStdin, isCI });
         break;

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

@@ -74,11 +74,41 @@ export interface CIGateConfig {
      */
     timeout?: number;
 }
+/** pre-commit hook feature toggles (version 2 only). */
+export interface CIHookCommitConfig {
+    /** quick native CI gate (default true when `hooks:` is present) */
+    ci: boolean;
+    /** run the stack test command */
+    tdd: boolean;
+    /** L1 secret scan */
+    secrets: boolean;
+    /** L3 permission boundaries */
+    permissions: boolean;
+}
+/** pre-push hook feature toggles (version 2 only). */
+export interface CIHookPushConfig {
+    /** quick native CI gate (default true when `hooks:` is present) */
+    ci: boolean;
+    /** run the stack test command — false | "strict" | "warn" ("warn" = advisory) */
+    tdd: boolean | "strict" | "warn";
+    /** L2 dependency audit */
+    deps: boolean;
+}
+/**
+ * Parsed `hooks:` section. Every hook is always present with defaults applied
+ * (ci on, every other feature off) so the dispatcher never branches on absence.
+ */
+export interface CIHooksConfig {
+    preCommit: CIHookCommitConfig;
+    prePush: CIHookPushConfig;
+}
 export interface CIConfig {
     version: number;
     runners: CIRunnerConfig[];
     /** Present only under version 2 when `gates:` is declared. */
     gates?: CIGateConfig[];
+    /** Present only under version 2 when `hooks:` is declared. */
+    hooks?: CIHooksConfig;
 }
 export interface CIConfigValidationError {
     path: string;
@@ -96,6 +126,14 @@ export declare const CI_STACKS: readonly string[];
  * (the caller discards them all if `errors` is non-empty — fail closed).
  */
 export declare function validateGates(raw: unknown, errors: CIConfigValidationError[]): CIGateConfig[];
+/**
+ * Validate the `hooks:` block (version 2 only). Mirrors validateGate: every
+ * schema error names the offending field and the caller discards the whole
+ * config if `errors` is non-empty (fail closed). Always returns a fully
+ * defaulted config (ci on, every other feature off) so the dispatcher never
+ * branches on an omitted hook or feature.
+ */
+export declare function validateHooks(raw: unknown, errors: CIConfigValidationError[]): CIHooksConfig;
 /**
  * Parse and validate CI config YAML text. Throws CIConfigError listing every
  * validation problem; never returns a partially valid config.

package/dist/lib/ci-config.js

@@ -396,6 +396,113 @@ export function validateGates(raw, errors) {
     });
     return gates;
 }
+const HOOK_NAMES = new Set(["pre-commit", "pre-push"]);
+const PRE_COMMIT_FEATURES = new Set(["ci", "tdd", "secrets", "permissions"]);
+const PRE_PUSH_FEATURES = new Set(["ci", "tdd", "deps"]);
+/** Validate one boolean feature toggle, returning `dflt` when absent. */
+function validateBoolFeature(raw, key, base, errors, dflt) {
+    const value = raw[key];
+    if (value === undefined)
+        return dflt;
+    if (typeof value !== "boolean") {
+        errors.push({
+            path: `${base}.${key}`,
+            message: `${key} must be a boolean`,
+        });
+        return dflt;
+    }
+    return value;
+}
+/** Validate the tri-state pre-push.tdd toggle (false | "strict" | "warn"). */
+function validatePushTdd(value, base, errors) {
+    if (value === undefined)
+        return false;
+    if (typeof value === "boolean")
+        return value;
+    if (value === "strict" || value === "warn")
+        return value;
+    errors.push({
+        path: `${base}.tdd`,
+        message: `tdd must be a boolean or one of: strict, warn (got "${String(value)}")`,
+    });
+    return false;
+}
+/**
+ * Validate the `hooks:` block (version 2 only). Mirrors validateGate: every
+ * schema error names the offending field and the caller discards the whole
+ * config if `errors` is non-empty (fail closed). Always returns a fully
+ * defaulted config (ci on, every other feature off) so the dispatcher never
+ * branches on an omitted hook or feature.
+ */
+export function validateHooks(raw, errors) {
+    const preCommit = {
+        ci: true,
+        tdd: false,
+        secrets: false,
+        permissions: false,
+    };
+    const prePush = { ci: true, tdd: false, deps: false };
+    if (!isRecord(raw)) {
+        errors.push({
+            path: "hooks",
+            message: "hooks must be a mapping of hook names to feature toggles",
+        });
+        return { preCommit, prePush };
+    }
+    for (const key of Object.keys(raw)) {
+        if (!HOOK_NAMES.has(key)) {
+            errors.push({ path: `hooks.${key}`, message: `unknown field "${key}"` });
+        }
+    }
+    if (raw["pre-commit"] !== undefined) {
+        const pc = raw["pre-commit"];
+        const base = "hooks.pre-commit";
+        if (!isRecord(pc)) {
+            errors.push({
+                path: base,
+                message: "pre-commit must be a mapping of feature toggles",
+            });
+        }
+        else {
+            for (const key of Object.keys(pc)) {
+                if (!PRE_COMMIT_FEATURES.has(key)) {
+                    errors.push({
+                        path: `${base}.${key}`,
+                        message: `unknown field "${key}"`,
+                    });
+                }
+            }
+            preCommit.ci = validateBoolFeature(pc, "ci", base, errors, true);
+            preCommit.tdd = validateBoolFeature(pc, "tdd", base, errors, false);
+            preCommit.secrets = validateBoolFeature(pc, "secrets", base, errors, false);
+            preCommit.permissions = validateBoolFeature(pc, "permissions", base, errors, false);
+        }
+    }
+    if (raw["pre-push"] !== undefined) {
+        const pp = raw["pre-push"];
+        const base = "hooks.pre-push";
+        if (!isRecord(pp)) {
+            errors.push({
+                path: base,
+                message: "pre-push must be a mapping of feature toggles",
+            });
+        }
+        else {
+            for (const key of Object.keys(pp)) {
+                if (!PRE_PUSH_FEATURES.has(key)) {
+                    errors.push({
+                        path: `${base}.${key}`,
+                        message: `unknown field "${key}"`,
+                    });
+                }
+            }
+            prePush.ci = validateBoolFeature(pp, "ci", base, errors, true);
+            prePush.tdd = validatePushTdd(pp.tdd, base, errors);
+            prePush.deps = validateBoolFeature(pp, "deps", base, errors, false);
+        }
+    }
+    return { preCommit, prePush };
+}
 // =============================================================================
 // Public API
 // =============================================================================
@@ -434,6 +541,7 @@ export function parseCIConfig(rawYaml, source) {
     }
     const isV2 = version === 2;
     const hasGates = doc.gates !== undefined;
+    const hasHooks = doc.hooks !== undefined;
     for (const key of Object.keys(doc)) {
         if (TOP_LEVEL_FIELDS.has(key))
             continue;
@@ -445,16 +553,25 @@ export function parseCIConfig(rawYaml, source) {
             }
             continue;
         }
+        if (key === "hooks") {
+            // Same version-gating as `gates`: `hooks` is a v2-only key, so under any
+            // other version it reports a named error, not the generic unknown-field.
+            if (!isV2) {
+                errors.push({ path: "hooks", message: "hooks require version: 2" });
+            }
+            continue;
+        }
         errors.push({ path: key, message: `unknown field "${key}"` });
     }
     if (isV2) {
-        // v2: runners OPTIONAL when gates present; NEITHER runners nor gates fails
-        // closed (nothing to run).
+        // v2: runners OPTIONAL when gates OR hooks are present; declaring NONE of the
+        // three fails closed (nothing to run).
         if (!hasGates &&
+            !hasHooks &&
             (!Array.isArray(doc.runners) || doc.runners.length === 0)) {
             errors.push({
                 path: "runners",
-                message: "a version 2 config must declare runners or gates (nothing to run otherwise)",
+                message: "a version 2 config must declare runners, gates or hooks (nothing to run otherwise)",
             });
         }
     }
@@ -468,6 +585,9 @@ export function parseCIConfig(rawYaml, source) {
     // Gates are validated ONLY under v2 — a v1+gates config is already rejected
     // above and must not surface a second, confusing wave of gate-field errors.
     const gates = isV2 && hasGates ? validateGates(doc.gates, errors) : [];
+    // Hooks are validated ONLY under v2 — a v1+hooks config is already rejected
+    // above and must not surface a second wave of hook-field errors.
+    const hooks = isV2 && hasHooks ? validateHooks(doc.hooks, errors) : undefined;
     const runners = [];
     if (Array.isArray(doc.runners)) {
         doc.runners.forEach((raw, index) => {
@@ -496,6 +616,8 @@ export function parseCIConfig(rawYaml, source) {
     const config = { version: version ?? CI_CONFIG_VERSION, runners };
     if (gates.length > 0)
         config.gates = gates;
+    if (hooks)
+        config.hooks = hooks;
     return config;
 }
 /**

package/dist/lib/docker.js

@@ -38,6 +38,14 @@ export function getDockerfileContent(stack) {
                 "RUN apt-get update && apt-get install -y git curl unzip && rm -rf /var/lib/apt/lists/*",
                 "RUN useradd -m -s /bin/bash runner",
                 "USER runner",
+                // No GRADLE_USER_HOME override (audit R4-001): on noble the
+                // `ubuntu` user owns uid 1000, so `useradd -m runner` lands at
+                // uid 1001 and /home/runner is 0750 runner:runner. Pinning
+                // GRADLE_USER_HOME=/home/runner/.gradle hard-fails the TS
+                // runtime path, which runs as the HOST uid (ENV-1, typically
+                // 1000) and cannot create that dir. Without the env both paths
+                // work off $HOME: shell path (--user runner) → /home/runner;
+                // host-uid path → getpwuid(1000) → /home/ubuntu.
                 "WORKDIR /home/runner/work",
                 'ENTRYPOINT ["/bin/bash", "-c"]',
             ].join("\n");
@@ -143,10 +151,22 @@ export async function ensureImage(options) {
             path.join(path.dirname(fileURLToPath(import.meta.url)), "../../ci-local/docker");
         dockerfilePath = path.join(dockerDir, `${stack}.Dockerfile`);
         contextDir = dockerDir;
-        // Write Dockerfile if it doesn't exist yet (first run)
         if (!(await fs.pathExists(dockerfilePath))) {
-            await fs.ensureDir(dockerDir);
-            await fs.writeFile(dockerfilePath, getDockerfileContent(stack), "utf-8");
+            if (dockerfilesDir) {
+                // Caller-provided generation dir (dev / project-local flow):
+                // first-run generation is expected — write the canonical content.
+                await fs.ensureDir(dockerDir);
+                await fs.writeFile(dockerfilePath, getDockerfileContent(stack), "utf-8");
+            }
+            else {
+                // PKG-002: the package bundles a Dockerfile for EVERY stack, so a
+                // miss here means a corrupted/incomplete install. Writing into the
+                // install dir would EACCES on root-owned global installs and mask
+                // the real problem — fail closed with a clear message instead.
+                throw new Error(`bundled Dockerfile "${stack}.Dockerfile" is missing from ` +
+                    `"${dockerDir}" — the javi-forge installation looks corrupted; ` +
+                    "reinstall the package (or pass an explicit dockerfilesDir)");
+            }
         }
     }
     // Staleness check: compare Dockerfile hash with the one embedded in the image label

package/package.json

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