javi-forge 1.38.5 → 1.39.0

package/assets/claude-hooks/javi-forge-windows-secure-object.ps1

@@ -92,6 +92,7 @@ namespace JaviForge
         private const uint WRITE_OWNER_A = 0x00080000;
         private const uint DELETE_A = 0x00010000;
         private const uint FILE_READ_ATTRIBUTES = 0x0080;
+        private const uint DIRECTORY_FLUSH_ACCESS = GENERIC_WRITE | READ_CONTROL | FILE_READ_ATTRIBUTES;
 
         private const uint FILE_SHARE_READ = 0x1;
         private const uint FILE_SHARE_WRITE = 0x2;
@@ -866,12 +867,34 @@ namespace JaviForge
                 // No opaque re-check here (unlike unlink/rmdir): both endpoints are our
                 // own just-created nodes under the held parent-chain lock, so no on-path
                 // node can be swapped while the chain handle is held.
-                if (!MoveFileExW(fromFull, toFull,
-                    MOVEFILE_REPLACE_EXISTING | MOVEFILE_WRITE_THROUGH))
-                    return OpResult.Fail(R_CHAIN, "rename failed " + Marshal.GetLastWin32Error()
-                        + " " + fromFull);
-                FlushFileBuffers(dir.Handle);
-                return OpResult.Good();
+                int flushErr;
+                IntPtr flushHandle = OpenNoFollow(dir.Path, DIRECTORY_FLUSH_ACCESS,
+                    FILE_SHARE_READ | FILE_SHARE_WRITE, out flushErr);
+                if (flushHandle == INVALID_HANDLE)
+                    return OpResult.Fail(R_CHAIN, "rename flush-open failed " + flushErr + " " + dir.Path);
+                try
+                {
+                    uint attr; string opaque; bool zeroId;
+                    if (!ReadInfo(flushHandle, out attr, out opaque, out zeroId))
+                        return OpResult.Fail(R_CHAIN, "rename flush-open info failed " + dir.Path);
+                    if ((attr & FILE_ATTRIBUTE_REPARSE_POINT) != 0)
+                        return OpResult.Fail(R_CHAIN, "rename flush-open reparse point " + dir.Path);
+                    if ((attr & FILE_ATTRIBUTE_DIRECTORY) == 0)
+                        return OpResult.Fail(R_CHAIN, "rename flush-open not a directory " + dir.Path);
+                    if (zeroId)
+                        return OpResult.Fail(R_CHAIN, "rename flush-open unresolvable identity " + dir.Path);
+                    if (!String.Equals(opaque, dir.Opaque, StringComparison.OrdinalIgnoreCase))
+                        return OpResult.Fail(R_CHAIN, "rename flush-open identity changed " + dir.Path);
+                    if (!MoveFileExW(fromFull, toFull,
+                        MOVEFILE_REPLACE_EXISTING | MOVEFILE_WRITE_THROUGH))
+                        return OpResult.Fail(R_CHAIN, "rename failed " + Marshal.GetLastWin32Error()
+                            + " " + fromFull);
+                    if (!FlushFileBuffers(flushHandle))
+                        return OpResult.Fail(R_CHAIN, "rename flush failed " + Marshal.GetLastWin32Error()
+                            + " " + dir.Path);
+                    return OpResult.Good();
+                }
+                finally { CloseHandle(flushHandle); }
             }
             catch (Exception ex) { return OpResult.Fail(R_CHAIN, "rename exception " + ex.Message); }
         }

package/assets/claude-hooks/manifest.json

@@ -30,7 +30,7 @@
 	"installerHelpers": {
 		"windowsSecureObject": {
 			"name": "javi-forge-windows-secure-object.ps1",
-			"sha256": "2289ef6ac6b039ec74dc3ea0894413e243ff9bea963f04008a356b3838f9b8dd"
+			"sha256": "4ee446d4e540adbea88c343df540efdcad1a5b26d31481ac5ae7057d8375cd11"
 		}
 	}
 }

package/assets/preparation-worker.c

