@gempack/squad-mcp 0.5.0 → 0.6.1

package/dist/index.js

@@ -1,15 +1,15 @@
 #!/usr/bin/env node
-import { Server } from '@modelcontextprotocol/sdk/server/index.js';
-import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-import { CallToolRequestSchema, ListToolsRequestSchema, ListResourcesRequestSchema, ReadResourceRequestSchema, ListPromptsRequestSchema, GetPromptRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
-import { registerTools, dispatchTool, listTools } from './tools/registry.js';
-import { listResources, readResource } from './resources/registry.js';
-import { listPrompts, getPrompt } from './prompts/registry.js';
-import { logger, setupProcessHandlers } from './observability/logger.js';
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, ListResourcesRequestSchema, ReadResourceRequestSchema, ListPromptsRequestSchema, GetPromptRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { registerTools, dispatchTool, listTools } from "./tools/registry.js";
+import { listResources, readResource } from "./resources/registry.js";
+import { listPrompts, getPrompt } from "./prompts/registry.js";
+import { logger, setupProcessHandlers } from "./observability/logger.js";
 setupProcessHandlers();
-const SERVER_VERSION = '0.5.0';
+const SERVER_VERSION = "0.6.1";
 const server = new Server({
-    name: 'squad-mcp',
+    name: "squad-mcp",
     version: SERVER_VERSION,
 }, {
     capabilities: {
@@ -19,15 +19,21 @@ const server = new Server({
     },
 });
 registerTools();
-server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: listTools() }));
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: listTools(),
+}));
 server.setRequestHandler(CallToolRequestSchema, async (req) => dispatchTool(req.params.name, req.params.arguments ?? {}));
-server.setRequestHandler(ListResourcesRequestSchema, async () => ({ resources: await listResources() }));
+server.setRequestHandler(ListResourcesRequestSchema, async () => ({
+    resources: await listResources(),
+}));
 server.setRequestHandler(ReadResourceRequestSchema, async (req) => readResource(req.params.uri));
-server.setRequestHandler(ListPromptsRequestSchema, async () => ({ prompts: listPrompts() }));
+server.setRequestHandler(ListPromptsRequestSchema, async () => ({
+    prompts: listPrompts(),
+}));
 server.setRequestHandler(GetPromptRequestSchema, async (req) => getPrompt(req.params.name, req.params.arguments ?? {}));
 const transport = new StdioServerTransport();
 await server.connect(transport);
