feat: expand starter scar pack to 12 with community-proposed scars (OD-780)

Claude · claude · Claude · commit 262593cc6ce6 · 2026-02-22T15:12:54.000-05:00
Add 5 community-proposed starter scars covering multi-agent delegation,
memory hygiene, and communication patterns. Fix is_active filter, add
learning_type to recall results, set explicit is_active on creation.

Co-Authored-By: Claude Opus 4.6 &lt;noreply@anthropic.com&gt;
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -7,6 +7,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.3.4] - 2026-02-22
+
+### Added
+- **Expanded starter scar pack** (7 → 12): Five new community-proposed scars covering multi-agent delegation, memory hygiene, and communication patterns.
+- **Closing payload pre-seeded during init**: `closing-payload.json` template created at install time, preventing Write permission prompt on first session close.
+- **`contribute_feedback` tool**: Agents can submit anonymous feedback (feature requests, bugs, friction) to help improve gitmem.
+
+### Fixed
+- **`is_active` filter for free tier**: `list()` now treats missing `is_active` as `true` instead of filtering out all learnings without the field.
+- **`learning_type` in recall results**: Recall now returns `learning_type` in search results so agents can distinguish scars from wins and patterns.
+- **Explicit `is_active: true` on learning creation**: New learnings are created with `is_active: true` to prevent filter mismatches.
+
 ## [1.3.1] - 2026-02-22
 
 ### Fixed
diff --git a/package.json b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "gitmem-mcp",
-  "version": "1.3.3",
+  "version": "1.3.4",
   "mcpName": "io.github.gitmem-dev/gitmem",
   "description": "Persistent learning memory for AI coding agents. Memory that compounds.",
   "type": "module",
diff --git a/schema/starter-scars.json b/schema/starter-scars.json
@@ -124,5 +124,95 @@
     "project": "default",
     "source_date": "2026-01-01",
     "created_at": "2026-01-01T00:00:00Z"
