@gempack/squad-mcp 0.5.0 → 0.6.0

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.0";
 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

package/dist/resources/agent-loader.js

@@ -1,31 +1,35 @@
-import { promises as fs } from 'node:fs';
-import path from 'node:path';
-import os from 'node:os';
-import { fileURLToPath } from 'node:url';
-import { AGENTS } from '../config/ownership-matrix.js';
-import { SquadError } from '../errors.js';
-import { logger } from '../observability/logger.js';
-import { validateOverrideDir, validateOverrideFile, rejectionToError, getAllowlistSize, __resetOverrideAllowlistCache, } from '../util/override-allowlist.js';
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import { fileURLToPath } from "node:url";
+import { AGENTS } from "../config/ownership-matrix.js";
+import { SquadError } from "../errors.js";
+import { logger } from "../observability/logger.js";
+import { validateOverrideDir, validateOverrideFile, rejectionToError, getAllowlistSize, __resetOverrideAllowlistCache, } from "../util/override-allowlist.js";
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const AGENT_FILE_MAP = {
-    po: 'PO.md',
-    'tech-lead-planner': 'TechLead-Planner.md',
-    'tech-lead-consolidator': 'TechLead-Consolidator.md',
-    'senior-architect': 'Senior-Architect.md',
-    'senior-dba': 'Senior-DBA.md',
-    'senior-developer': 'Senior-Developer.md',
-    'senior-dev-reviewer': 'Senior-Dev-Reviewer.md',
-    'senior-dev-security': 'Senior-Dev-Security.md',
-    'senior-qa': 'Senior-QA.md',
+    'product-owner': "product-owner.md",
+    "tech-lead-planner": "tech-lead-planner.md",
+    "tech-lead-consolidator": "tech-lead-consolidator.md",
+    "senior-architect": "senior-architect.md",
+    "senior-dba": "senior-dba.md",
+    "senior-developer": "senior-developer.md",
+    "senior-dev-reviewer": "senior-dev-reviewer.md",
+    "senior-dev-security": "senior-dev-security.md",
+    "senior-qa": "senior-qa.md",
 };
