feat: add reflect_scars tool and default execution_successful at session close

Close the scar enforcement gap where agents confirm scars (APPLYING) but
never report outcomes, causing 80% null execution_successful in scar_usage.

Option A: session_close defaults execution_successful based on confirm_scars
decision (APPLYING→true, unmentioned→false).

Option B: new reflect_scars tool (gitmem-rf/gm-reflect) for end-of-session
OBEYED/REFUTED evidence, bridged into scar_usage with priority over defaults.

Refs: OD-772

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: 2 people

src/server.ts

@@ -25,6 +25,7 @@ import { recordScarUsage } from "./tools/record-scar-usage.js";
 import { recordScarUsageBatch } from "./tools/record-scar-usage-batch.js";
 import { recall } from "./tools/recall.js";
 import { confirmScars } from "./tools/confirm-scars.js";
+import { reflectScars } from "./tools/reflect-scars.js";
 import { saveTranscript } from "./tools/save-transcript.js";
 import { getTranscript } from "./tools/get-transcript.js";
 import { searchTranscripts } from "./tools/search-transcripts.js";
@@ -82,6 +83,7 @@ import type {
   SaveTranscriptParams,
   GetTranscriptParams,
   ConfirmScarsParams,
+  ReflectScarsParams,
 } from "./types/index.js";
 import type { RecallParams } from "./tools/recall.js";
 import type { SearchParams } from "./tools/search.js";
