@groundtrack/hooks 0.1.3 → 0.1.5

package/README.md

@@ -16,7 +16,7 @@ repository root:
 
 ```bash
 groundtrack doctor
-groundtrack doctor --fix
+groundtrack doctor --fix --client codex
 ```
 
 `doctor` checks the installed package/runtime version, discovers the actual
@@ -24,6 +24,11 @@ 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.
 
+Pass `--client claude`, `--client codex`, or `--client cursor` when repairing a
+repository. This limits MCP alias discovery and configuration changes to that
+client. If more than one client is detected, `doctor --fix` refuses to guess
+which one to modify.
+
 The Doctor verifies local configuration and enrichment behavior, but it cannot
 observe whether a coding-agent host loaded or trusted a project hook. A
 `search_experiences` MCP response is the authoritative live check: Groundtrack

package/dist/agent-instructions.js

@@ -1,10 +1,47 @@
 import { readFileSync } from "node:fs";
-const VERSION_PATTERN = /^<!-- groundtrack:start version=(\d+) -->/;
+import { join } from "node:path";
+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.");
 }
+const AGENT_INSTRUCTION_START_MARKER = versionMatch[0];
 /** Version is derived from the canonical template marker; never define it separately. */
 export const AGENT_INSTRUCTION_TEMPLATE_VERSION = Number(versionMatch[1]);
+function readInstructions(path) {
+    try {
+        return readFileSync(path, "utf8");
+    }
+    catch {
+        return null;
+    }
+}
+function instructionVersion(content) {
+    const match = content ? VERSION_PATTERN.exec(content) : null;
+    return match ? Number(match[1]) : null;
+}
+/** Detect the managed policy version available to a client in one repository. */
+export function detectAgentInstructionsVersion(repoDir, client) {
+    const agents = readInstructions(join(repoDir, "AGENTS.md"));
+    const agentsVersion = instructionVersion(agents);
+    if (client !== "claude")
+        return agentsVersion;
+    const claude = readInstructions(join(repoDir, "CLAUDE.md"));
+    if (!claude)
+        return null;
+    if (/^@AGENTS\.md\s*$/m.test(claude)) {
+        const bridgeVersion = instructionVersion(claude);
+        if (agentsVersion == null)
+            return null;
+        return bridgeVersion == null ? agentsVersion : Math.min(bridgeVersion, agentsVersion);
+    }
+    const inlineVersion = instructionVersion(claude);
+    if (inlineVersion != null)
+        return inlineVersion;
+    const unmarkedCurrentInstructions = AGENT_INSTRUCTION_BODY.replace(AGENT_INSTRUCTION_START_MARKER, "")
+        .replace("<!-- groundtrack:end -->", "")
+        .trim();
+    return claude.includes(unmarkedCurrentInstructions) ? AGENT_INSTRUCTION_TEMPLATE_VERSION : null;
+}

package/dist/doctor.js

@@ -53,9 +53,13 @@ function matcherForAliases(aliases) {
     const server = escaped.length === 1 ? escaped[0] : `(?:${escaped.join("|")})`;
     return `^mcp__${server}__(store_event|search_experiences)$`;
 }