@@ -0,0 +1,180 @@
+/* Fixed Linux x86-64 data-only preparation worker. Build statically; never run
+ * generated helpers. Operator approves the exact binary AND this source digest.
+ * JSON checks are artifact validation, not helper behavior or domain-schema tests. */
+#define _GNU_SOURCE
+#include <errno.h>
+#include <fcntl.h>
+#include <linux/audit.h>
+#include <linux/filter.h>
+#include <linux/seccomp.h>
+#include <stddef.h>
+#include <stdint.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <sys/prctl.h>
+#include <sys/socket.h>
+#include <sys/stat.h>
+#include <sys/syscall.h>
+#include <time.h>
+#include <unistd.h>
+
+#define LIMIT 1048576
+#define DIR_FLAGS (O_RDONLY | O_DIRECTORY | O_NOFOLLOW | O_CLOEXEC)
+#define FILE_FLAGS (O_WRONLY | O_CREAT | O_EXCL | O_NOFOLLOW | O_CLOEXEC)
+static const char *names[6] = {"app-request.json", "minimal.py", "test_minimal.py", "dispatch.py", "run_gateway.py", "preparation-result.json"};
+static unsigned char *data[6];
+static size_t sizes[6];
+extern char **environ;
+
+#define ALLOW(n) BPF_JUMP(BPF_JMP | BPF_JEQ | BPF_K, __NR_##n, 0, 1), BPF_STMT(BPF_RET | BPF_K, SECCOMP_RET_ALLOW)
+static int restrict_syscalls(void) {
+    struct sock_filter rules[] = {
+        BPF_STMT(BPF_LD | BPF_W | BPF_ABS, offsetof(struct seccomp_data, arch)),
+        BPF_JUMP(BPF_JMP | BPF_JEQ | BPF_K, AUDIT_ARCH_X86_64, 1, 0),
+        BPF_STMT(BPF_RET | BPF_K, SECCOMP_RET_KILL_PROCESS),
+        BPF_STMT(BPF_LD | BPF_W | BPF_ABS, offsetof(struct seccomp_data, nr)),
+        ALLOW(read), ALLOW(write), ALLOW(close), ALLOW(fstat), ALLOW(newfstatat),
+        ALLOW(fsync), ALLOW(fchmod), ALLOW(mkdirat), ALLOW(unlinkat),
+        ALLOW(brk), ALLOW(mmap), ALLOW(munmap), ALLOW(mprotect), ALLOW(futex),
+        ALLOW(clock_gettime), ALLOW(alarm), ALLOW(rt_sigaction), ALLOW(rt_sigprocmask),
+        ALLOW(rt_sigreturn), ALLOW(exit), ALLOW(exit_group), ALLOW(getpid),
+        BPF_JUMP(BPF_JMP | BPF_JEQ | BPF_K, __NR_openat, 1, 0),
+        BPF_STMT(BPF_RET | BPF_K, SECCOMP_RET_ERRNO | EPERM),
+        BPF_STMT(BPF_LD | BPF_W | BPF_ABS, offsetof(struct seccomp_data, args[2])),
+        BPF_JUMP(BPF_JMP | BPF_JEQ | BPF_K, DIR_FLAGS, 2, 0),
+        BPF_JUMP(BPF_JMP | BPF_JEQ | BPF_K, FILE_FLAGS, 1, 0),
+        BPF_STMT(BPF_RET | BPF_K, SECCOMP_RET_ERRNO | EPERM),
+        BPF_STMT(BPF_RET | BPF_K, SECCOMP_RET_ALLOW)
+    };
+    struct sock_fprog program = {(unsigned short)(sizeof(rules) / sizeof(rules[0])), rules};
+    return prctl(PR_SET_NO_NEW_PRIVS, 1, 0, 0, 0) || prctl(PR_SET_SECCOMP, SECCOMP_MODE_FILTER, &program);
+}
+static int isolation_probes(int parent) {
+    errno = 0;
+    if (syscall(__NR_socket, AF_INET, SOCK_STREAM, 0) != -1 || errno != EPERM) return 0;
+    errno = 0;
+    if (openat(parent, "credential-probe", O_RDONLY) != -1 || errno != EPERM) return 0;
+    errno = 0;
+    if (syscall(__NR_clone, 0, 0, 0, 0, 0) != -1 || errno != EPERM) return 0;
+    errno = 0;
+    if (syscall(__NR_execve, "/worker", 0, 0) != -1 || errno != EPERM) return 0;
+    return 1;
+}
+
+struct json { const unsigned char *p, *end; };
+static void ws(struct json *j) { while (j->p < j->end && (*j->p == ' ' || *j->p == '\n' || *j->p == '\r' || *j->p == '\t')) j->p++; }
+static int hex(unsigned char c) { return (c >= '0' && c <= '9') || (c >= 'a' && c <= 'f') || (c >= 'A' && c <= 'F'); }
+static int string(struct json *j) {
+    if (j->p == j->end || *j->p++ != '"') return 0;
+    while (j->p < j->end) {
+        unsigned char c = *j->p++;
+        if (c == '"') return 1;
+        if (c < 32) return 0;
+        if (c == '\\') {
+            if (j->p == j->end) return 0;
+            c = *j->p++;
+            if (c == 'u') {
+                for (int i = 0; i < 4; i++) if (j->p == j->end || !hex(*j->p++)) return 0;
+            } else if (!strchr("\"\\/bfnrt", c)) return 0;
+        } else if (c >= 128) {
+            unsigned int value; int count;
+            if (c >= 0xc2 && c <= 0xdf) { value = c & 31; count = 1; }
+            else if (c >= 0xe0 && c <= 0xef) { value = c & 15; count = 2; }
+            else if (c >= 0xf0 && c <= 0xf4) { value = c & 7; count = 3; }
+            else return 0;
+            int remaining = count;
+            while (remaining--) { if (j->p == j->end || (*j->p & 0xc0) != 0x80) return 0; value = (value << 6) | (*j->p++ & 63); }
+            if ((count == 2 && value < 0x800) || (count == 3 && value < 0x10000) || value > 0x10ffff || (value >= 0xd800 && value <= 0xdfff)) return 0;
+        }
+    }
+    return 0;
+}
+static int value(struct json *j, int depth) {
+    ws(j); if (depth > 64 || j->p == j->end) return 0;
+    unsigned char c = *j->p;
+    if (c == '"') return string(j);
+    if (c == '{' || c == '[') {
+        unsigned char stop = c == '{' ? '}' : ']'; j->p++; ws(j);
+        if (j->p < j->end && *j->p == stop) { j->p++; return 1; }
+        for (;;) {
+            if (c == '{') { if (!string(j)) return 0; ws(j); if (j->p == j->end || *j->p++ != ':') return 0; }
+            if (!value(j, depth + 1)) return 0;
+            ws(j); if (j->p == j->end) return 0;
+            unsigned char next = *j->p++; if (next == stop) return 1;
+            if (next != ',') return 0;
+            ws(j);
+        }
+    }
+    const char *literal = c == 't' ? "true" : c == 'f' ? "false" : c == 'n' ? "null" : NULL;
+    if (literal) { size_t n = strlen(literal); if ((size_t)(j->end - j->p) < n || memcmp(j->p, literal, n)) return 0; j->p += n; return 1; }
+    if (*j->p == '-') j->p++;
+    if (j->p == j->end) return 0;
+    if (*j->p == '0') j->p++;
+    else { if (*j->p < '1' || *j->p > '9') return 0; do { j->p++; } while (j->p < j->end && *j->p >= '0' && *j->p <= '9'); }
+    if (j->p < j->end && *j->p == '.') { j->p++; const unsigned char *start = j->p; while (j->p < j->end && *j->p >= '0' && *j->p <= '9') j->p++; if (j->p == start) return 0; }
+    if (j->p < j->end && (*j->p == 'e' || *j->p == 'E')) { j->p++; if (j->p < j->end && (*j->p == '+' || *j->p == '-')) j->p++; const unsigned char *start = j->p; while (j->p < j->end && *j->p >= '0' && *j->p <= '9') j->p++; if (j->p == start) return 0; }
+    return 1;
+}
+static int object(const unsigned char *bytes, size_t n) { struct json j = {bytes, bytes + n}; ws(&j); if (j.p == j.end || *j.p != '{' || !value(&j, 0)) return 0; ws(&j); return j.p == j.end; }
+static int write_all(int fd, const unsigned char *bytes, size_t length) {
+    while (length) { ssize_t n = write(fd, bytes, length); if (n <= 0) return 0; bytes += n; length -= (size_t)n; } return 1;
+}
+
+int main(int argc, char **argv) {
+    (void)argv;
+    alarm(30); umask(077); setvbuf(stdout, NULL, _IONBF, 0);
+    if (argc != 1) return 11;
+    if (environ && *environ && (environ[1] || strcmp(environ[0], "PWD=/"))) return 12;
+    if (clearenv()) return 13;
+    struct timespec started; if (clock_gettime(CLOCK_MONOTONIC, &started)) return 10;
+    int parent = open("/out", DIR_FLAGS); struct stat parent_stat, existing;
+    if (parent < 0 || fstat(parent, &parent_stat) || (parent_stat.st_mode & 0777) != 0700) return 10;
+    if (fstatat(parent, "attempt-3", &existing, AT_SYMLINK_NOFOLLOW) == 0 || errno != ENOENT) return 10;
+    unsigned long long dev, ino; FILE *identity = fopen("/identity", "r");
+    if (!identity || fscanf(identity, "%llu %llu", &dev, &ino) != 2 || dev != (unsigned long long)parent_stat.st_dev || ino != (unsigned long long)parent_stat.st_ino) return 10;
+    fclose(identity);
+    size_t total = 0;
+    for (int i = 0; i < 6; i++) {
+        char filename[128]; snprintf(filename, sizeof(filename), "/payload/%s", names[i]);
+        int fd = open(filename, O_RDONLY | O_NOFOLLOW | O_CLOEXEC); struct stat st;
+        if (fd < 0 || fstat(fd, &st) || !S_ISREG(st.st_mode) || st.st_size < 0 || st.st_size > LIMIT) return 10;
+        sizes[i] = (size_t)st.st_size; total += sizes[i]; if (total > LIMIT) return 10;
+        data[i] = malloc(sizes[i] + 1); if (!data[i]) return 10;
+        size_t offset = 0;
+        while (offset < sizes[i]) { ssize_t n = read(fd, data[i] + offset, sizes[i] - offset); if (n <= 0) return 10; offset += (size_t)n; }
+        close(fd); data[i][sizes[i]] = 0;
+    }
+    if (restrict_syscalls() || !isolation_probes(parent)) return 10;
+#ifdef PREPARATION_FIXTURE_NOT_READY
+    for (;;) { /* Test-only readiness stall, never a production build. */ }
+#endif
+    puts("READY");
+    char go; if (read(STDIN_FILENO, &go, 1) != 1 || go != 'G') return 10;
+    alarm(10);
+#ifdef PREPARATION_FIXTURE_STALL
+    for (;;) { /* Test-only compiled variant, approved only by fixture keys. */ }
+#endif
+    if (!object(data[0], sizes[0]) || !object(data[5], sizes[5])) return 20;
+    for (int i = 1; i < 5; i++) if (!sizes[i] || memchr(data[i], 0, sizes[i])) return 20;
+    puts("VALID");
+    struct timespec now; if (clock_gettime(CLOCK_MONOTONIC, &now)) return 20;
+    long elapsed = now.tv_sec - started.tv_sec; if (elapsed >= 30) return 20;
+    alarm((unsigned int)(30 - elapsed));
+    if (mkdirat(parent, "attempt-3", 0700)) return 30;
+    int dir = openat(parent, "attempt-3", DIR_FLAGS); struct stat directory_stat;
+    if (dir < 0 || fstat(dir, &directory_stat)) return 30;
+    printf("DIR %llu %llu\n", (unsigned long long)directory_stat.st_dev, (unsigned long long)directory_stat.st_ino);
+    for (int i = 0; i < 6; i++) {
+        int fd = openat(dir, names[i], FILE_FLAGS, 0600); struct stat st;
+        if (fd < 0 || fstat(fd, &st)) return 30;
+        printf("FILE %d %llu %llu\n", i, (unsigned long long)st.st_dev, (unsigned long long)st.st_ino);
+        if (fchmod(fd, 0600) || !write_all(fd, data[i], sizes[i]) || fsync(fd)) return 30;
+        close(fd);
+#ifdef PREPARATION_FIXTURE_PARTIAL
+        if (i == 0) return 30;
+#endif
+    }
+    if (fsync(dir) || fsync(parent)) return 30;
+    close(dir); close(parent); puts("DONE"); return 0;
+}

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