+  },
+  {
+    "id": "5c1111a9-c161-4b2d-83f9-063780164b7c",
+    "learning_type": "scar",
+    "title": "Sub-agents Start With Zero Context — Always Inject Memory",
+    "description": "When you spawn a sub-agent (Task tool), it starts with a blank slate — no conversation history, no institutional memory, no project context. If you don't explicitly inject context via prepare_context or a detailed prompt, the sub-agent will repeat mistakes the team already learned from. The 2-3 seconds to prepare context prevents minutes of wasted work.",
+    "severity": "high",
+    "scar_type": "process",
+    "is_starter": true,
+    "counter_arguments": [
+      "The sub-agent has access to the same tools so it can figure things out — but without memory context it will rediscover pitfalls the hard way",
+      "Injecting context slows down spawning — but 2-3 seconds of prep prevents full task re-runs when the agent hits a known issue"
+    ],
+    "keywords": ["sub-agent", "task-tool", "context", "delegation", "multi-agent", "prepare-context"],
+    "domain": ["multi-agent", "delegation"],
+    "project": "default",
+    "source_date": "2026-02-22",
+    "created_at": "2026-02-22T00:00:00Z"
+  },
+  {
+    "id": "f7d1dcb8-dcf1-48fb-9ab0-e682cd704530",
+    "learning_type": "scar",
+    "title": "Sub-agents Cannot See Your Conversation — Spell Out Everything",
+    "description": "Sub-agents spawned via the Task tool do not inherit the parent conversation. They cannot see what the user asked, what files were discussed, or what decisions were made. Every requirement, file path, and constraint must be explicitly stated in the task prompt. Vague delegation like 'fix the bug we discussed' will fail because the sub-agent has no idea what was discussed.",
+    "severity": "high",
+    "scar_type": "process",
+    "is_starter": true,
+    "counter_arguments": [
+      "The sub-agent description says it has 'access to current context' — but only certain agent types do, and even then the full nuance of the conversation may not transfer",
+      "I can just tell it to 'continue the work' — but without explicit requirements the sub-agent will interpret 'the work' differently than you intended"
+    ],
+    "keywords": ["sub-agent", "delegation", "prompt", "requirements", "context-loss", "multi-agent"],
+    "domain": ["multi-agent", "delegation"],
+    "project": "default",
+    "source_date": "2026-02-22",
+    "created_at": "2026-02-22T00:00:00Z"
+  },
+  {
+    "id": "060389aa-c0fa-445d-bbfd-5d9250dc1e73",
+    "learning_type": "scar",
+    "title": "Don't Pre-read Files Before Delegating — Let the Sub-agent Read Them",
+    "description": "Reading files into your context before spawning a sub-agent wastes your context window and doesn't help the sub-agent (it can't see what you read). Instead, tell the sub-agent which files to read. The sub-agent has its own context budget and its own file access. Pre-reading just burns tokens twice.",
+    "severity": "medium",
+    "scar_type": "process",
+    "is_starter": true,
+    "counter_arguments": [
+      "I need to understand the code before I can write a good prompt — true for architecture decisions, but for 'read and fix' tasks the sub-agent can do its own reading",
+      "What if the sub-agent reads the wrong files — provide specific file paths in the prompt rather than reading them yourself"
+    ],
+    "keywords": ["sub-agent", "context-window", "delegation", "file-reading", "tokens", "multi-agent"],
+    "domain": ["multi-agent", "efficiency"],
+    "project": "default",
+    "source_date": "2026-02-22",
+    "created_at": "2026-02-22T00:00:00Z"
+  },
+  {
+    "id": "55b25d2e-41ad-47f4-8723-569b78586dff",
+    "learning_type": "scar",
+    "title": "Search Memory Before Creating Learnings — Duplicates Dilute Recall",
+    "description": "Before creating a new scar, win, or pattern, search existing memory first. Duplicate entries dilute recall quality — when the same lesson exists three times with slightly different wording, search results waste slots on redundant matches instead of surfacing diverse, relevant knowledge. One well-written scar beats three near-duplicates.",
+    "severity": "medium",
+    "scar_type": "process",
+    "is_starter": true,
+    "counter_arguments": [
+      "Creating duplicates reinforces the lesson — but recall is similarity-based, so duplicates just crowd out other useful results",
+      "My wording is better than the existing one — then update the existing entry instead of creating a new one"
+    ],
+    "keywords": ["memory", "search", "duplicates", "recall", "learning", "scar-creation"],
+    "domain": ["memory-hygiene", "gitmem"],
+    "project": "default",
+    "source_date": "2026-02-22",
+    "created_at": "2026-02-22T00:00:00Z"
+  },
+  {
+    "id": "867cf3f6-a0e5-4ca2-8d4d-43cb1f10d94d",
+    "learning_type": "scar",
+    "title": "Ask Clarifying Questions Before Coding — 5 Seconds Prevents a Rewrite",
+    "description": "When requirements are ambiguous, ask a clarifying question before writing code. A 5-second question like 'Should this handle both cases or just the first?' prevents building the wrong thing and having to rewrite. Assumptions that seem obvious are often wrong. The cost of asking is near-zero; the cost of a wrong assumption is a full task redo.",
+    "severity": "high",
+    "scar_type": "process",
+    "is_starter": true,
+    "counter_arguments": [
+      "Asking too many questions slows things down — but one targeted question is faster than a rewrite after building the wrong thing",
+      "I can just build both options and let the user pick — but that's double the work and the user wanted a decision, not a menu"
+    ],
+    "keywords": ["requirements", "clarification", "assumptions", "communication", "rewrite"],
+    "domain": ["communication", "planning"],
+    "project": "default",
+    "source_date": "2026-02-22",
+    "created_at": "2026-02-22T00:00:00Z"
   }
 ]