-function groundtrackAliases(repoDir) {
+function groundtrackAliases(repoDir, clients) {
     const aliases = new Set();
-    for (const relative of [".mcp.json", ".cursor/mcp.json"]) {
+    const jsonConfigs = [
+        ...(clients.includes("claude") ? [".mcp.json"] : []),
+        ...(clients.includes("cursor") ? [".cursor/mcp.json"] : []),
+    ];
+    for (const relative of jsonConfigs) {
         const path = join(repoDir, relative);
         try {
             const config = readJson(path);
@@ -73,11 +77,13 @@ function groundtrackAliases(repoDir) {
             // 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 (clients.includes("codex")) {
+        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)
@@ -360,7 +366,7 @@ function addFileCheck(checks, changedFiles, options, input) {
 export function runDoctor(options) {
     const version = packageVersion();
     const clients = options.clients ?? detectClients(options.repoDir);
-    const aliases = groundtrackAliases(options.repoDir);
+    const aliases = groundtrackAliases(options.repoDir, clients);
     const matcher = matcherForAliases(aliases);
     const checks = [];
     const changedFiles = [];
@@ -474,7 +480,8 @@ export function runDoctor(options) {
         }
     }
     const instructionFiles = new Map([["AGENTS.md", AGENT_INSTRUCTION_BODY]]);
-    if (clients.includes("claude") || existsSync(join(options.repoDir, "CLAUDE.md"))) {
+    if (clients.includes("claude") ||
+        (options.clients === undefined && existsSync(join(options.repoDir, "CLAUDE.md")))) {
         instructionFiles.set("CLAUDE.md", CLAUDE_INSTRUCTION_BODY);
     }
     for (const [name, desired] of instructionFiles) {

package/dist/enrich-store-event.js

@@ -1,5 +1,6 @@
 import { execFileSync } from "node:child_process";
 import { closeSync, fstatSync, openSync, readSync } from "node:fs";
+import { detectAgentInstructionsVersion, } from "./agent-instructions.js";
 const PROVIDERS = [
     [/^claude(?:[-_.]|$)/, "anthropic"],
     [/^(?:gpt|o\d|codex)(?:[-_.]|$)/, "openai"],
@@ -120,6 +121,11 @@ function gitContext(cwd) {
         isDirty: status == null ? null : status.length > 0,
     };
 }
+function repositoryRoot(cwd) {
+    if (!cwd)
+        return null;
+    return git(cwd, ["rev-parse", "--show-toplevel"]) ?? cwd;
+}
 export function enrichInput(hookInput, clientOverride, tool = "store_event") {
     const toolInput = hookInput.tool_input &&
         typeof hookInput.tool_input === "object" &&
@@ -133,7 +139,8 @@ export function enrichInput(hookInput, clientOverride, tool = "store_event") {
         ? (hookInput.model_id ?? hookInput.model)
         : (hookInput.model ?? hookInput.model_id ?? transcriptModel(hookInput.transcript_path)));
     const invocationId = nonEmptyString(isCursor ? hookInput.generation_id : hookInput.tool_use_id);
-    const context = gitContext(workspacePath(hookInput));
+    const cwd = workspacePath(hookInput);
+    const context = gitContext(cwd);
     if (hostSessionId)
         toolInput.sessionId = `${host}:${hostSessionId}`;
     if (hostModel)
@@ -141,6 +148,11 @@ export function enrichInput(hookInput, clientOverride, tool = "store_event") {
     if (tool === "store_event" && invocationId) {
         toolInput.clientEventId = [host, hostSessionId, invocationId].filter(Boolean).join(":");
     }
+    if (tool === "search_experiences") {
+        const client = host === "claude" || host === "cursor" ? host : "codex";
+        const root = repositoryRoot(cwd);
+        toolInput.agentInstructionsVersion = root ? detectAgentInstructionsVersion(root, client) : null;
+    }
     if (context)
         Object.assign(toolInput, context);
     return toolInput;

package/dist/groundtrack.js

@@ -10,13 +10,16 @@ function usage() {
     return `Groundtrack CLI
 
 Usage:
-  groundtrack doctor [--fix] [--yes] [--json] [--repo PATH]
+  groundtrack doctor [--fix] [--yes] [--json] [--client CLIENT] [--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
+
+Options:
+  --client     Limit diagnosis and repair to claude, codex, or cursor
 `;
 }
 function parseArguments(argv) {
@@ -28,22 +31,37 @@ function parseArguments(argv) {
     const command = argv[0] === "version" || argv[0] === "--version" ? "version" : "doctor";
     let repoDir = process.cwd();
     let homeDir = homedir();
+    let client;
     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]);
+        if (argv[index] === "--client") {
+            const value = argv[++index];
+            if (value !== "claude" && value !== "codex" && value !== "cursor") {
+                throw new Error("--client must be one of: claude, codex, cursor");
+            }
+            client = value;
+        }
     }
     return {
         command,
         fix: argv.includes("--fix"),
         yes: argv.includes("--yes") || argv.includes("-y"),
         json: argv.includes("--json"),
+        client,
         repoDir,
         homeDir,
     };
 }
 function printResult(result, options = {}) {
+    const selectedClient = options.client ?? (result.clients.length === 1 ? result.clients[0] : null);
+    const fixHint = !options.showFixHint
+        ? ""
+        : selectedClient
+            ? ` Run: groundtrack doctor --fix --client ${selectedClient}`
+            : " Re-run with --client claude, --client codex, or --client cursor.";
     stdout.write(`Groundtrack doctor ${result.version}\n`);
     stdout.write(`Clients: ${result.clients.join(", ")}\n`);
     stdout.write(`MCP aliases: ${result.aliases.join(", ")}\n\n`);
@@ -64,7 +82,7 @@ function printResult(result, options = {}) {
     }
     stdout.write(result.healthy
         ? "\nGroundtrack local configuration is healthy. Live hook activation is verified by Groundtrack MCP calls.\n"
-        : `\nGroundtrack local configuration needs attention.${options.showFixHint ? " Run: groundtrack doctor --fix" : ""}\n`);
+        : `\nGroundtrack local configuration needs attention.${fixHint}\n`);
 }
 async function confirmFix() {
     const prompt = createInterface({ input: stdin, output: stdout });
@@ -132,6 +150,7 @@ async function main() {
     const base = {
         repoDir: args.repoDir,
         homeDir: args.homeDir,
+        clients: args.client ? [args.client] : undefined,
         skipPackageInstall: process.env.GROUNDTRACK_DOCTOR_SKIP_INSTALL === "1",
         latestVersion: await latestPackageVersion(),
     };
@@ -140,10 +159,13 @@ async function main() {
         if (args.json)
             stdout.write(`${JSON.stringify(diagnosis, null, 2)}\n`);
         else
-            printResult(diagnosis, { showFixHint: true });
+            printResult(diagnosis, { showFixHint: true, client: args.client });
         process.exitCode = diagnosis.healthy ? 0 : 1;
         return;
     }
+    if (!args.client && diagnosis.clients.length > 1) {
+        throw new Error(`Multiple coding-agent clients detected: ${diagnosis.clients.join(", ")}. Re-run with --client claude, --client codex, or --client cursor so Doctor does not modify unrelated client configuration.`);
+    }
     if (diagnosis.healthy) {
         if (args.json)
             stdout.write(`${JSON.stringify(diagnosis, null, 2)}\n`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@groundtrack/hooks",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "Lifecycle hook utilities for Groundtrack MCP clients.",
   "keywords": [
     "claude-code",

package/templates/AGENTS.md

@@ -1,4 +1,4 @@
-<!-- groundtrack:start version=1 -->
+<!-- groundtrack:start version=3 -->
 
 ## Groundtrack
 
@@ -8,9 +8,9 @@ Use Groundtrack as the shared engineering memory for this repository.
 - 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 task reaches a concrete result, call `record_outcome` with a short title, a concise summary, and the retrieval ids for searches that contributed. Include measurements only for sourced, quantified impact on time, cost, reliability, quality, performance, or throughput; tests, typechecks, lint, and builds are validation rather than impact. Include avoided work only when it was explicitly estimated, and never infer unknown values.
 - 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 -->