@@ -0,0 +1,3 @@
+import { type DoctorOptions } from "../../commands/doctor.js";
+export default function DoctorController({ dryRun, refreshContext, }: DoctorOptions): import("react").FunctionComponentElement<import("../../ui/Doctor.js").DoctorProps>;
+//# sourceMappingURL=doctor.d.ts.map

package/dist/cli/dispatch/doctor.js

@@ -0,0 +1,27 @@
+import { createElement, useEffect, useState } from "react";
+import { runDoctor } from "../../commands/doctor.js";
+import Doctor from "../../ui/Doctor.js";
+export default function DoctorController({ dryRun = false, refreshContext = false, }) {
+    const [result, setResult] = useState(null);
+    const [error, setError] = useState(null);
+    const [loading, setLoading] = useState(true);
+    const runCheck = () => {
+        setLoading(true);
+        setResult(null);
+        setError(null);
+        void runDoctor(undefined, { dryRun, refreshContext })
+            .then((nextResult) => {
+            setResult(nextResult);
+            setLoading(false);
+        })
+            .catch((nextError) => {
+            setError(String(nextError));
+            setLoading(false);
+        });
+    };
+    useEffect(() => {
+        runCheck();
+    }, [dryRun, refreshContext]);
+    return createElement(Doctor, { loading, result, error, onRerun: runCheck });
+}
+//# sourceMappingURL=doctor.js.map

