@groundtrack/hooks 0.1.2 → 0.1.4

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,18 @@ 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
+returns a `hook_context_missing` warning when hook-injected session context is
+absent. In Codex, use `/hooks` to review and trust the Groundtrack hook when that
+warning appears.
+
 `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

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) {
@@ -510,18 +517,26 @@ export function runDoctor(options) {
         updated.clientEventId === "claude:doctor-session:doctor-tool";
     checks.push({
         id: "hook-simulation",
-        label: "Hook simulation",
+        label: "Local hook simulation",
         status: simulationHealthy ? "ok" : "issue",
         detail: simulationHealthy
-            ? "session, model, and invocation context enriched"
+            ? "session, model, and invocation context enriched locally"
             : "enrichment failed",
     });
+    checks.push({
+        id: "live-hook-activation",
+        label: "Live hook activation",
+        status: "advisory",
+        detail: clients.includes("codex")
+            ? "not verifiable outside Codex; open /hooks and review and trust the Groundtrack hook"
+            : "not verifiable outside the coding-agent host; Groundtrack MCP calls report missing hook context",
+    });
     return {
         version,
         clients,
         aliases,
         checks,
         changedFiles,
-        healthy: checks.every((check) => check.status === "ok" || check.status === "fixed"),
+        healthy: checks.every((check) => check.status === "ok" || check.status === "fixed" || check.status === "advisory"),
     };
 }

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,41 +31,58 @@ 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) {
+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`);
     for (const check of result.checks) {
         const icon = check.status === "ok"
             ? "✓"
-            : check.status === "fixed"
-                ? "◆"
-                : check.status === "blocked"
-                    ? "×"
-                    : "!";
+            : check.status === "advisory"
+                ? "i"
+                : 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");
+        ? "\nGroundtrack local configuration is healthy. Live hook activation is verified by Groundtrack MCP calls.\n"
+        : `\nGroundtrack local configuration needs attention.${fixHint}\n`);
 }
 async function confirmFix() {
     const prompt = createInterface({ input: stdin, output: stdout });
@@ -130,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(),
     };
@@ -138,10 +159,13 @@ async function main() {
         if (args.json)
             stdout.write(`${JSON.stringify(diagnosis, null, 2)}\n`);
         else
-            printResult(diagnosis);
+            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.2",
+  "version": "0.1.4",
   "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=2 -->
 
 ## Groundtrack
 
@@ -8,6 +8,7 @@ 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.