@@ -159,6 +161,11 @@ export function createServer(): Server {
         case "gm-confirm":
           result = await confirmScars(toolArgs as unknown as ConfirmScarsParams);
           break;
+        case "reflect_scars":
+        case "gitmem-rf":
+        case "gm-reflect":
+          result = await reflectScars(toolArgs as unknown as ReflectScarsParams);
+          break;
         case "session_start":
         case "gitmem-ss":
         case "gm-open":
@@ -269,6 +276,7 @@ export function createServer(): Server {
           const commands = [
             { alias: "gitmem-r", full: "recall", description: "Check scars before taking action" },
             { alias: "gitmem-cs", full: "confirm_scars", description: "Confirm recalled scars (APPLYING/N_A/REFUTED)" },
+            { alias: "gitmem-rf", full: "reflect_scars", description: "End-of-session scar reflection (OBEYED/REFUTED)" },
             { alias: "gitmem-ss", full: "session_start", description: "Initialize session with context" },
             { alias: "gitmem-sr", full: "session_refresh", description: "Refresh context for active session" },
             { alias: "gitmem-sc", full: "session_close", description: "Close session with compliance validation" },

src/services/metrics.ts

@@ -35,6 +35,7 @@ export type ToolName =
   | "resolve_thread"
   | "create_thread"
   | "confirm_scars"
+  | "reflect_scars"
   | "cleanup_threads"
   | "health";
 
@@ -106,6 +107,7 @@ export const PERFORMANCE_TARGETS: Record<ToolName, number> = {
   resolve_thread: 100,      // In-memory mutation + file write
   create_thread: 100,       // In-memory mutation + file write
   confirm_scars: 500,       // In-memory validation + file write
+  reflect_scars: 500,       // In-memory validation + file write
   cleanup_threads: 2000,    // Fetch all threads + lifecycle computation
   health: 100,              // In-memory read from EffectTracker
 };

src/services/session-state.ts

@@ -12,7 +12,7 @@
  * This allows recall() to always assign variants even without explicit parameters.
  */
 
-import type { SurfacedScar, ScarConfirmation, Observation, SessionChild, ThreadObject } from "../types/index.js";
+import type { SurfacedScar, ScarConfirmation, ScarReflection, Observation, SessionChild, ThreadObject } from "../types/index.js";
 
 interface SessionContext {
   sessionId: string;
@@ -22,6 +22,7 @@ interface SessionContext {
   startedAt: Date;
   surfacedScars: SurfacedScar[]; // Track all scars surfaced during session
   confirmations: ScarConfirmation[]; // Refute-or-obey confirmations for recall-surfaced scars
+  reflections: ScarReflection[];    // End-of-session scar reflections (OBEYED/REFUTED)
   observations: Observation[];   // v2 Phase 2: Sub-agent/teammate observations
   children: SessionChild[];      // v2 Phase 2: Child agent records
   threads: ThreadObject[];       // : Working thread state
@@ -34,11 +35,12 @@ let currentSession: SessionContext | null = null;
  * Set the current active session
  * Called by session_start
  */
-export function setCurrentSession(context: Omit<SessionContext, 'surfacedScars' | 'confirmations' | 'observations' | 'children' | 'threads'> & { surfacedScars?: SurfacedScar[]; observations?: Observation[]; children?: SessionChild[]; threads?: ThreadObject[] }): void {
+export function setCurrentSession(context: Omit<SessionContext, 'surfacedScars' | 'confirmations' | 'reflections' | 'observations' | 'children' | 'threads'> & { surfacedScars?: SurfacedScar[]; observations?: Observation[]; children?: SessionChild[]; threads?: ThreadObject[] }): void {
   currentSession = {
     ...context,
     surfacedScars: context.surfacedScars || [],
     confirmations: [],
+    reflections: [],
     observations: context.observations || [],
     children: context.children || [],
     threads: context.threads || [],
@@ -137,6 +139,36 @@ export function getConfirmations(): ScarConfirmation[] {
   return currentSession?.confirmations || [];
 }
 
+/**
+ * Add end-of-session scar reflections (OBEYED/REFUTED) to the current session.
+ * Called by reflect_scars tool after validation.
+ */
+export function addReflections(reflections: ScarReflection[]): void {
+  if (!currentSession) {
+    console.warn("[session-state] Cannot add reflections: no active session");
+    return;
+  }
+
+  for (const ref of reflections) {
+    // Replace existing reflection for same scar_id (allow re-reflection)
+    const idx = currentSession.reflections.findIndex(r => r.scar_id === ref.scar_id);
+    if (idx >= 0) {
+      currentSession.reflections[idx] = ref;
+    } else {
+      currentSession.reflections.push(ref);
+    }
+  }
+
+  console.error(`[session-state] Reflections tracked: ${currentSession.reflections.length} total`);
+}
+
+/**
+ * Get all end-of-session scar reflections for the current session.
+ */
+export function getReflections(): ScarReflection[] {
+  return currentSession?.reflections || [];
+}
+
 /**
  * Check if there are recall-surfaced scars that haven't been confirmed.
  * Only checks scars with source "recall" — session_start scars don't require confirmation.

src/tools/definitions.ts

@@ -87,6 +87,39 @@ export const TOOLS = [
       required: ["confirmations"],
     },
   },
+  {
+    name: "reflect_scars",
+    description: "End-of-session scar reflection — the closing counterpart to confirm_scars. Mirrors CODA-1's [Scar Reflection] protocol. Call BEFORE session_close to provide evidence of how each surfaced scar was handled. OBEYED: concrete evidence of compliance (min 15 chars). REFUTED: why it didn't apply + what was done instead (min 30 chars). Session close uses reflections to set execution_successful accurately.",
+    inputSchema: {
+      type: "object" as const,
+      properties: {
+        reflections: {
+          type: "array",
+          items: {
+            type: "object",
+            properties: {
+              scar_id: {
+                type: "string",
+                description: "UUID of the surfaced scar (from recall or session_start)",
+              },
+              outcome: {
+                type: "string",
+                enum: ["OBEYED", "REFUTED"],
+                description: "OBEYED: followed the scar with evidence. REFUTED: scar didn't apply, explain why.",
+              },
+              evidence: {
+                type: "string",
+                description: "Concrete evidence of compliance (OBEYED, min 15 chars) or explanation of why scar didn't apply (REFUTED, min 30 chars).",
+              },
+            },
+            required: ["scar_id", "outcome", "evidence"],
+          },
+          description: "One reflection per surfaced scar.",
+        },
+      },
+      required: ["reflections"],
+    },
+  },
   {
     name: "session_start",
     description: "Initialize session, detect agent, load institutional context (last session, recent decisions, open threads). Scars surface on-demand via recall(). DISPLAY: The result includes a pre-formatted 'display' field visible in the tool result. Output the display field verbatim as your response — tool results are collapsed in the CLI.",
@@ -812,6 +845,29 @@ export const TOOLS = [
       required: ["confirmations"],
     },
   },
+  {
+    name: "gitmem-rf",
+    description: "gitmem-rf (reflect_scars) - End-of-session scar reflection (OBEYED/REFUTED with evidence)",
+    inputSchema: {
+      type: "object" as const,
+      properties: {
+        reflections: {
+          type: "array",
+          items: {
+            type: "object",
+            properties: {
+              scar_id: { type: "string", description: "UUID of the surfaced scar" },
+              outcome: { type: "string", enum: ["OBEYED", "REFUTED"], description: "Reflection outcome" },
+              evidence: { type: "string", description: "Evidence (OBEYED min 15 chars, REFUTED min 30 chars)" },
+            },
+            required: ["scar_id", "outcome", "evidence"],
+          },
+          description: "One reflection per surfaced scar",
+        },
+      },
+      required: ["reflections"],
+    },
+  },
   {
     name: "gitmem-ss",
     description: "gitmem-ss (session_start) - Initialize session with institutional context. DISPLAY: The result includes a pre-formatted 'display' field. Output the display field verbatim as your response — tool results are collapsed in the CLI.",
@@ -1510,6 +1566,29 @@ export const TOOLS = [
       required: ["confirmations"],
     },
   },
+  {
+    name: "gm-reflect",
+    description: "gm-reflect (reflect_scars) - End-of-session scar reflection",
+    inputSchema: {
+      type: "object" as const,
+      properties: {
+        reflections: {
+          type: "array",
+          items: {
+            type: "object",
+            properties: {
+              scar_id: { type: "string", description: "UUID of the surfaced scar" },
+              outcome: { type: "string", enum: ["OBEYED", "REFUTED"] },
+              evidence: { type: "string", description: "Evidence of compliance or refutation" },
+            },
+            required: ["scar_id", "outcome", "evidence"],
+          },
+          description: "One reflection per surfaced scar",
+        },
+      },
+      required: ["reflections"],
+    },
+  },
   {
     name: "gm-refresh",
     description: "gm-refresh (session_refresh) - Refresh context for the active session without creating a new one. DISPLAY: The result includes a pre-formatted 'display' field. Output the display field verbatim as your response — tool results are collapsed in the CLI.",
@@ -2196,15 +2275,15 @@ export const TOOLS = [
  */
 export const ALIAS_TOOL_NAMES = new Set([
   // gitmem-* aliases
-  "gitmem-r", "gitmem-cs", "gitmem-ss", "gitmem-sr", "gitmem-sc",
+  "gitmem-r", "gitmem-cs", "gitmem-rf", "gitmem-ss", "gitmem-sr", "gitmem-sc",
   "gitmem-cl", "gitmem-cd", "gitmem-rs", "gitmem-rsb",
   "gitmem-st", "gitmem-gt", "gitmem-stx",
   "gitmem-search", "gitmem-log", "gitmem-analyze",
   "gitmem-pc", "gitmem-ao",
   "gitmem-lt", "gitmem-rt", "gitmem-ct", "gitmem-ps", "gitmem-ds",
   "gitmem-cleanup", "gitmem-health", "gitmem-al", "gitmem-graph",
   // gm-* aliases
-  "gm-open", "gm-confirm", "gm-refresh", "gm-close",
+  "gm-open", "gm-confirm", "gm-reflect", "gm-refresh", "gm-close",
   "gm-scar", "gm-search", "gm-log", "gm-analyze",
   "gm-pc", "gm-absorb",
   "gm-threads", "gm-resolve", "gm-thread-new", "gm-promote", "gm-dismiss",