package/dist/cli/dispatch/simple-renderers.d.ts

@@ -15,7 +15,7 @@ export interface RendererDeps {
     error?: (message: string) => void;
     setExitCode?: (code: number) => void;
 }
-export declare function handleDoctor(_cli: CLI, ctx: RendererCtx, deps?: RendererDeps): void;
+export declare function handleDoctor(cli: CLI, ctx: RendererCtx, deps?: RendererDeps): void;
 export declare function handleAnalyze(cli: CLI, ctx: RendererCtx): void;
 export declare function handleLlmsTxt(cli: CLI, ctx: RendererCtx): void;
 export declare function handlePlugin(cli: CLI, ctx: RendererCtx): void;

package/dist/cli/dispatch/simple-renderers.js

@@ -13,11 +13,11 @@ import { resolvePlatformSupport } from "../../lib/platform-support.js";
 import AnalyzeUI from "../../ui/AnalyzeUI.js";
 import App from "../../ui/App.js";
 import { CIProvider as CIContextProvider } from "../../ui/CIContext.js";
-import Doctor from "../../ui/Doctor.js";
 import LlmsTxt from "../../ui/LlmsTxt.js";
 import Plugin from "../../ui/Plugin.js";
 import { VALID_CI, VALID_MEMORY, VALID_STACKS } from "../validators.js";
