@groundtrack/hooks 0.1.1 → 0.1.2

package/README.md

@@ -9,12 +9,43 @@ Codex, and Cursor hook configurations:
 npm install -g @groundtrack/hooks
 ```
 
-The command reads a pre-tool-use hook payload from standard input and enriches
-Groundtrack `store_event` calls with:
+## Doctor CLI
+
+The same package installs a deterministic `groundtrack` CLI. Run it from a
+repository root:
+
+```bash
+groundtrack doctor
+groundtrack doctor --fix
+```
+
+`doctor` checks the installed package/runtime version, discovers the actual
+Groundtrack MCP server alias, validates Claude/Codex/Cursor hook configuration,
+checks the managed `AGENTS.md` and `CLAUDE.md` instructions, and simulates a
+hook invocation. It exits non-zero when repair is needed.
+
+`doctor --fix` previews the diagnosis, asks before changing anything, updates
+only Groundtrack-owned hook entries and versioned managed instruction blocks,
+then repeats the verification. Use `--yes` for an explicitly authorized
+unattended repair. Existing surrounding instructions and unrelated hooks are
+preserved; malformed JSON and symbolic links are reported instead of
+overwritten.
+
+The CLI compares its package version with npm. Canonical hook configuration and
+instruction templates ship inside that versioned package, so repair does not
+depend on an LLM or download arbitrary configuration text.
+
+`templates/AGENTS.md` is the single source of truth for the managed repository
+policy. After changing it, run `pnpm sync:agent-instructions` to regenerate the
+setup-guide example; tests reject drift between the generated copy and the
+packaged template.
+
+The `groundtrack-hook` command reads a pre-tool-use hook payload from standard input and enriches
+Groundtrack `store_event` and `search_experiences` calls with:
 
 - the client session and model identifiers (using Claude's host-provided
   transcript path when its hook payload omits the model);
-- a stable client event id derived from the host's tool invocation id; and
+- for `store_event`, a stable client event id derived from the host's tool invocation id; and
 - repository, branch, commit, and dirty-worktree context collected with Git.
 
 The Git context is collected from the hook's working directory (or a single

package/dist/agent-instructions.js

@@ -0,0 +1,10 @@
+import { readFileSync } from "node:fs";
+const VERSION_PATTERN = /^<!-- groundtrack:start version=(\d+) -->/;
+/** Canonical managed Groundtrack policy, packaged with the CLI. */
+export const AGENT_INSTRUCTION_BODY = readFileSync(new URL("../templates/AGENTS.md", import.meta.url), "utf8").trim();
+const versionMatch = VERSION_PATTERN.exec(AGENT_INSTRUCTION_BODY);
+if (!versionMatch) {
+    throw new Error("Canonical Groundtrack AGENTS.md template is missing its version marker.");
+}
+/** Version is derived from the canonical template marker; never define it separately. */
+export const AGENT_INSTRUCTION_TEMPLATE_VERSION = Number(versionMatch[1]);

package/dist/doctor.js

@@ -0,0 +1,527 @@
+import { execFileSync, spawnSync } from "node:child_process";
+import { existsSync, lstatSync, mkdirSync, readFileSync, renameSync, statSync, unlinkSync, writeFileSync, } from "node:fs";
+import { dirname, join } from "node:path";
+import { AGENT_INSTRUCTION_BODY, AGENT_INSTRUCTION_TEMPLATE_VERSION, } from "./agent-instructions.js";
+import { hookOutput } from "./enrich-store-event.js";
+import { packageVersion } from "./version.js";
+const HOOK_TEMPLATE_VERSION = 1;
+const MANAGED_START = `<!-- groundtrack:start version=${AGENT_INSTRUCTION_TEMPLATE_VERSION} -->`;
+const MANAGED_END = "<!-- groundtrack:end -->";
+const CLAUDE_INSTRUCTION_BODY = `${MANAGED_START}
+@AGENTS.md
+${MANAGED_END}`;
+const UNMARKED_AGENT_INSTRUCTION_BODY = AGENT_INSTRUCTION_BODY.replace(MANAGED_START, "")
+    .replace(MANAGED_END, "")
+    .trim();
+const CLAUDE_USER_MATCHER = "^mcp__.+__(store_event|search_experiences)$";
+const LEGACY_AGENT_SIGNATURE = "Use Groundtrack as the shared engineering memory for this repository.";
+function readText(path) {
+    return existsSync(path) ? readFileSync(path, "utf8") : null;
+}
+function writeAtomic(path, content) {
+    mkdirSync(dirname(path), { recursive: true });
+    if (existsSync(path) && lstatSync(path).isSymbolicLink()) {
+        throw new Error("refusing to replace a symbolic link");
+    }
+    const temporary = `${path}.groundtrack-${process.pid}.tmp`;
+    try {
+        const mode = existsSync(path) ? statSync(path).mode & 0o777 : 0o644;
+        writeFileSync(temporary, content, { mode });
+        renameSync(temporary, path);
+    }
+    catch (error) {
+        if (existsSync(temporary))
+            unlinkSync(temporary);
+        throw error;
+    }
+}
+function readJson(path) {
+    const raw = readText(path);
+    if (raw == null)
+        return {};
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new Error(`${path} must contain a JSON object.`);
+    }
+    return parsed;
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function matcherForAliases(aliases) {
+    const escaped = aliases.map(escapeRegExp);
+    const server = escaped.length === 1 ? escaped[0] : `(?:${escaped.join("|")})`;
+    return `^mcp__${server}__(store_event|search_experiences)$`;
+}
+function groundtrackAliases(repoDir) {
+    const aliases = new Set();
+    for (const relative of [".mcp.json", ".cursor/mcp.json"]) {
+        const path = join(repoDir, relative);
+        try {
+            const config = readJson(path);
+            const servers = config.mcpServers;
+            if (!servers || typeof servers !== "object" || Array.isArray(servers))
+                continue;
+            for (const [name, value] of Object.entries(servers)) {
+                const serialized = JSON.stringify(value).toLowerCase();
+                if (name.toLowerCase().includes("groundtrack") || serialized.includes("groundtrack")) {
+                    aliases.add(name);
+                }
+            }
+        }
+        catch {
+            // The owning adapter reports malformed config; alias discovery stays fail-open.
+        }
+    }
+    const codex = readText(join(repoDir, ".codex/config.toml")) ?? "";
+    const table = /^\[mcp_servers\.([^\]]+)\]([\s\S]*?)(?=^\[|(?![\s\S]))/gm;
+    for (const match of codex.matchAll(table)) {
+        if (match[1]?.toLowerCase().includes("groundtrack") || match[2]?.includes("groundtrack")) {
+            aliases.add(match[1]);
+        }
+    }
+    if (aliases.size === 0)
+        aliases.add("groundtrack");
+    return [...aliases].sort();
+}
+function detectClients(repoDir) {
+    const clients = [];
+    if (existsSync(join(repoDir, ".claude")) || existsSync(join(repoDir, ".mcp.json"))) {
+        clients.push("claude");
+    }
+    if (existsSync(join(repoDir, ".codex")))
+        clients.push("codex");
+    if (existsSync(join(repoDir, ".cursor")))
+        clients.push("cursor");
+    return clients.length > 0 ? clients : ["claude"];
+}
+function asRecord(value) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : null;
+}
+function commandOf(value) {
+    return typeof asRecord(value)?.command === "string" ? asRecord(value).command : null;
+}
+function claudeHookIsCurrent(config, matcher) {
+    const hooks = asRecord(config.hooks);
+    const preToolUse = hooks?.PreToolUse;
+    if (!Array.isArray(preToolUse))
+        return false;
+    return preToolUse.some((entry) => {
+        const record = asRecord(entry);
+        return (record?.matcher === matcher &&
+            Array.isArray(record.hooks) &&
+            record.hooks.some((hook) => commandOf(hook) === "groundtrack-hook claude"));
+    });
+}
+function upsertClaudeHook(config, matcher) {
+    const hooks = asRecord(config.hooks) ?? {};
+    const existing = Array.isArray(hooks.PreToolUse) ? hooks.PreToolUse : [];
+    const retained = existing.filter((entry) => {
+        const record = asRecord(entry);
+        return !(Array.isArray(record?.hooks) &&
+            record.hooks.some((hook) => commandOf(hook)?.includes("groundtrack-hook")));
+    });
+    return {
+        ...config,
+        hooks: {
+            ...hooks,
+            PreToolUse: [
+                ...retained,
+                {
+                    matcher,
+                    hooks: [
+                        {
+                            type: "command",
+                            command: "groundtrack-hook claude",
+                            timeout: 5,
+                            statusMessage: "Adding Groundtrack session metadata",
+                        },
+                    ],
+                },
+            ],
+        },
+    };
+}
+function cursorHookIsCurrent(config) {
+    const hooks = asRecord(config.hooks);
+    const preToolUse = hooks?.preToolUse;
+    return (Array.isArray(preToolUse) &&
+        preToolUse.some((entry) => {
+            const record = asRecord(entry);
+            return (record?.command === "groundtrack-hook" &&
+                record.matcher ===
+                    "MCP:.*(store_event|search_experiences)|MCP:(store_event|search_experiences)");
+        }));
+}
+function upsertCursorHook(config) {
+    const hooks = asRecord(config.hooks) ?? {};
+    const existing = Array.isArray(hooks.preToolUse) ? hooks.preToolUse : [];
+    const retained = existing.filter((entry) => !commandOf(entry)?.includes("groundtrack-hook"));
+    return {
+        version: typeof config.version === "number" ? config.version : 1,
+        ...config,
+        hooks: {
+            ...hooks,
+            preToolUse: [
+                ...retained,
+                {
+                    command: "groundtrack-hook",
+                    matcher: "MCP:.*(store_event|search_experiences)|MCP:(store_event|search_experiences)",
+                },
+            ],
+        },
+    };
+}
+function codexBlock(matcher) {
+    return `# groundtrack:start version=${HOOK_TEMPLATE_VERSION}
+[[hooks.PreToolUse]]
+matcher = ${JSON.stringify(matcher)}
+
+[[hooks.PreToolUse.hooks]]
+type = "command"
+command = "groundtrack-hook"
+timeout = 5
+statusMessage = "Adding Groundtrack session metadata"
+# groundtrack:end`;
+}
+function codexHookIsCurrent(content, matcher) {
+    return (content.includes(`matcher = ${JSON.stringify(matcher)}`) &&
+        content.includes('command = "groundtrack-hook"'));
+}
+function upsertCodexHook(content, matcher) {
+    const managed = /(?:^|\n)# groundtrack:start version=\d+\n[\s\S]*?\n# groundtrack:end(?:\n|$)/;
+    const desired = codexBlock(matcher);
+    if (managed.test(content)) {
+        return `${content.replace(managed, `\n${desired}\n`).trimEnd()}\n`;
+    }
+    const lines = content.split("\n");
+    const ranges = [];
+    for (let index = 0; index < lines.length; index += 1) {
+        if (lines[index]?.trim() !== "[[hooks.PreToolUse]]")
+            continue;
+        let end = index + 1;
+        while (end < lines.length) {
+            const trimmed = lines[end].trim();
+            if (trimmed === "[[hooks.PreToolUse]]")
+                break;
+            if (/^\[[^[]/.test(trimmed))
+                break;
+            end += 1;
+        }
+        if (lines.slice(index, end).join("\n").includes("groundtrack-hook"))
+            ranges.push([index, end]);
+        index = end - 1;
+    }
+    for (const [start, end] of ranges.reverse())
+        lines.splice(start, end - start);
+    const base = lines.join("\n").trimEnd();
+    return `${base}${base ? "\n\n" : ""}${desired}\n`;
+}
+function managedContentIsCurrent(content, desired) {
+    if (!content)
+        return false;
+    const start = content.indexOf(MANAGED_START);
+    const end = content.indexOf(MANAGED_END, start);
+    return start >= 0 && end >= 0 && content.slice(start, end + MANAGED_END.length) === desired;
+}
+function claudeInstructionsAreCurrent(content) {
+    if (!content)
+        return false;
+    return (/^@AGENTS\.md$/m.test(content) ||
+        managedContentIsCurrent(content, AGENT_INSTRUCTION_BODY) ||
+        content.includes(UNMARKED_AGENT_INSTRUCTION_BODY));
+}
+function claudeUsesInlineGroundtrackInstructions(content) {
+    return content?.includes(LEGACY_AGENT_SIGNATURE) ?? false;
+}
+function removeLegacyAgentInstructions(content) {
+    const lines = content.split("\n");
+    for (let index = lines.length - 1; index >= 0; index -= 1) {
+        const heading = /^(#{1,6})\s+Groundtrack\s*$/.exec(lines[index].trim());
+        if (!heading)
+            continue;
+        const level = heading[1].length;
+        let end = index + 1;
+        while (end < lines.length) {
+            const nextHeading = /^(#{1,6})\s+/.exec(lines[end].trim());
+            if (nextHeading && nextHeading[1].length <= level)
+                break;
+            end += 1;
+        }
+        if (!lines.slice(index, end).join("\n").includes(LEGACY_AGENT_SIGNATURE))
+            continue;
+        let start = index;
+        if (start > 0 && lines[start - 1].trim() === "")
+            start -= 1;
+        lines.splice(start, end - start);
+        index = start;
+    }
+    return lines.join("\n");
+}
+function upsertManagedContent(content, desired, migrateLegacyAgentInstructions = false) {
+    const existing = migrateLegacyAgentInstructions
+        ? removeLegacyAgentInstructions(content ?? "")
+        : (content ?? "");
+    const managed = /<!-- groundtrack:start version=\d+ -->[\s\S]*?<!-- groundtrack:end -->/;
+    if (managed.test(existing)) {
+        return `${existing.replace(managed, desired).trimEnd()}\n`;
+    }
+    const base = existing.trimEnd();
+    return `${base}${base ? "\n\n" : ""}${desired}\n`;
+}
+function versionParts(version) {
+    return version
+        .replace(/^v/, "")
+        .split("-")[0]
+        .split(".")
+        .map((part) => Number.parseInt(part, 10) || 0);
+}
+export function compareVersions(left, right) {
+    const a = versionParts(left);
+    const b = versionParts(right);
+    for (let index = 0; index < Math.max(a.length, b.length); index += 1) {
+        const difference = (a[index] ?? 0) - (b[index] ?? 0);
+        if (difference !== 0)
+            return Math.sign(difference);
+    }
+    return 0;
+}
+function installedHookVersion() {
+    try {
+        const result = spawnSync("groundtrack-hook", ["version", "--json"], {
+            encoding: "utf8",
+            timeout: 5_000,
+        });
+        if (result.status !== 0)
+            return null;
+        const parsed = JSON.parse(result.stdout);
+        return typeof parsed.version === "string" ? parsed.version : null;
+    }
+    catch {
+        return null;
+    }
+}
+function installHookPackage(version) {
+    try {
+        execFileSync("npm", ["install", "-g", `@groundtrack/hooks@${version}`], {
+            stdio: "inherit",
+            timeout: 120_000,
+        });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function addFileCheck(checks, changedFiles, options, input) {
+    if (input.current) {
+        checks.push({
+            id: input.id,
+            label: input.label,
+            status: "ok",
+            detail: "current",
+            file: input.path,
+        });
+        return;
+    }
+    if (!options.fix) {
+        checks.push({
+            id: input.id,
+            label: input.label,
+            status: "issue",
+            detail: "missing or outdated",
+            file: input.path,
+        });
+        return;
+    }
+    try {
+        writeAtomic(input.path, input.updated());
+        changedFiles.push(input.path);
+        checks.push({
+            id: input.id,
+            label: input.label,
+            status: "fixed",
+            detail: "updated",
+            file: input.path,
+        });
+    }
+    catch (error) {
+        checks.push({
+            id: input.id,
+            label: input.label,
+            status: "blocked",
+            detail: error instanceof Error ? error.message : "update failed",
+            file: input.path,
+        });
+    }
+}
+export function runDoctor(options) {
+    const version = packageVersion();
+    const clients = options.clients ?? detectClients(options.repoDir);
+    const aliases = groundtrackAliases(options.repoDir);
+    const matcher = matcherForAliases(aliases);
+    const checks = [];
+    const changedFiles = [];
+    if (options.latestVersion && compareVersions(options.latestVersion, version) > 0) {
+        checks.push({
+            id: "cli-version",
+            label: "Groundtrack package",
+            status: "issue",
+            detail: `installed ${version}; latest ${options.latestVersion}`,
+        });
+    }
+    else {
+        checks.push({
+            id: "cli-version",
+            label: "Groundtrack package",
+            status: "ok",
+            detail: options.latestVersion ? `${version} (latest)` : `${version} (offline bundled state)`,
+        });
+    }
+    let runtimeVersion = options.installedHookVersion;
+    if (runtimeVersion === undefined)
+        runtimeVersion = installedHookVersion();
+    if (runtimeVersion === version) {
+        checks.push({ id: "hook-version", label: "Hook runtime", status: "ok", detail: version });
+    }
+    else if (options.fix && !options.skipPackageInstall && installHookPackage(version)) {
+        checks.push({
+            id: "hook-version",
+            label: "Hook runtime",
+            status: "fixed",
+            detail: `installed ${version}`,
+        });
+    }
+    else {
+        checks.push({
+            id: "hook-version",
+            label: "Hook runtime",
+            status: "issue",
+            detail: runtimeVersion
+                ? `installed ${runtimeVersion}; expected ${version}`
+                : `not found; expected ${version}`,
+        });
+    }
+    if (clients.includes("claude")) {
+        for (const [id, label, path, desiredMatcher] of [
+            [
+                "claude-user-hook",
+                "Claude user hook",
+                join(options.homeDir, ".claude/settings.json"),
+                CLAUDE_USER_MATCHER,
+            ],
+            [
+                "claude-repo-hook",
+                "Claude repository hook",
+                join(options.repoDir, ".claude/settings.json"),
+                matcher,
+            ],
+        ]) {
+            try {
+                const config = readJson(path);
+                addFileCheck(checks, changedFiles, options, {
+                    id,
+                    label,
+                    path,
+                    current: claudeHookIsCurrent(config, desiredMatcher),
+                    updated: () => `${JSON.stringify(upsertClaudeHook(config, desiredMatcher), null, 2)}\n`,
+                });
+            }
+            catch (error) {
+                checks.push({
+                    id,
+                    label,
+                    status: "blocked",
+                    detail: error instanceof Error ? error.message : "invalid JSON",
+                    file: path,
+                });
+            }
+        }
+    }
+    if (clients.includes("codex")) {
+        const path = join(options.repoDir, ".codex/config.toml");
+        const content = readText(path) ?? "";
+        addFileCheck(checks, changedFiles, options, {
+            id: "codex-repo-hook",
+            label: "Codex repository hook",
+            path,
+            current: codexHookIsCurrent(content, matcher),
+            updated: () => upsertCodexHook(content, matcher),
+        });
+    }
+    if (clients.includes("cursor")) {
+        const path = join(options.repoDir, ".cursor/hooks.json");
+        try {
+            const config = readJson(path);
+            addFileCheck(checks, changedFiles, options, {
+                id: "cursor-repo-hook",
+                label: "Cursor repository hook",
+                path,
+                current: cursorHookIsCurrent(config),
+                updated: () => `${JSON.stringify(upsertCursorHook(config), null, 2)}\n`,
+            });
+        }
+        catch (error) {
+            checks.push({
+                id: "cursor-repo-hook",
+                label: "Cursor repository hook",
+                status: "blocked",
+                detail: error instanceof Error ? error.message : "invalid JSON",
+                file: path,
+            });
+        }
+    }
+    const instructionFiles = new Map([["AGENTS.md", AGENT_INSTRUCTION_BODY]]);
+    if (clients.includes("claude") || existsSync(join(options.repoDir, "CLAUDE.md"))) {
+        instructionFiles.set("CLAUDE.md", CLAUDE_INSTRUCTION_BODY);
+    }
+    for (const [name, desired] of instructionFiles) {
+        const path = join(options.repoDir, name);
+        const content = readText(path);
+        const isClaudeInstructions = name === "CLAUDE.md";
+        addFileCheck(checks, changedFiles, options, {
+            id: `instructions-${name.toLowerCase()}`,
+            label: `${name} instructions`,
+            path,
+            current: isClaudeInstructions
+                ? claudeInstructionsAreCurrent(content)
+                : managedContentIsCurrent(content, desired),
+            updated: () => {
+                if (isClaudeInstructions && claudeUsesInlineGroundtrackInstructions(content)) {
+                    return upsertManagedContent(content, AGENT_INSTRUCTION_BODY, true);
+                }
+                return upsertManagedContent(content, desired, name === "AGENTS.md");
+            },
+        });
+    }
+    const simulation = hookOutput({
+        tool_name: `mcp__${aliases[0]}__store_event`,
+        cwd: options.repoDir,
+        session_id: "doctor-session",
+        model: "claude-sonnet-4-5",
+        tool_use_id: "doctor-tool",
+        tool_input: { title: "Groundtrack doctor simulation" },
+    }, "claude");
+    const updated = asRecord(asRecord(simulation.hookSpecificOutput)?.updatedInput);
+    const simulationHealthy = updated?.sessionId === "claude:doctor-session" &&
+        updated.modelId === "anthropic/claude-sonnet-4-5" &&
+        updated.clientEventId === "claude:doctor-session:doctor-tool";
+    checks.push({
+        id: "hook-simulation",
+        label: "Hook simulation",
+        status: simulationHealthy ? "ok" : "issue",
+        detail: simulationHealthy
+            ? "session, model, and invocation context enriched"
+            : "enrichment failed",
+    });
+    return {
+        version,
+        clients,
+        aliases,
+        checks,
+        changedFiles,
+        healthy: checks.every((check) => check.status === "ok" || check.status === "fixed"),
+    };
+}

package/dist/enrich-store-event.js

@@ -72,11 +72,20 @@ function transcriptModel(transcriptPath) {
     }
     return null;
 }
-function isGroundtrackStoreEvent(toolName) {
+function groundtrackContextTool(toolName) {
     const normalized = nonEmptyString(toolName)?.toLowerCase();
-    if (!normalized?.includes("store_event"))
-        return false;
-    return normalized.includes("groundtrack") || normalized === "mcp:store_event";
+    if (!normalized)
+        return null;
+    const isGroundtrack = normalized.includes("groundtrack") ||
+        normalized === "mcp:store_event" ||
+        normalized === "mcp:search_experiences";
+    if (!isGroundtrack)
+        return null;
+    if (normalized.includes("store_event"))
+        return "store_event";
+    if (normalized.includes("search_experiences"))
+        return "search_experiences";
+    return null;
 }
 function workspacePath(hookInput) {
     const cwd = nonEmptyString(hookInput.cwd);
@@ -111,7 +120,7 @@ function gitContext(cwd) {
         isDirty: status == null ? null : status.length > 0,
     };
 }
-export function enrichInput(hookInput, clientOverride) {
+export function enrichInput(hookInput, clientOverride, tool = "store_event") {
     const toolInput = hookInput.tool_input &&
         typeof hookInput.tool_input === "object" &&
         !Array.isArray(hookInput.tool_input)
@@ -129,7 +138,7 @@ export function enrichInput(hookInput, clientOverride) {
         toolInput.sessionId = `${host}:${hostSessionId}`;
     if (hostModel)
         toolInput.modelId = hostModel;
-    if (invocationId) {
+    if (tool === "store_event" && invocationId) {
         toolInput.clientEventId = [host, hostSessionId, invocationId].filter(Boolean).join(":");
     }
     if (context)
@@ -137,9 +146,10 @@ export function enrichInput(hookInput, clientOverride) {
     return toolInput;
 }
 export function hookOutput(hookInput, clientOverride) {
-    if (!isGroundtrackStoreEvent(hookInput.tool_name))
+    const tool = groundtrackContextTool(hookInput.tool_name);
+    if (!tool)
         return {};
-    const updatedInput = enrichInput(hookInput, clientOverride);
+    const updatedInput = enrichInput(hookInput, clientOverride, tool);
     if (nonEmptyString(hookInput.conversation_id)) {
         return { permission: "allow", updated_input: updatedInput };
     }

package/dist/groundtrack-hook.js

@@ -1,6 +1,12 @@
 #!/usr/bin/env node
 import { hookOutput } from "./enrich-store-event.js";
+import { packageVersion } from "./version.js";
 async function main() {
+    if (process.argv[2] === "version" || process.argv[2] === "--version") {
+        const version = packageVersion();
+        process.stdout.write(process.argv.includes("--json") ? JSON.stringify({ version }) : version);
+        return;
+    }
     let raw = "";
     for await (const chunk of process.stdin)
         raw += chunk;

package/dist/groundtrack.js

@@ -0,0 +1,175 @@
+#!/usr/bin/env node
+import { createInterface } from "node:readline/promises";
+import { spawnSync } from "node:child_process";
+import { homedir } from "node:os";
+import { resolve } from "node:path";
+import { stdin, stdout } from "node:process";
+import { compareVersions, runDoctor } from "./doctor.js";
+import { packageVersion } from "./version.js";
+function usage() {
+    return `Groundtrack CLI
+
+Usage:
+  groundtrack doctor [--fix] [--yes] [--json] [--repo PATH]
+  groundtrack version [--json]
+
+Commands:
+  doctor       Diagnose Groundtrack hooks and managed agent instructions
+  doctor --fix Repair deterministic configuration drift
+  version      Print the installed CLI/runtime version
+`;
+}
+function parseArguments(argv) {
+    if (argv[0] &&
+        !["doctor", "version", "--version"].includes(argv[0]) &&
+        !argv[0].startsWith("-")) {
+        throw new Error(`Unknown command: ${argv[0]}\n\n${usage()}`);
+    }
+    const command = argv[0] === "version" || argv[0] === "--version" ? "version" : "doctor";
+    let repoDir = process.cwd();
+    let homeDir = homedir();
+    for (let index = 0; index < argv.length; index += 1) {
+        if (argv[index] === "--repo" && argv[index + 1])
+            repoDir = resolve(argv[++index]);
+        if (argv[index] === "--home" && argv[index + 1])
+            homeDir = resolve(argv[++index]);
+    }
+    return {
+        command,
+        fix: argv.includes("--fix"),
+        yes: argv.includes("--yes") || argv.includes("-y"),
+        json: argv.includes("--json"),
+        repoDir,
+        homeDir,
+    };
+}
+function printResult(result) {
+    stdout.write(`Groundtrack doctor ${result.version}\n`);
+    stdout.write(`Clients: ${result.clients.join(", ")}\n`);
+    stdout.write(`MCP aliases: ${result.aliases.join(", ")}\n\n`);
+    for (const check of result.checks) {
+        const icon = check.status === "ok"
+            ? "✓"
+            : check.status === "fixed"
+                ? "◆"
+                : check.status === "blocked"
+                    ? "×"
+                    : "!";
+        stdout.write(`${icon} ${check.label}: ${check.detail}${check.file ? ` (${check.file})` : ""}\n`);
+    }
+    if (result.changedFiles.length > 0) {
+        stdout.write(`\nUpdated ${result.changedFiles.length} file(s).\n`);
+    }
+    stdout.write(result.healthy
+        ? "\nGroundtrack integration is healthy.\n"
+        : "\nGroundtrack integration needs attention.\n");
+}
+async function confirmFix() {
+    const prompt = createInterface({ input: stdin, output: stdout });
+    try {
+        const answer = await prompt.question("Apply deterministic Groundtrack repairs? [y/N] ");
+        return /^y(?:es)?$/i.test(answer.trim());
+    }
+    finally {
+        prompt.close();
+    }
+}
+async function latestPackageVersion() {
+    const override = process.env.GROUNDTRACK_DOCTOR_LATEST_VERSION;
+    if (override)
+        return override;
+    if (process.env.GROUNDTRACK_DOCTOR_OFFLINE === "1")
+        return null;
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), 2_000);
+    try {
+        const response = await fetch("https://registry.npmjs.org/@groundtrack%2Fhooks/latest", {
+            signal: controller.signal,
+            headers: { accept: "application/json" },
+        });
+        if (!response.ok)
+            return null;
+        const payload = (await response.json());
+        return typeof payload.version === "string" ? payload.version : null;
+    }
+    catch {
+        return null;
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+function updatePackageAndRerun(version) {
+    const install = spawnSync("npm", ["install", "-g", `@groundtrack/hooks@${version}`], {
+        stdio: "inherit",
+        timeout: 120_000,
+    });
+    if (install.status !== 0)
+        return install.status ?? 1;
+    const rerun = spawnSync("groundtrack", process.argv.slice(2), {
+        stdio: "inherit",
+        env: {
+            ...process.env,
+            GROUNDTRACK_DOCTOR_REEXEC: "1",
+            GROUNDTRACK_DOCTOR_LATEST_VERSION: version,
+        },
+    });
+    return rerun.status ?? 1;
+}
+async function main() {
+    const args = parseArguments(process.argv.slice(2));
+    if (process.argv.includes("--help") || process.argv.includes("-h")) {
+        stdout.write(usage());
+        return;
+    }
+    if (args.command === "version") {
+        const version = packageVersion();
+        stdout.write(args.json ? `${JSON.stringify({ version })}\n` : `${version}\n`);
+        return;
+    }
+    const base = {
+        repoDir: args.repoDir,
+        homeDir: args.homeDir,
+        skipPackageInstall: process.env.GROUNDTRACK_DOCTOR_SKIP_INSTALL === "1",
+        latestVersion: await latestPackageVersion(),
+    };
+    const diagnosis = runDoctor(base);
+    if (!args.fix) {
+        if (args.json)
+            stdout.write(`${JSON.stringify(diagnosis, null, 2)}\n`);
+        else
+            printResult(diagnosis);
+        process.exitCode = diagnosis.healthy ? 0 : 1;
+        return;
+    }
+    if (diagnosis.healthy) {
+        if (args.json)
+            stdout.write(`${JSON.stringify(diagnosis, null, 2)}\n`);
+        else
+            printResult(diagnosis);
+        return;
+    }
+    if (!args.json)
+        printResult(diagnosis);
+    if (!args.yes && !(await confirmFix())) {
+        stdout.write("No changes made.\n");
+        process.exitCode = 1;
+        return;
+    }
+    if (base.latestVersion &&
+        compareVersions(base.latestVersion, diagnosis.version) > 0 &&
+        process.env.GROUNDTRACK_DOCTOR_REEXEC !== "1") {
+        process.exitCode = updatePackageAndRerun(base.latestVersion);
+        return;
+    }
+    const repaired = runDoctor({ ...base, fix: true });
+    if (args.json)
+        stdout.write(`${JSON.stringify(repaired, null, 2)}\n`);
+    else
+        printResult(repaired);
+    process.exitCode = repaired.healthy ? 0 : 1;
+}
+main().catch((error) => {
+    process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+    process.exitCode = 1;
+});

package/dist/version.js

@@ -0,0 +1,12 @@
+import { readFileSync } from "node:fs";
+let cachedVersion = null;
+export function packageVersion() {
+    if (cachedVersion)
+        return cachedVersion;
+    const packageJson = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+    if (typeof packageJson.version !== "string" || !packageJson.version.trim()) {
+        throw new Error("@groundtrack/hooks package version is unavailable.");
+    }
+    cachedVersion = packageJson.version.trim();
+    return cachedVersion;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@groundtrack/hooks",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Lifecycle hook utilities for Groundtrack MCP clients.",
   "keywords": [
     "claude-code",
@@ -12,10 +12,12 @@
   ],
   "license": "MIT",
   "bin": {
+    "groundtrack": "./dist/groundtrack.js",
     "groundtrack-hook": "./dist/groundtrack-hook.js"
   },
   "files": [
     "dist/",
+    "templates/",
     "README.md",
     "LICENSE"
   ],
@@ -28,12 +30,14 @@
     "lint": "oxlint .",
     "prepack": "pnpm run build",
     "release:patch": "node scripts/release-patch.mjs",
-    "test": "pnpm run build && node --test test/*.test.mjs",
-    "typecheck": "tsc -p tsconfig.json --noEmit"
+    "sync:agent-instructions": "node scripts/sync-agent-instructions.mjs",
+    "test": "pnpm run build && node --import tsx --test test/*.test.ts",
+    "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.test.json"
   },
   "devDependencies": {
     "@groundtrack/typescript": "workspace:*",
     "@types/node": "^25.9.1",
+    "tsx": "^4.20.5",
     "typescript": "~7.0.2"
   },
   "engines": {

package/templates/AGENTS.md

@@ -0,0 +1,16 @@
+<!-- groundtrack:start version=1 -->
+
+## Groundtrack
+
+Use Groundtrack as the shared engineering memory for this repository.
+
+- Before non-trivial investigation or implementation where prior decisions, failures, or constraints could matter, call `search_experiences`. Start with a focused description of the work, then inspect the results and search one or two materially different adjacent concepts when related components, constraints, failure modes, or prior decisions could change the approach. Do not stop merely because the first search has no exact match; try a meaningfully broader or neighboring query. Keep this expansion bounded, and also search before repeating an approach that may already have been tried.
+- When a relevant experience needs more context or verification, call `get_experience_events` with its id to inspect the underlying raw evidence and provenance.
+- Apply relevant current experiences and heed any caveats that an experience was contradicted, superseded, or expired.
+- Once the effect of a search is known, call `report_experience_use` with its retrieval id. Report when a result changed the approach or avoided a failure, and report `not_helpful` when none applied.
+- After a non-obvious discovery, decision, workaround, correction, or failed approach that would help a future agent, call `store_event` promptly with a concise title and an explanation of what happened and why it matters.
+- Do not store routine implementation details, obvious facts, unrestricted transcripts, or secrets.
+- Keep the raw-event ids returned by `store_event`. When the related work lands in a commit or pull request, call `link_outcomes` with those ids and the explicit commit SHA and/or pull-request number. Never infer an outcome from worktree HEAD.
+- When recurring engineering friction may support or oppose an existing initiative, call `search_initiatives` before storing the event and link it to the matching initiative with the appropriate direction. Propose a new initiative only when explicitly recommending organizational change and no existing initiative matches.
+
+<!-- groundtrack:end -->