feat: ship closing payload schema with init and session_start

Agents frequently guess wrong field names for closing-payload.json,
causing validation failures on session_close. Two fixes:

1. gitmem init now creates .gitmem/closing-payload-template.json with
   exact field names (survives context compaction)
2. session_start/refresh results include closing_payload_schema so
   agents have the schema in-context without reading a file

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

Author: 2 people

bin/init-wizard.js

@@ -506,6 +506,36 @@ async function stepMemoryStore() {
     }
   }
 
+  // Closing payload template — agents read this before writing closing-payload.json
+  const templatePath = join(gitmemDir, "closing-payload-template.json");
+  if (!existsSync(templatePath)) {
+    writeJson(templatePath, {
+      closing_reflection: {
+        what_broke: "",
+        what_took_longer: "",
+        do_differently: "",
+        what_worked: "",
+        wrong_assumption: "",
+        scars_applied: [],
+        institutional_memory_items: "",
+        collaborative_dynamic: "",
+        rapport_notes: ""
+      },
+      task_completion: {
+        questions_displayed_at: "ISO-8601 timestamp",
+        reflection_completed_at: "ISO-8601 timestamp",
+        human_asked_at: "ISO-8601 timestamp",
+        human_response_at: "ISO-8601 timestamp",
+        human_response: "no corrections | actual corrections text"
+      },
+      human_corrections: "",
+      scars_to_record: [],
+      learnings_created: [],
+      open_threads: [],
+      decisions: []
+    });
+  }
+
   console.log(
     `  Created .gitmem/ with ${starterScars.length} starter scars` +
       (added < starterScars.length

src/tools/session-start.ts

@@ -50,6 +50,34 @@ import type {
   ThreadObject,
 } from "../types/index.js";
 
+/**
+ * Closing payload schema — returned in session_start/refresh so agents
+ * know the exact field names for closing-payload.json without guessing.
+ */
+const CLOSING_PAYLOAD_SCHEMA: Record<string, unknown> = {
+  closing_reflection: {
+    what_broke: "Q1: What broke that you didn't expect?",
+    what_took_longer: "Q2: What took longer than it should have?",
+    do_differently: "Q3: What would you do differently next time?",
+    what_worked: "Q4: What pattern or approach worked well?",
+    wrong_assumption: "Q5: What assumption was wrong?",
+    scars_applied: ["Q6: scar titles applied"],
+    institutional_memory_items: "Q7: What to capture as institutional memory?",
+  },
+  task_completion: {
+    questions_displayed_at: "ISO-8601",
+    reflection_completed_at: "ISO-8601",
+    human_asked_at: "ISO-8601",
+    human_response_at: "ISO-8601",
+    human_response: "human's corrections or 'no corrections'",
+  },
+  human_corrections: "",
+  scars_to_record: [],
+  learnings_created: [],
+  open_threads: [],
+  decisions: [],
+};
+
 // Supabase record types
 interface SessionRecord {
   id: string;
@@ -539,6 +567,7 @@ async function sessionStartFree(
     ...(freeMergedThreads.length > 0 && { open_threads: freeMergedThreads }),
     recent_decisions: decisions,
     gitmem_dir: getGitmemDir(),
+    closing_payload_schema: CLOSING_PAYLOAD_SCHEMA,
     project,
     performance,
   };
@@ -1027,6 +1056,7 @@ export async function sessionStart(
     recent_decisions: decisions,
     ...(recordingPath && { recording_path: recordingPath }),
     gitmem_dir: getGitmemDir(),
+    closing_payload_schema: CLOSING_PAYLOAD_SCHEMA,
     project,
     performance,
   };
@@ -1195,6 +1225,7 @@ export async function sessionRefresh(
     recent_decisions: decisions,
     // Rapport disabled — not injected into session context
     ...(recordingPath && { recording_path: recordingPath }),
+    closing_payload_schema: CLOSING_PAYLOAD_SCHEMA,
     project,
     performance,
   };

src/types/index.ts

@@ -206,6 +206,8 @@ export interface SessionStartResult {
   recording_path?: string;
   /** Resolved .gitmem directory path — use for closing-payload.json writes */
   gitmem_dir?: string;
+  /** Closing payload schema — exact field names for closing-payload.json */
+  closing_payload_schema?: Record<string, unknown>;
   /** Project namespace for this session */
   project?: string;
   /** Pre-formatted display string for consistent CLI output */