-export function handleDoctor(_cli, ctx, deps = {}) {
+import DoctorController from "./doctor.js";
+export function handleDoctor(cli, ctx, deps = {}) {
     const platformSupport = resolvePlatformSupport(deps.platform ?? process.platform);
     if (platformSupport) {
         (deps.error ?? console.error)(`${platformSupport.refusalCode}: ${platformSupport.guidance}`);
@@ -28,7 +28,7 @@ export function handleDoctor(_cli, ctx, deps = {}) {
         return;
     }
     (deps.render ?? render)(React.createElement(CIContextProvider, { isCI: ctx.isCI },
-        React.createElement(Doctor, null)), { stdin: ctx.inkStdin });
+        React.createElement(DoctorController, { dryRun: cli.flags.dryRun === true, refreshContext: cli.flags.refreshContext === true })), { stdin: ctx.inkStdin });
 }
 export function handleAnalyze(cli, ctx) {
     render(React.createElement(CIContextProvider, { isCI: ctx.isCI },

package/dist/cli/help.d.ts

@@ -8,7 +8,7 @@
  * Help banner shown by meow when `--help` is passed or invalid args are supplied.
  * Multi-line template literal — preserve exact formatting (whitespace is significant).
  */
-export declare const HELP_TEXT = "\n  Usage\n    $ javi-forge [command] [options]\n\n  Commands\n    init              Bootstrap a new project (default)\n    ci                Run CI simulation (lint + compile + test + security + ghagga)\n    ci validate       Validate .javi-forge/ci.yaml without running anything\n    ci init           Install git hooks that call javi-forge ci\n    tdd init          Enable the TDD pre-commit section + install managed hooks\n    tdd pipeline      Enable the TDD pre-push section (--mode strict|warn)\n    hooks run         Run a git hook's composed sections (pre-commit | pre-push)\n    analyze           Run repoforge skills analysis\n    doctor            Show health report\n    workflow show     Render a workflow graph as ASCII (--template <name> or file path)\n    workflow validate Validate project state against a workflow graph\n    workflow list     List available workflows and built-in templates\n    plugin add        Install a plugin from GitHub (org/repo)\n    plugin remove     Remove an installed plugin\n    plugin list       List installed plugins\n    plugin search     Search the plugin registry\n    plugin validate   Validate a local plugin directory\n    plugin sync       Auto-detect and wire installed plugins\n    plugin export     Export plugin to Agent Skills spec format (skills.json)\n    plugin export     --codex: Export plugin to Codex-compatible TOML subagent files\n    plugin export-skills  Generate aggregated skills.json from all installed plugins\n    plugin export-skills global  Generate global skills.json from all globally installed plugins\n    plugin import     Import an Agent Skills spec package as a javi-forge plugin\n    skills doctor     Show skills health report (add --deep for conflict detection)\n    skills budget     Show token cost of loaded skills (add -b N for custom budget)\n    skills score      Score a skill on quality dimensions (completeness, clarity, testability, token-efficiency)\n    skills benchmark  Benchmark a skill with structural quality checks\n    skills auto       Auto-detect project stack and suggest/install matching AI skills\n    skills auto-install  Alias for skills auto\n    skill publish     Package a skill directory for marketplace distribution (generates plugin.json)\n    security baseline   Create security baseline from current audit findings\n    security check      Check for regressions against baseline (exits non-zero if found)\n    security update     Re-snapshot baseline (acknowledge current vulns)\n    security allowlist  Add all current findings to the allowlist (suppress in future checks)\n    llms-txt          Generate AI-friendly llms.txt for current project\n\n  Options\n    --dry-run       Preview changes without writing files\n    --stack         Project stack (node, python, go, rust, java-gradle, java-maven, elixir)\n    --ci            CI provider (github, gitlab, woodpecker)\n    --memory        Memory module (engram, obsidian-brain, memory-simple, none)\n    --project-name  Project name (skips name prompt)\n    --ghagga        Enable GHAGGA review system\n    --mock          Enable mock-first mode (no real API keys needed)\n    --local-ai      Include local AI dev stack (Ollama + Docker Compose)\n    --batch         Non-interactive mode (auto-proceed, no keyboard input)\n    --deep          Enable deep analysis (conflict + duplicate detection)\n    --budget, -b    Token budget limit for skills (default: 8000)\n    --skills-dir    Custom skills directory path\n    --author        Author name for skill publish\n    --repo          Repository URL for skill publish\n    --version       Show version\n    --help          Show this help\n\n  CI options (javi-forge ci)\n    --quick         Lint + compile only (fast, for pre-commit)\n    --shell         Open interactive shell in CI container\n    --detect        Show detected stack and exit\n    --config PATH   Load ordered CI runners from a versioned config file\n                    (default discovery: .javi-forge/ci.yaml)\n    --stack STACK   Force a single explicit stack (single-stack repos only \u2014\n                    insufficient for hybrid repos; use --config instead)\n    --no-docker     Run commands natively (no Docker)\n    --no-ci-ghagga  Skip GHAGGA review\n    --no-security   Skip Semgrep security scan\n    --timeout N     Per-step timeout in seconds (default: 600)\n\n  CI hooks (javi-forge ci init)\n    Install git hooks that call javi-forge ci.\n    No files copied \u2014 hooks reference the global CLI.\n    Existing hooks javi-forge did not write are refused, never clobbered.\n    --force         Overwrite a foreign or locally modified hook. The previous\n                    content is copied to a .bak sibling first; if that backup\n                    cannot be written, the hook is left untouched. Symlinked\n                    hook paths are refused even with --force.\n\n  SkillGuard install gate (plugin add / plugin import / skills auto)\n    Every install is scanned before anything is written. Refusals are\n    fail-closed and name the offending files:\n    - SKILL.md files that block (critical threats) are refused \u2014 always.\n    - Unscannable files (binary, oversized, unreadable) are refused unless\n      --force is given.\n    - Symlinks anywhere in the tree and SKILL.md files outside the declared\n      set are manifest-integrity refusals \u2014 they are refused even with --force.\n    - Empty or missing skills.json `skills` array on import is refused.\n    A refused install/auto-install exits non-zero (exit 1) so scripts and CI\n    can tell a refusal apart from success; clean installs \u2014 including\n    --force-lifted unscannable ones \u2014 exit 0.\n\n  Examples\n    $ javi-forge\n    $ javi-forge init --dry-run\n    $ javi-forge init --stack node --ci github\n    $ javi-forge ci\n    $ javi-forge ci init\n    $ javi-forge ci init --force\n    $ javi-forge plugin add org/repo\n    $ javi-forge plugin add org/repo --force\n    $ javi-forge tdd init\n    $ javi-forge ci --quick\n    $ javi-forge ci --no-ci-ghagga --no-security\n    $ javi-forge ci --no-docker\n    $ javi-forge ci --shell\n    $ javi-forge ci --config .javi-forge/ci.yaml\n    $ javi-forge ci validate\n    $ javi-forge ci --help\n    $ javi-forge analyze\n    $ javi-forge doctor\n    $ javi-forge plugin add mapbox/agent-skills\n    $ javi-forge plugin list\n";
+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    --refresh-context  Refresh .context/ during doctor (writes INDEX.md, summary.md, manifest timestamp)\n    --deep          Enable deep analysis (conflict + duplicate detection)\n    --budget, -b    Token budget limit for skills (default: 8000)\n    --skills-dir    Custom skills directory path\n    --author        Author name for skill publish\n    --repo          Repository URL for skill publish\n    --version       Show version\n    --help          Show this help\n\n  CI options (javi-forge ci)\n    --quick         Lint + compile only (fast, for pre-commit)\n    --shell         Open interactive shell in CI container\n    --detect        Show detected stack and exit\n    --config PATH   Load ordered CI runners from a versioned config file\n                    (default discovery: .javi-forge/ci.yaml)\n    --stack STACK   Force a single explicit stack (single-stack repos only \u2014\n                    insufficient for hybrid repos; use --config instead)\n    --no-docker     Run commands natively (no Docker)\n    --no-ci-ghagga  Skip GHAGGA review\n    --no-security   Skip Semgrep security scan\n    --timeout N     Per-step timeout in seconds (default: 600)\n\n  CI hooks (javi-forge ci init)\n    Install git hooks that call javi-forge ci.\n    No files copied \u2014 hooks reference the global CLI.\n    Existing hooks javi-forge did not write are refused, never clobbered.\n    --force         Overwrite a foreign or locally modified hook. The previous\n                    content is copied to a .bak sibling first; if that backup\n                    cannot be written, the hook is left untouched. Symlinked\n                    hook paths are refused even with --force.\n\n  SkillGuard install gate (plugin add / plugin import / skills auto)\n    Every install is scanned before anything is written. Refusals are\n    fail-closed and name the offending files:\n    - SKILL.md files that block (critical threats) are refused \u2014 always.\n    - Unscannable files (binary, oversized, unreadable) are refused unless\n      --force is given.\n    - Symlinks anywhere in the tree and SKILL.md files outside the declared\n      set are manifest-integrity refusals \u2014 they are refused even with --force.\n    - Empty or missing skills.json `skills` array on import is refused.\n    A refused install/auto-install exits non-zero (exit 1) so scripts and CI\n    can tell a refusal apart from success; clean installs \u2014 including\n    --force-lifted unscannable ones \u2014 exit 0.\n\n  Examples\n    $ javi-forge\n    $ javi-forge init --dry-run\n    $ javi-forge init --stack node --ci github\n    $ javi-forge ci\n    $ javi-forge ci init\n    $ javi-forge ci init --force\n    $ javi-forge plugin add org/repo\n    $ javi-forge plugin add org/repo --force\n    $ javi-forge tdd init\n    $ javi-forge ci --quick\n    $ javi-forge ci --no-ci-ghagga --no-security\n    $ javi-forge ci --no-docker\n    $ javi-forge ci --shell\n    $ javi-forge ci --config .javi-forge/ci.yaml\n    $ javi-forge ci validate\n    $ javi-forge ci --help\n    $ javi-forge analyze\n    $ javi-forge doctor\n    $ javi-forge plugin add mapbox/agent-skills\n    $ javi-forge plugin list\n";
 /**
  * Per-command help for `ci`, shown by `javi-forge ci --help` (or when `ci` is
  * given an unknown subcommand). Kept consistent with the global HELP_TEXT
@@ -30,6 +30,10 @@ export declare const FLAGS_SCHEMA: {
         readonly type: "boolean";
         readonly default: false;
     };
+    readonly refreshContext: {
+        readonly type: "boolean";
+        readonly default: false;
+    };
     readonly stack: {
         readonly type: "string";
         readonly default: "";

package/dist/cli/help.js

@@ -59,6 +59,7 @@ export const HELP_TEXT = `
     --mock          Enable mock-first mode (no real API keys needed)
     --local-ai      Include local AI dev stack (Ollama + Docker Compose)
     --batch         Non-interactive mode (auto-proceed, no keyboard input)
+    --refresh-context  Refresh .context/ during doctor (writes INDEX.md, summary.md, manifest timestamp)
     --deep          Enable deep analysis (conflict + duplicate detection)
     --budget, -b    Token budget limit for skills (default: 8000)
     --skills-dir    Custom skills directory path
@@ -214,6 +215,7 @@ export const FLAGS_SCHEMA = {
     // `ci --help` can show ci-specific usage instead of the global banner).
     help: { type: "boolean", shortFlag: "h", default: false },
     dryRun: { type: "boolean", default: false },
+    refreshContext: { type: "boolean", default: false },
     stack: { type: "string", default: "" },
     ci: { type: "string", default: "" },
     memory: { type: "string", default: "" },

package/dist/cli/main.js

@@ -10,11 +10,21 @@ import { handleTdd } from "./dispatch/tdd.js";
 import { handleWorkflow } from "./dispatch/workflow.js";
 import { FLAGS_SCHEMA, HELP_TEXT } from "./help.js";
 import { createInkStdin, detectCI, setupUpdateNotifier } from "./runtime.js";
+const KNOWN_COMMANDS = new Set([
+    "init",
+    "tdd",
+    "ci",
+    "hooks",
+    "doctor",
+    "analyze",
+    "workflow",
+    "llms-txt",
+    "plugin",
+    "skills",
+    "skill",
+    "security",
+]);
 export async function runCli() {
-    // Check for updates in background (non-blocking, cached 24h)
-    const _require = createRequire(import.meta.url);
-    const pkg = _require("../../package.json");
-    setupUpdateNotifier(pkg);
     const cli = meow(HELP_TEXT, {
         importMeta: import.meta,
         flags: FLAGS_SCHEMA,
@@ -23,12 +33,23 @@ export async function runCli() {
         autoHelp: false,
     });
     const subcommand = cli.input[0] ?? "init";
+    if (!KNOWN_COMMANDS.has(subcommand)) {
+        console.error(`Unknown command "${subcommand}". Run javi-forge --help for usage.`);
+        process.exit(1);
+    }
     // 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);
     }
+    // Check for updates in background (non-blocking, cached 24h). Diagnostics and
+    // dry-runs must not create notifier cache/state before doing their actual work.
+    if (subcommand !== "doctor" && !cli.flags.dryRun) {
+        const _require = createRequire(import.meta.url);
+        const pkg = _require("../../package.json");
+        setupUpdateNotifier(pkg);
+    }
     const isCI = detectCI(cli.flags);
     const inkStdin = createInkStdin();
     switch (subcommand) {
@@ -76,7 +97,7 @@ export async function runCli() {
             await handleSecurity(cli);
             break;
         }
-        default: {
+        case "init": {
             handleInitDefault(cli, { inkStdin, isCI });
             break;
         }

package/dist/commands/doctor.d.ts

@@ -1,12 +1,16 @@
 import fs from "fs-extra";
 import { detectStack } from "../lib/common.js";
-import { refreshContextDir } from "../lib/context.js";
+import { detectDependenciesDetailed, refreshContextDir } from "../lib/context.js";
 import { execFileAsync } from "../lib/exec.js";
 import { listInstalledPlugins } from "../lib/plugin.js";
 import type { DoctorResult } from "../types/index.js";
 export type CheckStatus = "ok" | "fail" | "skip";
 type DoctorFilesystem = Pick<typeof fs, "pathExists" | "readJson" | "readdir">;
-export interface DoctorDeps {
+export interface DoctorOptions {
+    dryRun?: boolean;
+    refreshContext?: boolean;
+}
+export interface DoctorDeps extends DoctorOptions {
     platform?: string;
     cwd?: () => string;
     filesystem?: DoctorFilesystem;
@@ -14,6 +18,7 @@ export interface DoctorDeps {
     stackDetector?: typeof detectStack;
     pluginLister?: typeof listInstalledPlugins;
     contextRefresher?: typeof refreshContextDir;
+    dependencyDetector?: typeof detectDependenciesDetailed;
 }
 interface RemoteInfo {
     host: "github" | "gitlab" | "other";

package/dist/commands/doctor.js

@@ -2,7 +2,7 @@ import path from "node:path";
 import fs from "fs-extra";
 import { FORGE_ROOT, MODULES_DIR, PLUGINS_DIR, TEMPLATES_DIR, } from "../constants.js";
 import { detectStack } from "../lib/common.js";
-import { refreshContextDir } from "../lib/context.js";
+import { detectDependenciesDetailed, refreshContextDir, } from "../lib/context.js";
 import { execFileAsync } from "../lib/exec.js";
 import { resolvePlatformSupport } from "../lib/platform-support.js";
 import { listInstalledPlugins } from "../lib/plugin.js";
@@ -162,6 +162,7 @@ export async function runDoctor(projectDir, deps = {}) {
     const stackDetector = deps.stackDetector ?? detectStack;
     const pluginLister = deps.pluginLister ?? listInstalledPlugins;
     const contextRefresher = deps.contextRefresher ?? refreshContextDir;
+    const dependencyDetector = deps.dependencyDetector ?? detectDependenciesDetailed;
     const sections = [];
     // ── 1. System Tools ────────────────────────────────────────────────────────
     const toolChecks = [];
@@ -328,19 +329,37 @@ export async function runDoctor(projectDir, deps = {}) {
         });
     }
     sections.push({ title: "Plugins", checks: pluginChecks });
-    // ── 7. Context Directory Refresh ───────────────────────────────────────────
+    // ── 7. Context Directory (refresh is explicit) ──────────────────────────────
     const contextChecks = [];
     try {
-        const result = await contextRefresher(cwd);
-        if (result) {
+        if (deps.refreshContext && !deps.dryRun) {
+            const result = await contextRefresher(cwd);
             contextChecks.push({
                 label: ".context/ refresh",
-                status: "ok",
-                detail: "INDEX.md + summary.md updated",
+                status: result ? "ok" : "skip",
+                detail: result
+                    ? "INDEX.md + summary.md updated"
+                    : "no .context/ or no manifest found",
             });
-            // A manifest that could not be read is not "no dependencies" — surface
-            // each warning so an unreadable/oversized/invalid manifest is visible.
-            for (const warning of result.warnings) {
+            for (const warning of result?.warnings ?? []) {
+                contextChecks.push({
+                    label: "dependency manifest",
+                    status: "fail",
+                    detail: warning,
+                });
+            }
+        }
+        else if (manifest &&
+            (await filesystem.pathExists(path.join(cwd, ".context")))) {
+            contextChecks.push({
+                label: ".context/",
+                status: deps.refreshContext ? "skip" : "ok",
+                detail: deps.refreshContext
+                    ? "dry-run: would refresh INDEX.md + summary.md and manifest timestamp"
+                    : "present; not refreshed (use --refresh-context to update)",
+            });
+            const { warnings } = await dependencyDetector(cwd, manifest.stack);
+            for (const warning of warnings) {
                 contextChecks.push({
                     label: "dependency manifest",
                     status: "fail",
@@ -350,17 +369,17 @@ export async function runDoctor(projectDir, deps = {}) {
         }
         else {
             contextChecks.push({
-                label: ".context/ refresh",
+                label: ".context/",
                 status: "skip",
                 detail: "no .context/ or no manifest found",
             });
         }
     }
-    catch (e) {
+    catch (error) {
         contextChecks.push({
-            label: ".context/ refresh",
+            label: ".context/",
             status: "fail",
-            detail: `refresh failed: ${String(e)}`,
+            detail: `context check failed: ${error instanceof Error ? error.message : String(error)}`,
         });
     }
     sections.push({ title: "Context Directory", checks: contextChecks });

package/dist/commands/plugin.d.ts

@@ -17,7 +17,9 @@ export declare function runPluginList(onStep: StepCallback): Promise<void>;
 /**
  * Search the remote plugin registry.
  */
-export declare function runPluginSearch(query: string | undefined, onStep: StepCallback): Promise<void>;
+export declare function runPluginSearch(query: string | undefined, onStep: StepCallback, options?: {
+    signal?: AbortSignal;
+}): Promise<void>;
 /**
  * Validate a local plugin directory.
  */

package/dist/commands/plugin.js

@@ -4,6 +4,22 @@ import { installPlugin, listInstalledPlugins, removePlugin, searchRegistry, sync
 function report(onStep, id, label, status, detail) {
     onStep({ id, label, status, detail });
 }
+function successDetail(action, dryRun, result) {
+    const verb = action === "install" ? "install" : "import";
+    const past = action === "install" ? "installed" : "imported";
+    const lines = [
+        dryRun ? `dry-run: would ${verb} ${result.name}` : `${past} ${result.name}`,
+    ];
+    if (result.warning)
+        lines.push(`warning: ${result.warning}`);
+    if (result.recoveryPaths?.length) {
+        lines.push("manual recovery paths:");
+        for (const recoveryPath of result.recoveryPaths) {
+            lines.push(`  - ${recoveryPath}`);
+        }
+    }
+    return lines.join("\n");
+}
 /**
  * Add (install) a plugin from a GitHub source.
  */
@@ -12,9 +28,7 @@ export async function runPluginAdd(source, dryRun, onStep, options = {}) {
     report(onStep, stepId, `Install plugin: ${source}`, "running");
     const result = await installPlugin(source, { dryRun, force: options.force });
     if (result.success) {
-        report(onStep, stepId, `Install plugin: ${source}`, "done", dryRun
-            ? `dry-run: would install ${result.name}`
-            : `installed ${result.name}`);
+        report(onStep, stepId, `Install plugin: ${source}`, "done", successDetail("install", dryRun, result));
     }
     else {
         report(onStep, stepId, `Install plugin: ${source}`, "error", result.error);
@@ -58,10 +72,10 @@ export async function runPluginList(onStep) {
 /**
  * Search the remote plugin registry.
  */
-export async function runPluginSearch(query, onStep) {
+export async function runPluginSearch(query, onStep, options = {}) {
     const stepId = "plugin-search";
     report(onStep, stepId, `Search plugins${query ? `: ${query}` : ""}`, "running");
-    const results = await searchRegistry(query);
+    const results = await searchRegistry(query, options);
     if (results.status === "cancelled") {
         report(onStep, stepId, `Search plugins${query ? `: ${query}` : ""}`, "error", "registry search cancelled");
     }
@@ -163,9 +177,7 @@ export async function runPluginImport(sourceDir, dryRun, onStep, options = {}) {
         force: options.force,
     });
     if (result.success) {
-        report(onStep, stepId, `Import agent-skills package: ${sourceDir}`, "done", dryRun
-            ? `dry-run: would import ${result.name}`
-            : `imported ${result.name}`);
+        report(onStep, stepId, `Import agent-skills package: ${sourceDir}`, "done", successDetail("import", dryRun, result));
     }
     else {
         report(onStep, stepId, `Import agent-skills package: ${sourceDir}`, "error", result.error);

package/dist/lib/__fixtures__/fake-secure-fs.js

@@ -177,16 +177,19 @@ export function makeFakeSecureFs() {
         },
         async renameInDir(dir, from, to) {
             if (fake.faults.renameRefuse?.(to))
-                return unsafe(`rename ${to}`);
+                return { ...unsafe(`rename ${to}`), mutation: "not-applied" };
             const fromP = path.join(dir.path, from);
             const toP = path.join(dir.path, to);
             const file = files.get(fromP);
             if (!file)
-                return unsafe(`rename enoent ${fromP}`);
+                return {
+                    ...unsafe(`rename enoent ${fromP}`),
+                    mutation: "not-applied",
+                };
             files.set(toP, file);
             files.delete(fromP);
             inos.delete(toP); // fresh identity for the renamed-in target
-            return ok();
+            return { ok: true, mutation: "applied" };
         },
         async unlinkIfIdentity(dir, name, _held) {
             const full = path.join(dir.path, name);