-logger.info('server started', {
+logger.info("server started", {
     details: { version: SERVER_VERSION, tools: listTools().length },
 });
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AACnE,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EACL,qBAAqB,EACrB,sBAAsB,EACtB,0BAA0B,EAC1B,yBAAyB,EACzB,wBAAwB,EACxB,sBAAsB,GACvB,MAAM,oCAAoC,CAAC;AAC5C,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAC7E,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AACtE,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAC/D,OAAO,EAAE,MAAM,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AAEzE,oBAAoB,EAAE,CAAC;AAEvB,MAAM,cAAc,GAAG,OAAO,CAAC;AAE/B,MAAM,MAAM,GAAG,IAAI,MAAM,CACvB;IACE,IAAI,EAAE,WAAW;IACjB,OAAO,EAAE,cAAc;CACxB,EACD;IACE,YAAY,EAAE;QACZ,KAAK,EAAE,EAAE;QACT,SAAS,EAAE,EAAE;QACb,OAAO,EAAE,EAAE;KACZ;CACF,CACF,CAAC;AAEF,aAAa,EAAE,CAAC;AAEhB,MAAM,CAAC,iBAAiB,CAAC,sBAAsB,EAAE,KAAK,IAAI,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,SAAS,EAAE,EAAE,CAAC,CAAC,CAAC;AACvF,MAAM,CAAC,iBAAiB,CAAC,qBAAqB,EAAE,KAAK,EAAE,GAAG,EAAE,EAAE,CAAC,YAAY,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,SAAS,IAAI,EAAE,CAAC,CAAC,CAAC;AAE1H,MAAM,CAAC,iBAAiB,CAAC,0BAA0B,EAAE,KAAK,IAAI,EAAE,CAAC,CAAC,EAAE,SAAS,EAAE,MAAM,aAAa,EAAE,EAAE,CAAC,CAAC,CAAC;AACzG,MAAM,CAAC,iBAAiB,CAAC,yBAAyB,EAAE,KAAK,EAAE,GAAG,EAAE,EAAE,CAAC,YAAY,CAAC,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;AAEjG,MAAM,CAAC,iBAAiB,CAAC,wBAAwB,EAAE,KAAK,IAAI,EAAE,CAAC,CAAC,EAAE,OAAO,EAAE,WAAW,EAAE,EAAE,CAAC,CAAC,CAAC;AAC7F,MAAM,CAAC,iBAAiB,CAAC,sBAAsB,EAAE,KAAK,EAAE,GAAG,EAAE,EAAE,CAAC,SAAS,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,SAAS,IAAI,EAAE,CAAC,CAAC,CAAC;AAExH,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;AAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;AAEhC,MAAM,CAAC,IAAI,CAAC,gBAAgB,EAAE;IAC5B,OAAO,EAAE,EAAE,OAAO,EAAE,cAAc,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC,MAAM,EAAE;CAChE,CAAC,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AACnE,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EACL,qBAAqB,EACrB,sBAAsB,EACtB,0BAA0B,EAC1B,yBAAyB,EACzB,wBAAwB,EACxB,sBAAsB,GACvB,MAAM,oCAAoC,CAAC;AAC5C,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAC7E,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AACtE,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAC/D,OAAO,EAAE,MAAM,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AAEzE,oBAAoB,EAAE,CAAC;AAEvB,MAAM,cAAc,GAAG,OAAO,CAAC;AAE/B,MAAM,MAAM,GAAG,IAAI,MAAM,CACvB;IACE,IAAI,EAAE,WAAW;IACjB,OAAO,EAAE,cAAc;CACxB,EACD;IACE,YAAY,EAAE;QACZ,KAAK,EAAE,EAAE;QACT,SAAS,EAAE,EAAE;QACb,OAAO,EAAE,EAAE;KACZ;CACF,CACF,CAAC;AAEF,aAAa,EAAE,CAAC;AAEhB,MAAM,CAAC,iBAAiB,CAAC,sBAAsB,EAAE,KAAK,IAAI,EAAE,CAAC,CAAC;IAC5D,KAAK,EAAE,SAAS,EAAE;CACnB,CAAC,CAAC,CAAC;AACJ,MAAM,CAAC,iBAAiB,CAAC,qBAAqB,EAAE,KAAK,EAAE,GAAG,EAAE,EAAE,CAC5D,YAAY,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,SAAS,IAAI,EAAE,CAAC,CAC1D,CAAC;AAEF,MAAM,CAAC,iBAAiB,CAAC,0BAA0B,EAAE,KAAK,IAAI,EAAE,CAAC,CAAC;IAChE,SAAS,EAAE,MAAM,aAAa,EAAE;CACjC,CAAC,CAAC,CAAC;AACJ,MAAM,CAAC,iBAAiB,CAAC,yBAAyB,EAAE,KAAK,EAAE,GAAG,EAAE,EAAE,CAChE,YAAY,CAAC,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAC7B,CAAC;AAEF,MAAM,CAAC,iBAAiB,CAAC,wBAAwB,EAAE,KAAK,IAAI,EAAE,CAAC,CAAC;IAC9D,OAAO,EAAE,WAAW,EAAE;CACvB,CAAC,CAAC,CAAC;AACJ,MAAM,CAAC,iBAAiB,CAAC,sBAAsB,EAAE,KAAK,EAAE,GAAG,EAAE,EAAE,CAC7D,SAAS,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,SAAS,IAAI,EAAE,CAAC,CACvD,CAAC;AAEF,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;AAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;AAEhC,MAAM,CAAC,IAAI,CAAC,gBAAgB,EAAE;IAC5B,OAAO,EAAE,EAAE,OAAO,EAAE,cAAc,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC,MAAM,EAAE;CAChE,CAAC,CAAC"}

package/dist/learning/format.d.ts

@@ -0,0 +1,29 @@
+import type { LearningEntry } from "./store.js";
+export interface FormatLearningsOptions {
+    /**
+     * Filter to learnings whose `scope` glob matches at least one of these
+     * paths. Used to narrow per-PR injection to learnings relevant to the
+     * files actually changed. When empty / undefined, all entries pass.
+     */
+    changedFiles?: string[];
+    /**
+     * Cap the rendered list. Default 50. Tail-most-recent. Hard cap of 200
+     * to prevent prompt bloat.
+     */
+    limit?: number;
+    /**
+     * Heading level for the section. Default `## Past team decisions`. Adjust
+     * when injecting into a prompt that already nests under a higher heading.
+     */
+    heading?: string;
+}
+/**
+ * Render a slice of learning entries as a markdown block ready to inject into
+ * an agent or consolidator prompt. Pure function. The block is intentionally
+ * compact — each entry is one numbered line so the LLM can scan quickly and
+ * reference back ("see decision #4 — already declined this CSRF flag").
+ *
+ * Returns `''` when no entries qualify after filtering. Callers should check
+ * the empty case before injecting (avoid empty headers in prompts).
+ */
+export declare function formatLearningsForPrompt(entries: LearningEntry[], options?: FormatLearningsOptions): string;

package/dist/learning/format.js

@@ -0,0 +1,55 @@
+import { matchesGlob } from "../config/squad-yaml.js";
+const HARD_LIMIT = 200;
+const DEFAULT_LIMIT = 50;
+const DEFAULT_HEADING = "## Past team decisions";
+/**
+ * Render a slice of learning entries as a markdown block ready to inject into
+ * an agent or consolidator prompt. Pure function. The block is intentionally
+ * compact — each entry is one numbered line so the LLM can scan quickly and
+ * reference back ("see decision #4 — already declined this CSRF flag").
+ *
+ * Returns `''` when no entries qualify after filtering. Callers should check
+ * the empty case before injecting (avoid empty headers in prompts).
+ */
+export function formatLearningsForPrompt(entries, options = {}) {
+    const limit = Math.min(options.limit ?? DEFAULT_LIMIT, HARD_LIMIT);
+    const heading = options.heading ?? DEFAULT_HEADING;
+    // Filter by scope glob match against changedFiles. An entry without a scope
+    // is repo-wide and always passes. An entry WITH a scope passes if any
+    // changed file matches the scope glob.
+    let relevant = entries;
+    if (options.changedFiles && options.changedFiles.length > 0) {
+        relevant = entries.filter((e) => {
+            if (!e.scope)
+                return true;
+            return options.changedFiles.some((p) => matchesGlob(e.scope, p));
+        });
+    }
+    // Tail-N most recent. Append order = chronological, so slice from end.
+    const tail = relevant.slice(-limit);
+    if (tail.length === 0)
+        return "";
+    // Render most-recent-first to bias the LLM's attention.
+    const ordered = [...tail].reverse();
+    const lines = [];
+    lines.push(heading);
+    lines.push("");
+    lines.push(`Recent decisions on similar findings (${ordered.length} of ${entries.length} total, most recent first). When evaluating a new finding that matches a past **rejected** decision (similar agent + similar finding text + matching scope), suppress or downgrade severity. When a finding contradicts a past **accepted** decision, flag the contradiction explicitly.`);
+    lines.push("");
+    ordered.forEach((e, i) => {
+        const ref = e.pr
+            ? `PR #${e.pr}`
+            : e.branch
+                ? `branch ${e.branch}`
+                : e.ts.slice(0, 10);
+        const verdict = e.decision === "reject" ? "REJECTED" : "ACCEPTED";
+        const sev = e.severity ? ` [${e.severity}]` : "";
+        const scope = e.scope ? ` (scope: \`${e.scope}\`)` : "";
+        lines.push(`${i + 1}. **${verdict}** at ${ref}${scope} — ${e.agent}${sev}: "${e.finding}"`);
+        if (e.reason) {
+            lines.push(`   Reason: ${e.reason}`);
+        }
+    });
+    return lines.join("\n") + "\n";
+}
+//# sourceMappingURL=format.js.map

package/dist/learning/format.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"format.js","sourceRoot":"","sources":["../../src/learning/format.ts"],"names":[],"mappings":"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"}

package/dist/learning/store.d.ts

@@ -0,0 +1,102 @@
+import { z } from "zod";
+import { type AgentName } from "../config/ownership-matrix.js";
+/**
+ * One row in `.squad/learnings.jsonl`. Append-only — entries are never
+ * rewritten, just superseded by later ones with the same (agent, finding,
+ * scope) tuple. Keep the schema small; rich query semantics are out of
+ * scope for V1 (the consolidator does free-text recall, not vector search).
+ */
+declare const learningEntrySchema: z.ZodObject<{
+    /** ISO 8601 timestamp. Required for ordering. */
+    ts: z.ZodString;
+    /** PR number when recorded from `/squad-review #N`; optional otherwise. */
+    pr: z.ZodOptional<z.ZodNumber>;
+    /** Branch name when recorded from a local review (no PR ref). */
+    branch: z.ZodOptional<z.ZodString>;
+    /** Which agent's finding this decision concerns. */
+    agent: z.ZodEnum<[AgentName, ...AgentName[]]>;
+    /** Severity at the time of the decision (Blocker / Major / Minor / Suggestion). */
+    severity: z.ZodOptional<z.ZodEnum<["Blocker", "Major", "Minor", "Suggestion"]>>;
+    /** Short title of the finding — same shape as Finding.title in consolidate. */
+    finding: z.ZodString;
+    /** Whether the team accepted or rejected this finding. */
+    decision: z.ZodEnum<["accept", "reject"]>;
+    /** Free-form rationale. Surfaces in the consolidator prompt. */
+    reason: z.ZodOptional<z.ZodString>;
+    /**
+     * Glob-ish path scope this decision applies to (e.g. "src/auth/**"). When
+     * absent, the decision applies repo-wide. Used by the formatter to filter
+     * learnings down to those relevant to the current diff.
+     */
+    scope: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    agent: AgentName;
+    ts: string;
+    finding: string;
+    decision: "accept" | "reject";
+    reason?: string | undefined;
+    severity?: "Blocker" | "Major" | "Minor" | "Suggestion" | undefined;
+    pr?: number | undefined;
+    branch?: string | undefined;
+    scope?: string | undefined;
+}, {
+    agent: AgentName;
+    ts: string;
+    finding: string;
+    decision: "accept" | "reject";
+    reason?: string | undefined;
+    severity?: "Blocker" | "Major" | "Minor" | "Suggestion" | undefined;
+    pr?: number | undefined;
+    branch?: string | undefined;
+    scope?: string | undefined;
+}>;
+export type LearningEntry = z.infer<typeof learningEntrySchema>;
+/**
+ * Default location for the JSONL file, relative to workspace_root. Repo-versioned
+ * by convention; the team commits `.squad/learnings.jsonl` along with the code so
+ * decisions are auditable in PR diffs.
+ */
+export declare const DEFAULT_LEARNING_PATH = ".squad/learnings.jsonl";
+/** Test-only: clear the per-process cache. Production code MUST NOT call this. */
+export declare function __resetLearningStoreCacheForTests(): void;
+/**
+ * Read all learnings from the JSONL file. Returns [] if the file does not exist
+ * (a fresh repo with no decisions recorded is the common case). Throws on
+ * parse failure of any individual line — callers may want to soft-fail, but
+ * silent corruption is worse than loud rejection.
+ */
+export declare function readLearnings(workspaceRoot: string, options?: {
+    configuredPath?: string;
+}): Promise<LearningEntry[]>;
+/**
+ * Append a new learning entry to the JSONL file. Creates the directory and
+ * file if needed. Atomic at the append level (single fs.appendFile call —
+ * Node serialises this on POSIX); concurrent appenders may interleave entries
+ * but never corrupt them line-wise.
+ *
+ * Stamps the timestamp here if the caller did not supply one — gives a single
+ * source of clock truth and prevents stale ts in CLI invocations.
+ */
+export declare function appendLearning(workspaceRoot: string, entry: Omit<LearningEntry, "ts"> & {
+    ts?: string;
+}, options?: {
+    configuredPath?: string;
+}): Promise<{
+    filePath: string;
+    entry: LearningEntry;
+}>;
+/**
+ * Filter helper: pick the most recent N entries, optionally narrowed by
+ * agent. Used by the formatter to inject a small, relevant slice into the
+ * agent / consolidator prompt.
+ *
+ * Sort: input is in append order (oldest first). We slice the tail. The
+ * filter happens BEFORE the slice — `recentForAgent('senior-dba', 50)`
+ * returns the last 50 DBA decisions, not the last 50 decisions overall
+ * filtered to DBA (which would often return zero on diverse repos).
+ */
+export declare function tailRecent(entries: LearningEntry[], limit: number, options?: {
+    agent?: AgentName;
+    decision?: "accept" | "reject";
+}): LearningEntry[];
+export {};

package/dist/learning/store.js

@@ -0,0 +1,169 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { z } from "zod";
+import { AGENT_NAMES_TUPLE, } from "../config/ownership-matrix.js";
+import { SquadError } from "../errors.js";
+import { logger } from "../observability/logger.js";
+/**
+ * One row in `.squad/learnings.jsonl`. Append-only — entries are never
+ * rewritten, just superseded by later ones with the same (agent, finding,
+ * scope) tuple. Keep the schema small; rich query semantics are out of
+ * scope for V1 (the consolidator does free-text recall, not vector search).
+ */
+const learningEntrySchema = z.object({
+    /** ISO 8601 timestamp. Required for ordering. */
+    ts: z.string().min(1).max(40),
+    /** PR number when recorded from `/squad-review #N`; optional otherwise. */
+    pr: z.number().int().positive().optional(),
+    /** Branch name when recorded from a local review (no PR ref). */
+    branch: z.string().min(1).max(255).optional(),
+    /** Which agent's finding this decision concerns. */
+    agent: z.enum(AGENT_NAMES_TUPLE),
+    /** Severity at the time of the decision (Blocker / Major / Minor / Suggestion). */
+    severity: z.enum(["Blocker", "Major", "Minor", "Suggestion"]).optional(),
+    /** Short title of the finding — same shape as Finding.title in consolidate. */
+    finding: z.string().min(1).max(2048),
+    /** Whether the team accepted or rejected this finding. */
+    decision: z.enum(["accept", "reject"]),
+    /** Free-form rationale. Surfaces in the consolidator prompt. */
+    reason: z.string().max(4096).optional(),
+    /**
+     * Glob-ish path scope this decision applies to (e.g. "src/auth/**"). When
+     * absent, the decision applies repo-wide. Used by the formatter to filter
+     * learnings down to those relevant to the current diff.
+     */
+    scope: z.string().min(1).max(512).optional(),
+});
+/**
+ * Default location for the JSONL file, relative to workspace_root. Repo-versioned
+ * by convention; the team commits `.squad/learnings.jsonl` along with the code so
+ * decisions are auditable in PR diffs.
+ */
+export const DEFAULT_LEARNING_PATH = ".squad/learnings.jsonl";
+const cache = new Map();
+/** Test-only: clear the per-process cache. Production code MUST NOT call this. */
+export function __resetLearningStoreCacheForTests() {
+    cache.clear();
+}
+function resolveLearningFile(workspaceRoot, configuredPath) {
+    const rel = configuredPath ?? DEFAULT_LEARNING_PATH;
+    return path.resolve(workspaceRoot, rel);
+}
+/**
+ * Read all learnings from the JSONL file. Returns [] if the file does not exist
+ * (a fresh repo with no decisions recorded is the common case). Throws on
+ * parse failure of any individual line — callers may want to soft-fail, but
+ * silent corruption is worse than loud rejection.
+ */
+export async function readLearnings(workspaceRoot, options = {}) {
+    const filePath = resolveLearningFile(workspaceRoot, options.configuredPath);
+    const absRoot = path.resolve(workspaceRoot);
+    let stat;
+    try {
+        stat = await fs.stat(filePath);
+    }
+    catch {
+        // No file — first run, no learnings yet.
+        return [];
+    }
+    if (!stat.isFile()) {
+        return [];
+    }
+    const cached = cache.get(absRoot);
+    if (cached &&
+        cached.filePath === filePath &&
+        cached.mtimeMs === stat.mtimeMs) {
+        return cached.entries;
+    }
+    let raw;
+    try {
+        raw = await fs.readFile(filePath, "utf8");
+    }
+    catch (err) {
+        throw new SquadError("CONFIG_READ_FAILED", `failed to read learnings file ${filePath}: ${err.message}`, { source: filePath });
+    }
+    const lines = raw.split(/\r?\n/);
+    const entries = [];
+    let lineNo = 0;
+    for (const line of lines) {
+        lineNo++;
+        const trimmed = line.trim();
+        if (trimmed === "")
+            continue; // skip blank lines (trailing newline, spacing)
+        let parsed;
+        try {
+            parsed = JSON.parse(trimmed);
+        }
+        catch (err) {
+            throw new SquadError("INVALID_INPUT", `${filePath}:${lineNo}: invalid JSON: ${err.message}`, { source: filePath, line: lineNo });
+        }
+        const validated = learningEntrySchema.safeParse(parsed);
+        if (!validated.success) {
+            throw new SquadError("INVALID_INPUT", `${filePath}:${lineNo}: schema violation: ${validated.error.message}`, {
+                source: filePath,
+                line: lineNo,
+                issues: validated.error.issues.length,
+            });
+        }
+        entries.push(validated.data);
+    }
+    cache.set(absRoot, { mtimeMs: stat.mtimeMs, filePath, entries });
+    return entries;
+}
+/**
+ * Append a new learning entry to the JSONL file. Creates the directory and
+ * file if needed. Atomic at the append level (single fs.appendFile call —
+ * Node serialises this on POSIX); concurrent appenders may interleave entries
+ * but never corrupt them line-wise.
+ *
+ * Stamps the timestamp here if the caller did not supply one — gives a single
+ * source of clock truth and prevents stale ts in CLI invocations.
+ */
+export async function appendLearning(workspaceRoot, entry, options = {}) {
+    const ts = entry.ts ?? new Date().toISOString();
+    const candidate = { ...entry, ts };
+    const validated = learningEntrySchema.safeParse(candidate);
+    if (!validated.success) {
+        throw new SquadError("INVALID_INPUT", `learning entry schema violation: ${validated.error.message}`, { issues: validated.error.issues.length });
+    }
+    const filePath = resolveLearningFile(workspaceRoot, options.configuredPath);
+    const dir = path.dirname(filePath);
+    await fs.mkdir(dir, { recursive: true });
+    // One JSON object per line, no pretty-print — keeps the file grep-friendly
+    // and minimises diff churn when entries get re-ordered (which they don't,
+    // but defensive).
+    const line = JSON.stringify(validated.data) + "\n";
+    await fs.appendFile(filePath, line, "utf8");
+    // Invalidate cache so next readLearnings reflects the append.
+    const absRoot = path.resolve(workspaceRoot);
+    cache.delete(absRoot);
+    logger.info("learning appended", {
+        details: {
+            file: filePath,
+            agent: validated.data.agent,
+            decision: validated.data.decision,
+        },
+    });
+    return { filePath, entry: validated.data };
+}
+/**
+ * Filter helper: pick the most recent N entries, optionally narrowed by
+ * agent. Used by the formatter to inject a small, relevant slice into the
+ * agent / consolidator prompt.
+ *
+ * Sort: input is in append order (oldest first). We slice the tail. The
+ * filter happens BEFORE the slice — `recentForAgent('senior-dba', 50)`
+ * returns the last 50 DBA decisions, not the last 50 decisions overall
+ * filtered to DBA (which would often return zero on diverse repos).
+ */
+export function tailRecent(entries, limit, options = {}) {
+    let filtered = entries;
+    if (options.agent) {
+        filtered = filtered.filter((e) => e.agent === options.agent);
+    }
+    if (options.decision) {
+        filtered = filtered.filter((e) => e.decision === options.decision);
+    }
+    return filtered.slice(-limit);
+}
+//# sourceMappingURL=store.js.map

package/dist/learning/store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.js","sourceRoot":"","sources":["../../src/learning/store.ts"],"names":[],"mappings":"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"}

package/dist/resources/agent-loader.d.ts

@@ -1,4 +1,4 @@
-import { type AgentName } from '../config/ownership-matrix.js';
+import { type AgentName } from "../config/ownership-matrix.js";
 export declare const SHARED_FILES: string[];
 /**
  * Returns the configured override directory and whether it was set explicitly
@@ -9,6 +9,13 @@ export declare function getLocalDir(): {
     explicit: boolean;
 };
 export declare function getEmbeddedDir(): string;
+/**
+ * Path to the shared docs directory at repo root (`<repo>/shared/`). Lives
+ * outside `agents/` so the Claude Code plugin manifest's agent validator does
+ * not see non-agent files. Mirrors to `<localOverrideDir>/shared/` when the
+ * user runs init_local_config.
+ */
+export declare function getEmbeddedSharedDir(): string;
 /**
  * Test-only: reset all module-level caches and one-shot flags.
  * Production code MUST NOT call this.