@groundtrack/hooks 0.1.22 → 0.1.23

package/README.md

@@ -103,6 +103,35 @@ The lower-level `runDoctor` API remains for existing consumers. New setup uses
 client-specific plans for MCP, hooks/plugins, and instructions, so it can preview
 and repair several selected agents safely.
 
+## Local impact skill (opt-in)
+
+The package includes a read-only `groundtrack-impact` skill for Claude Code and
+Codex. It audits local sessions to produce an evidence-backed report on how
+Groundtrack changed your work. **Setup does not install or invoke this skill**;
+install it explicitly only when you want to give an agent access to local
+transcripts. From this repository checkout, choose either or both agents:
+
+```sh
+mkdir -p "${CODEX_HOME:-$HOME/.codex}/skills"
+cp -R packages/hooks/skills/groundtrack-impact "${CODEX_HOME:-$HOME/.codex}/skills/"
+mkdir -p "${CLAUDE_CONFIG_DIR:-$HOME/.claude}/skills"
+cp -R packages/hooks/skills/groundtrack-impact "${CLAUDE_CONFIG_DIR:-$HOME/.claude}/skills/"
+```
+
+If `@groundtrack/hooks` is installed in another project, use
+`node_modules/@groundtrack/hooks/skills/groundtrack-impact` as the copy source
+instead. For Claude Code, set this copied skill to **user-only** in `/skills`
+(or set `"groundtrack-impact": "user-invocable-only"` under `skillOverrides` in
+Claude settings) before using it; that prevents Claude from loading this
+transcript-reading workflow on its own. Codex's packaged `agents/openai.yaml` already
+disables implicit invocation. Restart your agent if needed, then explicitly invoke
+`$groundtrack-impact` in Codex or `/groundtrack-impact` in Claude Code and
+authorize the session scope. The audit reads Claude
+sessions from `CLAUDE_CONFIG_DIR` (default `~/.claude`) and Codex sessions from
+`CODEX_HOME` (default `~/.codex`); it never uploads transcripts or runs the
+session-import command. The agent's model provider may receive selected local
+context during analysis.
+
 ## Import coding-agent sessions
 
 Import completed Codex, Claude Code, Cursor, or OpenCode sessions with an API key created in Groundtrack

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@groundtrack/hooks",
-  "version": "0.1.22",
+  "version": "0.1.23",
   "description": "Lifecycle hook utilities for Groundtrack MCP clients.",
   "keywords": [
     "claude-code",
@@ -19,6 +19,7 @@
   "files": [
     "dist/",
     "templates/",
+    "skills/",
     "src/agents.ts",
     "README.md",
     "LICENSE"

package/skills/groundtrack-impact/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: groundtrack-impact
+description: Audit local Claude Code and Codex histories for evidence-backed knowledge-use stories and initiative-driven environment changes. Use only when the user explicitly invokes this skill and authorizes local session access.
+---
+
+# Groundtrack impact
+
+Answer “How has Groundtrack concretely helped me?” with an at-a-glance value summary followed by specific stories. This is a user-invoked, read-only local audit, not the server-side Impact Analyst or a causal ROI study. Make the strongest supportable positive case, including all defensible instances rather than stopping after finding a few examples.
+
+## Scope and privacy
+
+- Confirm explicit authorization to read local coding sessions. Use requested agents, repositories, and dates; otherwise cover **all locally available** Claude Code and Codex sessions on this machine, including archived sessions and subagents. State the actual scope and unavailable history. For a large corpus, spend the time to audit it; do not silently substitute a recent sample. If authorization is absent, ask before opening transcripts.
+- Read session files in place. Do not import or upload transcripts, use write-capable Groundtrack tools (including feedback or outcome recording), mutate repositories, or save transcript copies. Never run Groundtrack's session-import command. A hosted agent may send selected content to its model provider during analysis; do not claim device-only processing.
+- Keep private prompts, credentials, raw local paths, and unrelated transcript content out of the customer-facing report. Paraphrase sensitive details. Supporting record/PR links are useful where available, but exact citations are a recommendation, not a gate.
+
+## Census and audit
+
+1. Freeze an ISO UTC cutoff at the start of the audit and pass the same `--until TIMESTAMP` to all scanner/evidence runs; exclude the audit's own later activity from the report. Run `node scripts/scan.mjs --until TIMESTAMP` from this skill directory (or pass `--since YYYY-MM-DD` to both scripts for an explicitly requested UTC event-time window; `--codex-home` and `--claude-home` can point at alternate local homes). The scanner only reads local JSONL and emits an inventory of structured Groundtrack-call candidates, file locations, line numbers, and coverage. It does not identify impact. Record found, readable, unparseable, and missing histories, plus candidate and noncandidate sessions by agent. Its wrapper-call matches are **leads**: inspect the actual call and result to reject quoted code, unsuccessful calls, duplicates, or setup-only activity. If the scanner cannot run, perform an equivalent full inventory using the supported session locations and disclose what was not covered.
+2. Run `node scripts/evidence.mjs --until TIMESTAMP` for a compact per-session index of feedback and outcomes; `--reports` lists feedback leads, `--session ID` shows a session's evidence rows, and `--chains` joins the latest successful helpful verdict per retrieval to successful outcomes by retrieval ID and to asserted PR/commit links by raw-event ID. The index exposes both raw `helpedReports` and `currentHelpfulRetrievals` after corrections; use the latter for a current positive-feedback session count. The parser never executes transcript code and never determines impact. **Do not report its raw counts as ROI.** Check the actual call result, the retrieval it refers to, and neighboring work before accepting a feedback claim. Verify PR merge/deployment status, whether a link was accepted or pending, and later reversals with read-only checks. A PR mentioned nearby in a long chat is not a join. Distinguish historically merged work from still-surviving work, especially after a feature was reverted or removed.
+3. Triage **every Groundtrack-active session in scope**, not merely the most recent or most promising: review its actual structured calls/results, feedback verdicts, outcomes, and Review leads, including setup-only sessions and later corrections. Then inspect neighboring transcript context around **every plausible distinct positive work-item lead**, from initial retrieval or finding through action and outcome; do not treat index rows alone as impact. `node scripts/context.mjs FILE LINE [RADIUS]` displays a bounded excerpt at an evidence-row location; it may contain sensitive text and is for local analysis only. Include retrievals, feedback, outcomes, initiatives, and Review activity even if the latter has no `search_experiences` call. Flag impact-audit/evaluation sessions already in the historical corpus: include them in coverage but exclude their self-referential feedback and outcomes from the customer-value numerator. Join repeated calls on the same issue; a single long session or repeated feedback must not inflate a count. Build a private evidence ledger with a stable issue/work-item key, source session(s), actual Groundtrack evidence, the earlier plan or code, subsequent action, validation, outcome, and claim level. Do not put raw transcript text in this ledger or the report. Report both `sessions triaged / Groundtrack-active sessions` and `positive work items deeply checked`; if plausible leads remain unchecked, label the benefit count a verified lower bound, not an exhaustive total.
+4. Consult available **read-only** Groundtrack evidence for candidate retrievals, experiences and raw events, feedback, outcomes, initiatives, and Review findings. Check corrections, contradictions, supersessions, and whether a warning originated earlier in the same session. Local session context is primary evidence of changed behavior; backend feedback alone is not. Groundtrack's backend index may be incomplete, so never use it as the denominator for all coding sessions. If a detail source is unavailable, count only what local evidence supports and note the gap briefly.
+5. Classify each distinct issue/work item once at its highest supported level:
+   - **Verified defect detected or fixed**: Groundtrack's specific retrieval, prior experience, or Review finding directed an investigation that revealed a real defect, or identified it directly. The session shows the subsequent fix and independent confirmation (test, merged fix, deployment check, or actual failure matching the prediction). Distinguish pre-merge catches from production incidents diagnosed after deployment; never imply that an incident was prevented if it happened.
+   - **Mistake caught before completion**: a concrete risky plan or implementation is visible _before_ Groundtrack surfaced the relevant warning/finding; the subsequent session shows a targeted correction; and code, tests, review, or another independent artifact corroborates the change. Count observed interceptions, not hypothetical production incidents or failures that “would have shipped.” A generic warning or a preexisting fix does not qualify. A verified defect that was caught here belongs to the previous bucket, not both.
+   - **Other observed course correction**: a specific Groundtrack retrieval or Review finding preceded and informed a visible decision or change, but the earlier approach was not demonstrably a mistake or independent verification is missing.
+   - **Agent-reported help only**: explicit helpful-use feedback without a traceable changed action. Report separately, never as a prevented mistake.
+   - **Retrieved / reviewed only**: no demonstrated help; keep in the denominator, not a positive numerator. Do not turn “work completed after retrieval” into causal credit.
+     One issue belongs to only one bucket. Separate **verified completion** (merged fix, deployed work, passing validation, or an outcome tied to the issue) from the help bucket; completion is a parallel attribute, not another additive impact count. Count Review-only work with the same rules. Check that superficially similar cases are distinct before aggregating. An `avoided_failure` feedback effect is a lead, never sufficient evidence of prevention: check whether the agent had already found or fixed the same issue before retrieval.
+6. For before/after, look at comparable local pre-Groundtrack tasks if the history actually contains them. Report the comparable population and a descriptive contrast; changes in task mix, agent, or observability invalidate a causal efficiency claim. Time, money, tokens, and avoided incidents require separately sourced measurements or explicit estimates. Never invent a subscription ROI multiple.
+
+## Initiative impact (separate, optional)
+
+After the knowledge-loop audit, search read-only Groundtrack initiatives using the recurring friction and system changes found in the local sessions. Inspect current initiative detail (`search_initiatives` then `get_initiative` when available), including supporting and opposing events, relationships, dates, and linked outcomes; follow the local coding sessions and actual PR/deployment evidence. Verify that the initiative preceded or shaped the claimed intervention; a record created after a completed fix is retrospective context, not proof Groundtrack drove it. Search results, initiative state, an agent's attribution, or a `resolved` label alone do not establish implementation or impact. Check whether an apparent fix is a partial slice, was later replaced, or had a subsequent recurrence. The backend index may omit detail; use it as a lead, not a complete initiative census.
+
+Classify only credible, distinct initiative stories:
+
+- **Realized environment improvement:** recurring friction is documented; Groundtrack surfaced or organized a specific initiative; the intended system change landed; and comparable, time-ordered evidence after deployment shows that the same failure mode declined or stopped over a stated observation window. Describe the exposure and observation limits. Silence, a green test, or an absence of later search hits is not a measured decline, and the initiative must not receive sole causal credit when other interventions contributed.
+- **Implemented but unverified:** a clearly linked intervention landed and its immediate behavior may be validated, but later recurrence has not been measured sufficiently. State the implemented scope and what would verify durable improvement. A proposed initiative can fall here when independent code/PR evidence proves implementation; its state alone cannot.
+- **Identified opportunity:** a draft or proposal identifies a recurring, supported problem and a prospective intervention, but that intervention has not landed. Partial progress that leaves the stated failure mode open must be described as partial, not realized. Never count a draft or proposal as an achieved improvement.
+
+Keep initiative trajectory separate from retrieval/Review work-item attribution. If the same PR, defect, or change appears in both tracks, tell one story with an initiative label or cross-reference it; count the work item once in the headline, and never add initiative totals to defect or safeguard totals. Include a compact initiative section only when at least one story survives this audit; omit it entirely when none does, rather than padding the report with initiative counts. An identified opportunity is a next step, not realized value.
+
+## Report
+
+Start with a short, positive **at-a-glance** line or compact scorecard containing the strongest supportable numbers. When available, put broad **reach** (historically merged/deployed changes with a traceable Groundtrack chain, sessions with current positive agent feedback) beside **demonstrated changed work** (distinct completed work items, verified fixes split pre-merge/post-deploy, concrete mistakes caught before completion, and other course corrections). The largest defensible reach number can lead, but label it as reach in the same glance that identifies the smaller, stronger changed-work count; never imply the counts are additive or equally causal. Do not open with file/session inventory, triage methodology, or a wall of caveats. Use real numbers, including zero when fully audited; use “at least” and a partial denominator if coverage is incomplete.
+
+For reach, count only historically merged/deployed changes with an explicit retrieval → latest successful helpful feedback verdict → outcome → raw-event → PR/commit chain, after checking tool-call success and the claimed PR/revision. This **usage footprint** is not a count of prevented failures, current functionality, or ROI. Keep agent-reported-only help distinct from demonstrated changes, exclude self-audits from value numerators, deduplicate issues across sessions, and disclose historical work later removed.
+
+Then tell a few memorable, strongest stories up front and group other checked examples by recurring failure mode, with enough compact detail to substantiate the headline. Each should explain the task, the Groundtrack evidence, the agent's visible change, and what followed; identify whether the issue was caught before merge, repaired after deployment, or was a design/release safeguard. Favor cross-session reuse and non-Groundtrack work among equally strong cases. Offer useful evidence links when available. Put the nuanced distinction (reported / observed / verified) in compact labels and make the value clear without repetitive hedging. If a claim does not survive audit, omit it from positive stories rather than padding the report with weak anecdotes. If an initiative story qualifies, label its category and put it after or alongside the relevant work-item story without increasing the headline work-item count; state the implementation and recurrence evidence separately.
+
+When the same failure mode recurs in **distinct work items**, add a concise pattern line such as “Cross-user access mistakes caught in 3 separate changes,” with the three issue keys and corroborating records available on request. A repeated warning or feedback in one work item counts once, and a taxonomy match alone is not proof that each intervention changed the work.
+
+End with a brief scope note: `N/M Groundtrack-active sessions triaged; K distinct work items deeply checked; A/B total local sessions screened` (by agent if useful), local histories missing or unaudited, unavailable backend detail, and any comparable baseline. Name the most actionable instrumentation gap. If no positive case survives, do not fabricate one: report the completed census, what evidence is missing, and a concrete path to a stronger future measurement.

package/skills/groundtrack-impact/agents/openai.yaml

@@ -0,0 +1,2 @@
+policy:
+  allow_implicit_invocation: false

package/skills/groundtrack-impact/scripts/context.mjs

@@ -0,0 +1,93 @@
+#!/usr/bin/env node
+// Display a bounded local JSONL excerpt for human audit; never writes or uploads.
+import { createReadStream } from "node:fs";
+import { resolve } from "node:path";
+import { createInterface } from "node:readline";
+import { fileURLToPath } from "node:url";
+
+function summarize(record, limit) {
+  if (record?.type === "response_item") {
+    const p = record.payload;
+    if (p?.type === "message" && ["user", "assistant"].includes(p.role)) {
+      return {
+        kind: p.role,
+        text: p.content
+          ?.filter((x) => x.type === "input_text" || x.type === "output_text")
+          .map((x) => x.text)
+          .join("\n")
+          .slice(0, limit),
+      };
+    }
+    if (["custom_tool_call", "function_call"].includes(p?.type))
+      return {
+        kind: "tool_call",
+        name: p.name,
+        text: String(p.input ?? p.arguments ?? "").slice(0, limit),
+      };
+    if (["custom_tool_call_output", "function_call_output"].includes(p?.type))
+      return {
+        kind: "tool_result",
+        text: (typeof p.output === "string" ? p.output : JSON.stringify(p.output ?? "")).slice(
+          0,
+          limit,
+        ),
+      };
+  }
+  if (["user", "assistant"].includes(record?.type)) {
+    const blocks = Array.isArray(record.message?.content) ? record.message.content : [];
+    const content = blocks
+      .filter((x) => ["text", "tool_use", "tool_result"].includes(x?.type))
+      .map((x) =>
+        x.type === "text"
+          ? x.text
+          : x.type === "tool_use"
+            ? `${x.name} ${JSON.stringify(x.input)}`
+            : `result ${JSON.stringify(x.content)}`,
+      );
+    return { kind: record.type, text: content.join("\n").slice(0, limit) };
+  }
+  return null;
+}
+
+export async function context(path, center, radius = 15, limit = 650) {
+  const rows = [];
+  const input = createInterface({ input: createReadStream(path), crlfDelay: Infinity });
+  let line = 0;
+  for await (const text of input) {
+    line++;
+    if (line < center - radius || line > center + radius) continue;
+    let record;
+    try {
+      record = JSON.parse(text);
+    } catch {
+      continue;
+    }
+    const detail = summarize(record, limit);
+    if (detail) rows.push({ line, ...detail });
+  }
+  return rows;
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  const [path, rawLine, rawRadius] = process.argv.slice(2);
+  const line = Number(rawLine);
+  const radius = rawRadius === undefined ? 15 : Number(rawRadius);
+  if (
+    !path ||
+    !Number.isSafeInteger(line) ||
+    line < 1 ||
+    !Number.isSafeInteger(radius) ||
+    radius < 0 ||
+    radius > 100
+  ) {
+    process.stderr.write("Usage: node scripts/context.mjs FILE LINE [RADIUS<=100]\n");
+    process.exitCode = 1;
+  } else {
+    try {
+      process.stdout.write(`${JSON.stringify(await context(path, line, radius), null, 2)}\n`);
+    } catch (error) {
+      process.stderr.write(`${error.message}\n`);
+      process.exitCode = 1;
+    }
+  }
+}

package/skills/groundtrack-impact/scripts/evidence.mjs

@@ -0,0 +1,420 @@
+#!/usr/bin/env node
+// Read-only, local-only triage. Outputs selected evidence, not whole transcripts.
+import { createReadStream } from "node:fs";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import { createInterface } from "node:readline";
+import { fileURLToPath } from "node:url";
+
+import { scan } from "./scan.mjs";
+
+function property(source, key) {
+  if (!source) return null;
+  const pattern = new RegExp(`(?:["']?${key}["']?)\\s*:\\s*(["'\x60])`, "g");
+  const match = pattern.exec(source);
+  if (!match) return null;
+  const quote = match[1];
+  let value = "";
+  for (let i = pattern.lastIndex; i < source.length; i++) {
+    const char = source[i];
+    if (char === "\\" && i + 1 < source.length) {
+      value += source[++i];
+      continue;
+    }
+    if (char === quote) return value;
+    value += char;
+  }
+  return null;
+}
+
+function invocationArguments(source, start) {
+  const brackets = [];
+  let quote = null;
+  let escaped = false;
+  for (let i = start; i < source.length; i++) {
+    const char = source[i];
+    if (quote) {
+      if (escaped) escaped = false;
+      else if (char === "\\") escaped = true;
+      else if (char === quote) quote = null;
+    } else if ("\"'`".includes(char)) quote = char;
+    else if ("({[".includes(char)) brackets.push(char);
+    else if (")}]".includes(char)) {
+      const expected = { ")": "(", "}": "{", "]": "[" }[char];
+      if (brackets.pop() !== expected) return "";
+      if (!brackets.length) return source.slice(start + 1, i);
+    }
+  }
+  return "";
+}
+
+function invocation(tool, input) {
+  const direct = /^mcp__groundtrack__(\w+)$/.exec(tool || "");
+  if (direct) return [{ tool: direct[1], args: input }];
+  if (!["functions.exec", "exec"].includes(tool) || typeof input !== "string") return [];
+  return [...input.matchAll(/\btools\.mcp__groundtrack__(\w+)\s*\(/g)].map((match) => ({
+    tool: match[1],
+    args: invocationArguments(input, match.index + match[0].length - 1),
+  }));
+}
+
+function field(args, key) {
+  return typeof args === "string" ? property(args, key) : (args?.[key] ?? null);
+}
+
+function listField(args, key) {
+  if (typeof args !== "string") return args?.[key] ?? null;
+  const match = new RegExp(`(?:["']?${key}["']?)\\s*:\\s*\\[([^\\]]*)\\]`).exec(args);
+  return match ? [...match[1].matchAll(/["']([^"']+)["']/g)].map((item) => item[1]) : null;
+}
+
+function numberField(args, key) {
+  if (typeof args !== "string") return args?.[key] ?? null;
+  const match = new RegExp(`(?:["']?${key}["']?)\\s*:\\s*(\\d+)`).exec(args);
+  return match ? Number(match[1]) : null;
+}
+
+function snippets(record, agent, line) {
+  if (agent === "codex") {
+    if (record?.type !== "response_item") return [];
+    const payload = record.payload;
+    if (["custom_tool_call", "function_call"].includes(payload?.type)) {
+      return invocation(payload.name, payload.input ?? payload.arguments).map(({ tool, args }) => ({
+        tool,
+        args,
+        line,
+        callId: payload.call_id || null,
+        at: record.timestamp || null,
+      }));
+    }
+    return [];
+  }
+  if (record?.type !== "assistant" || !Array.isArray(record.message?.content)) return [];
+  return record.message.content.flatMap((block) =>
+    block?.type === "tool_use"
+      ? invocation(block.name, block.input).map(({ tool, args }) => ({
+          tool,
+          args,
+          line,
+          callId: block.id || null,
+          at: record.timestamp || null,
+        }))
+      : [],
+  );
+}
+
+function acceptedLinkEventIds(body) {
+  const ids = new Set();
+  function inspect(value, depth = 0) {
+    if (depth > 8 || value == null) return;
+    if (typeof value === "string") {
+      try {
+        inspect(JSON.parse(value), depth + 1);
+      } catch {
+        // Wrapper output can include status text; only structured responses prove acceptance.
+      }
+    } else if (Array.isArray(value)) {
+      for (const item of value) inspect(item, depth + 1);
+    } else if (typeof value === "object" && value.isError !== true) {
+      if (Array.isArray(value.linked)) {
+        for (const item of value.linked) {
+          if (typeof item?.rawEventId === "string") ids.add(item.rawEventId);
+        }
+      } else inspect(value.linked, depth + 1);
+      inspect(value.link, depth + 1);
+      inspect(value.result, depth + 1);
+      inspect(value.structuredContent, depth + 1);
+      inspect(value.content, depth + 1);
+      if (typeof value.text === "string") inspect(value.text, depth + 1);
+    }
+  }
+  inspect(body);
+  return [...ids];
+}
+
+async function readEvidence(path, agent, sinceMs, untilMs) {
+  const rows = [];
+  const results = new Map();
+  let line = 0;
+  const input = createInterface({ input: createReadStream(path), crlfDelay: Infinity });
+  for await (const text of input) {
+    line++;
+    let record;
+    try {
+      record = JSON.parse(text);
+    } catch {
+      continue;
+    }
+    const at = Date.parse(record?.timestamp || record?.payload?.timestamp || "");
+    if (untilMs !== null && Number.isFinite(at) && at > untilMs) continue;
+    if (sinceMs !== null && (!Number.isFinite(at) || at < sinceMs)) continue;
+    for (const entry of snippets(record, agent, line)) rows.push({ ...entry, path });
+    if (
+      agent === "codex" &&
+      record?.type === "response_item" &&
+      ["custom_tool_call_output", "function_call_output"].includes(record.payload?.type) &&
+      record.payload.call_id
+    ) {
+      results.set(record.payload.call_id, {
+        body:
+          typeof record.payload.output === "string"
+            ? record.payload.output
+            : JSON.stringify(record.payload.output),
+        error: false,
+      });
+    } else if (
+      agent === "claude" &&
+      record?.type === "user" &&
+      Array.isArray(record.message?.content)
+    ) {
+      for (const block of record.message.content.filter(
+        (part) => part?.type === "tool_result" && part.tool_use_id,
+      )) {
+        results.set(block.tool_use_id, {
+          body: typeof block.content === "string" ? block.content : JSON.stringify(block.content),
+          error: block.is_error === true,
+        });
+      }
+    }
+  }
+  return rows.map((row) => {
+    const result = results.get(row.callId);
+    const requestedEventIds = listField(row.args, "rawEventIds") || [];
+    const acceptedRawEventIds =
+      row.tool === "link_outcomes" && result && !result.error
+        ? acceptedLinkEventIds(result.body).filter((id) => requestedEventIds.includes(id))
+        : [];
+    return {
+      ...row,
+      resultSeen: Boolean(result),
+      resultError: result?.error || false,
+      ...(row.tool === "link_outcomes" ? { acceptedRawEventIds } : {}),
+      successMarker:
+        row.tool === "link_outcomes"
+          ? acceptedRawEventIds.length > 0
+          : (result &&
+              !result.error &&
+              result.body?.includes(
+                row.tool === "report_experience_use"
+                  ? "reportId"
+                  : row.tool === "record_outcome"
+                    ? "completedAt"
+                    : "retrievalId",
+              )) ||
+            false,
+    };
+  });
+}
+
+function present(row) {
+  const { args, ...location } = row;
+  if (row.tool === "report_experience_use") {
+    return {
+      ...location,
+      verdict: field(args, "verdict"),
+      explanation: field(args, "explanation"),
+      retrievalId: field(args, "retrievalId"),
+      effects:
+        typeof args === "string"
+          ? [
+              ...args.matchAll(
+                /(?:["']?effect["']?)\s*:\s*["'](applied|avoided_failure|relevant|irrelevant|rejected)["']/g,
+              ),
+            ].map((match) => match[1])
+          : args?.effects?.map((effect) => effect.effect) || [],
+      experienceIds:
+        typeof args === "string"
+          ? [...args.matchAll(/(?:["']?experienceId["']?)\s*:\s*["']([^"']+)["']/g)].map(
+              (match) => match[1],
+            )
+          : args?.effects?.map((effect) => effect.experienceId) || [],
+    };
+  }
+  if (row.tool === "record_outcome")
+    return {
+      ...location,
+      title: field(args, "title"),
+      summary: field(args, "summary"),
+      retrievalIds: listField(args, "retrievalIds"),
+      rawEventIds: listField(args, "rawEventIds"),
+    };
+  if (row.tool === "search_experiences") return { ...location, query: field(args, "query") };
+  if (row.tool === "link_outcomes")
+    return {
+      ...location,
+      prNumber: numberField(args, "prNumber"),
+      prUrl: field(args, "prUrl"),
+      repoKey: field(args, "repoKey"),
+      commitSha: field(args, "commitSha"),
+      rawEventIds: listField(args, "rawEventIds"),
+    };
+  return location;
+}
+
+export async function evidence(options, sessionId = null) {
+  const census = await scan(options);
+  const sessions = [];
+  for (const candidate of census.candidates.filter(
+    (row) => !sessionId || row.sessionId === sessionId,
+  )) {
+    const rows = [];
+    const seen = new Set();
+    for (const path of candidate.files) {
+      for (const row of await readEvidence(
+        path,
+        candidate.agent,
+        options.since ? Date.parse(options.since) : null,
+        options.until ? Date.parse(options.until) : null,
+      )) {
+        const key = row.callId
+          ? `${row.callId}:${row.tool}:${row.args && JSON.stringify(row.args)}`
+          : `${row.path}:${row.line}:${row.tool}`;
+        if (seen.has(key)) continue;
+        seen.add(key);
+        rows.push(present(row));
+      }
+    }
+    sessions.push({
+      agent: candidate.agent,
+      sessionId: candidate.sessionId,
+      repository: candidate.repository,
+      startedAt: candidate.startedAt,
+      files: candidate.files,
+      rows,
+    });
+  }
+  return { counts: census.counts, sessions };
+}
+
+function latestSuccessfulReports(rows) {
+  const latest = new Map();
+  for (const row of rows
+    .filter(
+      (item) => item.tool === "report_experience_use" && item.retrievalId && item.successMarker,
+    )
+    .sort((a, b) => (Date.parse(a.at || "") || 0) - (Date.parse(b.at || "") || 0))) {
+    latest.set(row.retrievalId, row);
+  }
+  return [...latest.values()];
+}
+
+export function chains(report) {
+  const found = new Map();
+  for (const session of report.sessions) {
+    // A later successful correction supersedes an earlier helpful verdict.
+    const reports = latestSuccessfulReports(session.rows).filter((row) => row.verdict === "helped");
+    const links = session.rows.filter(
+      (row) =>
+        row.tool === "link_outcomes" &&
+        row.successMarker &&
+        row.acceptedRawEventIds?.length &&
+        (row.prNumber || row.commitSha),
+    );
+    for (const outcome of session.rows.filter(
+      (row) =>
+        row.tool === "record_outcome" &&
+        row.title &&
+        row.retrievalIds?.length &&
+        row.rawEventIds?.length &&
+        row.successMarker,
+    )) {
+      const helpful = reports.filter((row) => outcome.retrievalIds.includes(row.retrievalId));
+      if (!helpful.length) continue;
+      for (const link of links.filter((row) =>
+        row.acceptedRawEventIds.some((id) => outcome.rawEventIds.includes(id)),
+      )) {
+        const key = `${link.repoKey || session.repository}:${link.prNumber || link.commitSha}:${outcome.title}`;
+        found.set(key, {
+          agent: session.agent,
+          sessionId: session.sessionId,
+          repository: link.repoKey || session.repository,
+          prNumber: link.prNumber,
+          prUrl: link.prUrl,
+          commitSha: link.commitSha,
+          title: outcome.title,
+          retrievalIds: [...new Set(helpful.map((row) => row.retrievalId))],
+          reportedHelp: [...new Set(helpful.map((row) => row.explanation).filter(Boolean))],
+          linkResultSeen: true,
+        });
+      }
+    }
+  }
+  return [...found.values()];
+}
+
+function cli(args) {
+  const options = {
+    codexHome: process.env.CODEX_HOME || join(homedir(), ".codex"),
+    claudeHome: process.env.CLAUDE_CONFIG_DIR || join(homedir(), ".claude"),
+    since: null,
+    until: null,
+  };
+  let session = null;
+  let reports = false;
+  let showChains = false;
+  for (let i = 0; i < args.length; i++) {
+    const key = args[i];
+    if (key === "--reports") reports = true;
+    else if (key === "--chains") showChains = true;
+    else if (
+      ["--session", "--since", "--until", "--codex-home", "--claude-home"].includes(key) &&
+      args[i + 1]
+    ) {
+      const value = args[++i];
+      if (key === "--session") session = value;
+      else if (key === "--since") options.since = value;
+      else if (key === "--until") options.until = value;
+      else options[key === "--codex-home" ? "codexHome" : "claudeHome"] = resolve(value);
+    } else throw new Error(`Unknown or incomplete option: ${key}`);
+  }
+  return { options, session, reports, showChains };
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  try {
+    const { options, session, reports, showChains } = cli(process.argv.slice(2));
+    const report = await evidence(options, session);
+    const selected = session
+      ? report.sessions.filter((row) => row.sessionId === session)
+      : report.sessions;
+    if (session && !selected.length) throw new Error(`Session not found: ${session}`);
+    const result = showChains
+      ? chains(report)
+      : session
+        ? selected
+        : reports
+          ? selected.flatMap((row) =>
+              row.rows
+                .filter((item) => item.tool === "report_experience_use")
+                .map((item) => ({
+                  agent: row.agent,
+                  sessionId: row.sessionId,
+                  repository: row.repository,
+                  startedAt: row.startedAt,
+                  ...item,
+                })),
+            )
+          : {
+              counts: report.counts,
+              sessions: selected.map((row) => ({
+                agent: row.agent,
+                sessionId: row.sessionId,
+                repository: row.repository,
+                startedAt: row.startedAt,
+                calls: row.rows.length,
+                helpedReports: row.rows.filter((item) => item.verdict === "helped").length,
+                currentHelpfulRetrievals: latestSuccessfulReports(row.rows).filter(
+                  (item) => item.verdict === "helped",
+                ).length,
+                otherReports: row.rows.filter(
+                  (item) => item.tool === "report_experience_use" && item.verdict !== "helped",
+                ).length,
+                outcomes: row.rows.filter((item) => item.tool === "record_outcome").length,
+              })),
+            };
+    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+  } catch (error) {
+    process.stderr.write(`${error.message}\n`);
+    process.exitCode = 1;
+  }
+}

package/skills/groundtrack-impact/scripts/scan.mjs

@@ -0,0 +1,309 @@
+#!/usr/bin/env node
+// Read-only candidate index. Transcript contents never appear in output.
+import { createReadStream, existsSync, readdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import { createInterface } from "node:readline";
+import { fileURLToPath } from "node:url";
+
+function repositoryLabel(value) {
+  if (typeof value !== "string") return null;
+  const match = value.replace(/\.git\/?$/, "").match(/(?:[:/])([^/:]+\/[^/:]+)$/);
+  return match ? match[1] : null;
+}
+
+function optionsFrom(args) {
+  const options = {
+    codexHome: process.env.CODEX_HOME || join(homedir(), ".codex"),
+    claudeHome: process.env.CLAUDE_CONFIG_DIR || join(homedir(), ".claude"),
+    since: null,
+    until: null,
+  };
+  for (let i = 0; i < args.length; i++) {
+    const key = args[i];
+    if (!["--codex-home", "--claude-home", "--since", "--until"].includes(key) || !args[i + 1]) {
+      throw new Error(
+        `Expected --codex-home PATH, --claude-home PATH, --since YYYY-MM-DD, or --until ISO timestamp; got ${key}`,
+      );
+    }
+    const value = args[++i];
+    if (key === "--since") {
+      if (!/^\d{4}-\d{2}-\d{2}$/.test(value) || Number.isNaN(Date.parse(value))) {
+        throw new Error(`Invalid --since date: ${value}`);
+      }
+      options.since = value;
+    } else if (key === "--until") {
+      if (
+        !/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?Z$/.test(value) ||
+        Number.isNaN(Date.parse(value))
+      ) {
+        throw new Error(`Invalid --until timestamp: ${value}`);
+      }
+      options.until = value;
+    } else options[key === "--codex-home" ? "codexHome" : "claudeHome"] = resolve(value);
+  }
+  return options;
+}
+
+function walk(root, files, unreadable) {
+  if (!existsSync(root)) return false;
+  let entries;
+  try {
+    entries = readdirSync(root, { withFileTypes: true });
+  } catch (error) {
+    unreadable.push({ path: root, error: error.code || error.message });
+    return true;
+  }
+  for (const entry of entries) {
+    const path = join(root, entry.name);
+    if (entry.isDirectory()) walk(path, files, unreadable);
+    else if (entry.isFile() && entry.name.endsWith(".jsonl")) files.push(path);
+  }
+  return true;
+}
+
+function groundtrackCalls(name, input) {
+  const direct = /^mcp__groundtrack__(\w+)$/.exec(name || "");
+  if (direct) return [{ tool: direct[1], kind: "direct" }];
+  if (!["functions.exec", "exec"].includes(name) || typeof input !== "string") return [];
+  // Proxy calls are leads only: a quoted invocation in JS may match too.
+  return [...input.matchAll(/\btools\.mcp__groundtrack__(\w+)\s*\(/g)].map((match) => ({
+    tool: match[1],
+    kind: "wrapper-lead",
+  }));
+}
+
+function callsIn(record, agent) {
+  if (agent === "codex") {
+    if (record?.type !== "response_item") return [];
+    const payload = record.payload;
+    if (!["custom_tool_call", "function_call"].includes(payload?.type)) return [];
+    return groundtrackCalls(payload.name, payload.input ?? payload.arguments).map((call) => ({
+      ...call,
+      callId: payload.call_id || null,
+      timestamp: record.timestamp || null,
+    }));
+  }
+  if (record?.type !== "assistant" || !Array.isArray(record.message?.content)) return [];
+  return record.message.content.flatMap((block) => {
+    if (block?.type !== "tool_use") return [];
+    return groundtrackCalls(block.name, block.input).map((call) => ({
+      ...call,
+      callId: block.id || null,
+      timestamp: record.timestamp || null,
+    }));
+  });
+}
+
+function reviewLeadIn(record, agent) {
+  let output;
+  let callId;
+  if (
+    agent === "codex" &&
+    record?.type === "response_item" &&
+    ["custom_tool_call_output", "function_call_output"].includes(record.payload?.type)
+  ) {
+    output = record.payload.output;
+    callId = record.payload.call_id;
+  } else if (
+    agent === "claude" &&
+    record?.type === "user" &&
+    Array.isArray(record.message?.content)
+  ) {
+    const blocks = record.message.content.filter((part) => part?.type === "tool_result");
+    output = blocks.map((part) => part.content);
+    callId = blocks.map((part) => part.tool_use_id).join(",");
+  }
+  if (output == null) return null;
+  // Only tool results are searched; this is a lead, not proof of a Review finding.
+  const text = typeof output === "string" ? output : JSON.stringify(output);
+  return /\bgroundtrack[ -]review\b/i.test(text)
+    ? { callId: callId || null, timestamp: record.timestamp || null }
+    : null;
+}
+
+async function scanFile(path, agent, sinceMs, untilMs) {
+  const found = {
+    path,
+    agent,
+    sessionId: null,
+    startedAt: null,
+    repository: null,
+    calls: [],
+    reviewLeads: [],
+    malformedLines: 0,
+    readable: true,
+    eligibleRecords: 0,
+  };
+  let line = 0;
+  try {
+    const input = createInterface({ input: createReadStream(path), crlfDelay: Infinity });
+    for await (const text of input) {
+      line++;
+      if (!text.trim()) continue;
+      let record;
+      try {
+        record = JSON.parse(text);
+      } catch {
+        found.malformedLines++;
+        continue;
+      }
+      const at = Date.parse(record?.timestamp || record?.payload?.timestamp || "");
+      if (untilMs !== null && Number.isFinite(at) && at > untilMs) continue;
+      if (agent === "codex" && record?.type === "session_meta" && !found.sessionId) {
+        found.sessionId = record.payload?.session_id || record.payload?.id || null;
+        found.startedAt = record.payload?.timestamp || record.timestamp || null;
+        found.repository = repositoryLabel(record.payload?.git?.repository_url);
+      } else if (agent === "claude" && !found.sessionId) {
+        found.sessionId = record?.sessionId || record?.session_id || null;
+        found.startedAt = record?.timestamp || null;
+      }
+      if (sinceMs !== null && (!Number.isFinite(at) || at < sinceMs)) continue;
+      found.eligibleRecords++;
+      for (const call of callsIn(record, agent)) found.calls.push({ ...call, path, line });
+      const lead = reviewLeadIn(record, agent);
+      if (lead) found.reviewLeads.push({ ...lead, path, line });
+    }
+  } catch (error) {
+    found.readable = false;
+    found.error = error.code || error.message;
+  }
+  return found;
+}
+
+export async function scan(options) {
+  if (
+    options.since &&
+    (!/^\d{4}-\d{2}-\d{2}$/.test(options.since) || Number.isNaN(Date.parse(options.since)))
+  )
+    throw new Error(`Invalid --since date: ${options.since}`);
+  if (
+    options.until &&
+    (!/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?Z$/.test(options.until) ||
+      Number.isNaN(Date.parse(options.until)))
+  )
+    throw new Error(`Invalid --until timestamp: ${options.until}`);
+  const roots = [
+    { agent: "codex", path: join(options.codexHome, "sessions") },
+    { agent: "codex", path: join(options.codexHome, "archived_sessions") },
+    { agent: "claude", path: join(options.claudeHome, "projects") },
+  ];
+  const missingRoots = [];
+  const unreadable = [];
+  const files = [];
+  for (const root of roots) {
+    const paths = [];
+    if (!walk(root.path, paths, unreadable)) missingRoots.push(root);
+    for (const path of paths) files.push({ path, agent: root.agent });
+  }
+  const counts = Object.fromEntries(
+    ["codex", "claude"].map((agent) => [
+      agent,
+      {
+        filesFound: 0,
+        filesEligible: 0,
+        filesReadable: 0,
+        filesUnreadable: 0,
+        filesAfterUntil: 0,
+        filesOutsideWindow: 0,
+        malformedLines: 0,
+        sessions: 0,
+        candidateSessions: 0,
+        noncandidateSessions: 0,
+        sessionsWithoutMetadata: 0,
+        groundtrackCallSessions: 0,
+        reviewLeadSessions: 0,
+      },
+    ]),
+  );
+  const sessions = new Map();
+  for (const file of files) {
+    const count = counts[file.agent];
+    count.filesFound++;
+    count.filesEligible++;
+    const result = await scanFile(
+      file.path,
+      file.agent,
+      options.since ? Date.parse(options.since) : null,
+      options.until ? Date.parse(options.until) : null,
+    );
+    count.malformedLines += result.malformedLines;
+    if (!result.readable) {
+      count.filesUnreadable++;
+      unreadable.push({ path: file.path, error: result.error });
+      continue;
+    }
+    if (!result.eligibleRecords) {
+      count.filesEligible--;
+      if (options.since) count.filesOutsideWindow++;
+      else count.filesAfterUntil++;
+      continue;
+    }
+    count.filesReadable++;
+    if (!result.sessionId) count.sessionsWithoutMetadata++;
+    const key = `${file.agent}:${result.sessionId || file.path}`;
+    const session = sessions.get(key) || {
+      agent: file.agent,
+      sessionId: result.sessionId,
+      startedAt: result.startedAt,
+      repository: result.repository,
+      files: [],
+      calls: [],
+      reviewLeads: [],
+      _callKeys: new Set(),
+    };
+    session.files.push(file.path);
+    session.startedAt ||= result.startedAt;
+    session.repository ||= result.repository;
+    for (const call of result.calls) {
+      const callKey = call.callId
+        ? `${call.callId}:${call.tool}`
+        : `${call.path}:${call.line}:${call.tool}`;
+      if (!session._callKeys.has(callKey)) {
+        session.calls.push(call);
+        session._callKeys.add(callKey);
+      }
+    }
+    for (const lead of result.reviewLeads) {
+      const leadKey = `review:${lead.callId || `${lead.path}:${lead.line}`}`;
+      if (!session._callKeys.has(leadKey)) {
+        session.reviewLeads.push(lead);
+        session._callKeys.add(leadKey);
+      }
+    }
+    sessions.set(key, session);
+  }
+  const candidates = [];
+  for (const session of sessions.values()) {
+    const count = counts[session.agent];
+    count.sessions++;
+    if (session.calls.length) count.groundtrackCallSessions++;
+    if (session.reviewLeads.length) count.reviewLeadSessions++;
+    if (session.calls.length || session.reviewLeads.length) {
+      count.candidateSessions++;
+      delete session._callKeys;
+      candidates.push(session);
+    } else count.noncandidateSessions++;
+  }
+  return {
+    scope: {
+      sinceRecordTimestamp: options.since,
+      untilRecordTimestamp: options.until || null,
+      roots,
+      missingRoots,
+    },
+    counts,
+    unreadable,
+    candidates,
+  };
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  try {
+    const report = await scan(optionsFrom(process.argv.slice(2)));
+    process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+  } catch (error) {
+    process.stderr.write(`${error.message}\n`);
+    process.exitCode = 1;
+  }
+}