diff --git a/src/services/local-file-storage.ts b/src/services/local-file-storage.ts
@@ -83,7 +83,12 @@ export class LocalFileStorage {
     if (options.filters) {
       for (const [key, value] of Object.entries(options.filters)) {
         const cleanValue = value.startsWith("eq.") ? value.slice(3) : value;
-        records = records.filter((r) => String(r[key]) === cleanValue);
+        if (key === "is_active" && cleanValue === "true") {
+          // is_active defaults to true when not explicitly set
+          records = records.filter((r) => r[key] !== false);
+        } else {
+          records = records.filter((r) => String(r[key]) === cleanValue);
+        }
       }
     }
 
@@ -183,6 +188,7 @@ export class LocalFileStorage {
       mapped.push({
         id: r.id,
         title: String(l.title),
+        learning_type: String(l.learning_type || "scar"),
         description: String(l.description),
         severity: String(l.severity || "medium"),
         counter_arguments: (l.counter_arguments as string[]) || [],
diff --git a/src/tools/create-learning.ts b/src/tools/create-learning.ts
@@ -113,6 +113,7 @@ export async function createLearning(
     created_at: new Date().toISOString(),
     persona_name: agentIdentity,
     source_date: new Date().toISOString().split("T")[0],
+    is_active: true,
     // LLM-cooperative enforcement fields (optional)
     ...(params.why_this_matters && { why_this_matters: params.why_this_matters }),
     ...(params.action_protocol && { action_protocol: params.action_protocol }),
diff --git a/tests/fixtures/starter-scars.ts b/tests/fixtures/starter-scars.ts
@@ -1,15 +1,15 @@
 /**
  * Test Fixtures: Starter Scars
  *
- * These match the 3 starter scars that ship with gitmem.
+ * Representative subset of the 12 starter scars that ship with gitmem.
  * Used for testing the "fresh install with starter scars" scenario.
  */
 
 import { randomUUID } from "crypto";
 import type { TestScar } from "./scars.js";
 
 /**
- * The 3 starter scars for fresh installations
+ * Representative subset of starter scars for fresh installations
  */
 export const STARTER_SCARS: TestScar[] = [
   {
diff --git a/tests/unit/services/local-file-storage.test.ts b/tests/unit/services/local-file-storage.test.ts
@@ -1,8 +1,8 @@
 /**
- * Unit tests for LocalFileStorage — starter scars timestamp fix
+ * Unit tests for LocalFileStorage
  *
- * Verifies that loadStarterScars stamps created_at to install time
- * instead of using hardcoded dates from starter-scars.json.
+ * Covers: loadStarterScars, keywordSearch learning_type propagation,
+ * list() is_active filter handling, and learning_type filtering.
  */
 
 import { describe, it, expect, beforeEach, afterEach } from "vitest";
@@ -82,3 +82,157 @@ describe("LocalFileStorage.loadStarterScars", () => {
     expect(learnings).toHaveLength(2);
   });
 });
+
+describe("LocalFileStorage.keywordSearch — learning_type propagation", () => {
+  let tmpDir: string;
+  let storage: LocalFileStorage;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "gitmem-test-"));
+    storage = new LocalFileStorage(tmpDir);
+
+    // Seed learnings with different types
+    const learnings = [
+      {
+        id: "scar-1",
+        title: "Database migration rollback",
+        description: "Always test rollback before migrating",
+        learning_type: "scar",
+        severity: "high",
+        keywords: ["database", "migration"],
+        is_active: true,
+      },
+      {
+        id: "pattern-1",
+        title: "Database connection pooling pattern",
+        description: "Use connection pooling for database access",
+        learning_type: "pattern",
+        severity: "low",
+        keywords: ["database", "connection"],
+        is_active: true,
+      },
+      {
+        id: "win-1",
+        title: "Database query optimization win",
+        description: "Indexing improved database query speed 10x",
+        learning_type: "win",
+        severity: "medium",
+        keywords: ["database", "optimization"],
+        is_active: true,
+      },
+    ];
+    const filePath = path.join(tmpDir, "learnings.json");
+    fs.writeFileSync(filePath, JSON.stringify(learnings));
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  it("returns learning_type for each result", async () => {
+    const results = await storage.keywordSearch("database", 10);
+    expect(results.length).toBeGreaterThanOrEqual(3);
+
+    const types = results.map((r) => r.learning_type);
+    expect(types).toContain("scar");
+    expect(types).toContain("pattern");
+    expect(types).toContain("win");
+  });
+
+  it("does not default all results to scar", async () => {
+    const results = await storage.keywordSearch("database", 10);
+    const nonScars = results.filter((r) => r.learning_type !== "scar");
+    expect(nonScars.length).toBeGreaterThanOrEqual(2);
+  });
+
+  it("preserves learning_type for patterns", async () => {
+    const results = await storage.keywordSearch("connection pooling", 5);
+    const pattern = results.find((r) => r.id === "pattern-1");
+    expect(pattern).toBeDefined();
+    expect(pattern!.learning_type).toBe("pattern");
+  });
+
+  it("preserves learning_type for wins", async () => {
+    const results = await storage.keywordSearch("optimization", 5);
+    const win = results.find((r) => r.id === "win-1");
+    expect(win).toBeDefined();
+    expect(win!.learning_type).toBe("win");
+  });
+});
+
+describe("LocalFileStorage.list — is_active filter", () => {
+  let tmpDir: string;
+  let storage: LocalFileStorage;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "gitmem-test-"));
+    storage = new LocalFileStorage(tmpDir);
+
+    // Seed learnings: some with is_active, some without (should default to active)
+    const learnings = [
+      {
+        id: "active-explicit",
+        title: "Explicitly active",
+        learning_type: "scar",
+        severity: "high",
+        is_active: true,
+        created_at: "2026-02-22T00:00:00Z",
+      },
+      {
+        id: "active-implicit",
+        title: "Implicitly active (no is_active field)",
+        learning_type: "pattern",
+        severity: "low",
+        created_at: "2026-02-21T00:00:00Z",
+        // NOTE: no is_active field — should be treated as active
+      },
+      {
+        id: "archived",
+        title: "Archived learning",
+        learning_type: "scar",
+        severity: "medium",
+        is_active: false,
+        created_at: "2026-02-20T00:00:00Z",
+      },
+    ];
+    const filePath = path.join(tmpDir, "learnings.json");
+    fs.writeFileSync(filePath, JSON.stringify(learnings));
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  it("includes records without is_active when filtering for active", async () => {
+    const results = await storage.list("learnings", {
+      filters: { is_active: "eq.true" },
+    });
+    const ids = results.map((r) => r.id);
+    expect(ids).toContain("active-explicit");
+    expect(ids).toContain("active-implicit");
+    expect(ids).not.toContain("archived");
+  });
+
+  it("excludes archived records", async () => {
+    const results = await storage.list("learnings", {
+      filters: { is_active: "eq.true" },
+    });
+    expect(results).toHaveLength(2);
+  });
+
+  it("filters by learning_type correctly", async () => {
+    const results = await storage.list("learnings", {
+      filters: { learning_type: "pattern" },
+    });
+    expect(results).toHaveLength(1);
+    expect(results[0].id).toBe("active-implicit");
+  });
+
+  it("combines is_active and learning_type filters", async () => {
+    const results = await storage.list("learnings", {
+      filters: { is_active: "eq.true", learning_type: "scar" },
+    });
+    expect(results).toHaveLength(1);
+    expect(results[0].id).toBe("active-explicit");
+  });
+});

Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`{`
`2`	`2`	`"name": "gitmem-mcp",`
`3`		`- "version": "1.3.3",`
	`3`	`+ "version": "1.3.4",`
`4`	`4`	`"mcpName": "io.github.gitmem-dev/gitmem",`
`5`	`5`	`"description": "Persistent learning memory for AI coding agents. Memory that compounds.",`
`6`	`6`	`"type": "module",`