-export const SHARED_FILES = ['_Severity-and-Ownership.md', 'Skill-Squad-Dev.md', 'Skill-Squad-Review.md'];
+export const SHARED_FILES = [
+    "_shared/_Severity-and-Ownership.md",
+    "_shared/Skill-Squad-Dev.md",
+    "_shared/Skill-Squad-Review.md",
+];
 function defaultLocalDir() {
-    if (process.platform === 'win32') {
-        const appdata = process.env.APPDATA ?? path.join(os.homedir(), 'AppData', 'Roaming');
-        return path.join(appdata, 'squad-mcp', 'agents');
+    if (process.platform === "win32") {
+        const appdata = process.env.APPDATA ?? path.join(os.homedir(), "AppData", "Roaming");
+        return path.join(appdata, "squad-mcp", "agents");
     }
-    const xdg = process.env.XDG_CONFIG_HOME ?? path.join(os.homedir(), '.config');
-    return path.join(xdg, 'squad-mcp', 'agents');
+    const xdg = process.env.XDG_CONFIG_HOME ?? path.join(os.homedir(), ".config");
+    return path.join(xdg, "squad-mcp", "agents");
 }
 /**
  * Returns the configured override directory and whether it was set explicitly
@@ -33,13 +37,13 @@ function defaultLocalDir() {
  */
 export function getLocalDir() {
     const env = process.env.SQUAD_AGENTS_DIR;
-    if (env !== undefined && env !== '') {
+    if (env !== undefined && env !== "") {
         return { rawDir: env, explicit: true };
     }
     return { rawDir: defaultLocalDir(), explicit: false };
 }
 export function getEmbeddedDir() {
-    return path.resolve(__dirname, '..', '..', 'agents');
+    return path.resolve(__dirname, "..", "..", "agents");
 }
 async function exists(p) {
     try {
@@ -86,7 +90,7 @@ export function __resetAgentLoaderForTests() {
  */
 async function createSecureDir(dir) {
     await fs.mkdir(dir, { recursive: true, mode: 0o700 });
-    if (process.platform !== 'win32') {
+    if (process.platform !== "win32") {
         await fs.chmod(dir, 0o700);
     }
 }
@@ -98,7 +102,7 @@ async function createSecureDir(dir) {
  */
 async function copyFileSecure(src, dst) {
     await fs.copyFile(src, dst);
-    if (process.platform !== 'win32') {
+    if (process.platform !== "win32") {
         await fs.chmod(dst, 0o600);
     }
 }
@@ -111,7 +115,7 @@ async function copyFileSecure(src, dst) {
  * not produce duplicate warnings.
  */
 async function checkOverrideDirPerms(dir) {
-    if (process.platform === 'win32')
+    if (process.platform === "win32")
         return;
     if (permWarnEmitted)
         return;
@@ -119,10 +123,10 @@ async function checkOverrideDirPerms(dir) {
     try {
         const s = await fs.stat(dir);
         if ((s.mode & 0o002) !== 0) {
-            logger.warn('override directory is world-writable', {
+            logger.warn("override directory is world-writable", {
                 details: {
                     configured_path: dir,
-                    mode: '0o' + (s.mode & 0o777).toString(8),
+                    mode: "0o" + (s.mode & 0o777).toString(8),
                     recommendation: `chmod 700 ${dir}`,
                 },
             });
@@ -137,7 +141,7 @@ async function ensureEmbeddedDir() {
         return;
     const dir = getEmbeddedDir();
     if (!(await exists(dir))) {
-        throw new SquadError('AGENT_DIR_MISSING', `embedded agents directory missing at ${dir}`);
+        throw new SquadError("AGENT_DIR_MISSING", `embedded agents directory missing at ${dir}`);
     }
     embeddedAsserted = true;
 }
@@ -164,7 +168,7 @@ async function resolveOverride() {
     if (!(await isDirectory(rawDir))) {
         if (explicit && !overrideMissingWarnEmitted) {
             overrideMissingWarnEmitted = true;
-            logger.warn('SQUAD_AGENTS_DIR set but directory not found; falling back to embedded defaults', {
+            logger.warn("SQUAD_AGENTS_DIR set but directory not found; falling back to embedded defaults", {
                 details: { configured_path: rawDir },
             });
         }
@@ -176,14 +180,14 @@ async function resolveOverride() {
         if (explicit) {
             const size = await getAllowlistSize();
             const err = rejectionToError(result, size);
-            logger.warn('SQUAD_AGENTS_DIR rejected', {
+            logger.warn("SQUAD_AGENTS_DIR rejected", {
                 error_code: err.code,
                 details: { reason: result.reason, configured_path: rawDir },
             });
             throw err;
         }
         // Platform-default rejection: log warn, fall back silently. Rare.
-        logger.warn('platform default agent directory failed validation', {
+        logger.warn("platform default agent directory failed validation", {
             details: { reason: result.reason, configured_path: rawDir },
         });
         overrideValidationCache.set(rawDir, null);
@@ -195,13 +199,15 @@ async function resolveOverride() {
             resolved_path: result.resolvedPath,
             allowlist_match: result.allowlistMatch,
             has_unsafe_override: result.unsafeOverride,
-            source: explicit ? 'env' : 'platform_default',
+            source: explicit ? "env" : "platform_default",
         };
         if (result.unsafeOverride) {
-            logger.warn('agent override active (unsafe escape hatch)', { details: fields });
+            logger.warn("agent override active (unsafe escape hatch)", {
+                details: fields,
+            });
         }
         else {
-            logger.info('agent override active', { details: fields });
+            logger.info("agent override active", { details: fields });
         }
     }
     await checkOverrideDirPerms(result.resolvedPath);
@@ -214,7 +220,7 @@ async function resolveOverride() {
  */
 function assertKnownAgent(name) {
     if (!Object.prototype.hasOwnProperty.call(AGENT_FILE_MAP, name)) {
-        throw new SquadError('UNKNOWN_AGENT', `unknown agent: ${name}`, { name });
+        throw new SquadError("UNKNOWN_AGENT", `unknown agent: ${name}`, { name });
     }
 }
 export async function resolveAgentFile(name) {
@@ -233,7 +239,9 @@ export async function resolveAgentFile(name) {
 export async function resolveSharedFile(file) {
     await ensureEmbeddedDir();
     if (!SHARED_FILES.includes(file)) {
-        throw new SquadError('INVALID_INPUT', `shared file not allowed: ${file}`, { file });
+        throw new SquadError("INVALID_INPUT", `shared file not allowed: ${file}`, {
+            file,
+        });
     }
     const override = await resolveOverride();
     if (override) {
@@ -245,7 +253,7 @@ export async function resolveSharedFile(file) {
 }
 export async function readAgentDefinition(name) {
     const filePath = await resolveAgentFile(name);
-    return fs.readFile(filePath, 'utf8');
+    return fs.readFile(filePath, "utf8");
 }
 export async function listAvailableAgents() {
     // Trigger validation so misconfigured overrides surface here too.
@@ -282,6 +290,11 @@ export async function initLocalConfig(force = false) {
             skipped.push(file);
             continue;
         }
+        // Shared docs live under _shared/; ensure the parent dir exists before copyFile.
+        const parent = path.dirname(dst);
+        if (parent !== rawDir) {
+            await createSecureDir(parent);
+        }
         const src = path.join(getEmbeddedDir(), file);
         await copyFileSecure(src, dst);
         created.push(file);