agent-relay-server 0.57.2 → 0.59.0

package/src/mcp-project-tools.ts

@@ -0,0 +1,352 @@
+import {
+  addEdge,
+  addProjectRoot,
+  edgesFor,
+  ensureProject,
+  getAgent,
+  getProject,
+  getProjectEntry,
+  listProjects,
+  promoteBlackboardEntry,
+  removeEdge,
+  resolveProject,
+  resolveProjectEntries,
+  resolveProjectForCwd,
+  retractProjectEntry,
+  rootsForProject,
+  searchProjectEntries,
+  ValidationError,
+  writeProjectEntry,
+} from "./db";
+import { McpNotFoundError } from "./mcp-errors";
+import { ingestClaudeMd } from "./project-ingest";
+import { authContextFromMcp, type AuthContext } from "./services/auth-context";
+import { cleanString, cleanStringArray, optionalEnum } from "./validation";
+import { PROJECT_EDGE_KINDS, PROJECT_ENTRY_KINDS, PROJECT_ENTRY_SOURCES, type ProjectEdgeKind, type ProjectEntryKind, type ProjectEntrySource } from "./types";
+
+// MCP tools for the durable Projects knowledge scope (#405). Mirrors
+// src/mcp-blackboard-tools.ts: same cleanString/cleanStringArray validation and
+// scope-gating shape. Unlike the blackboard (purely caller-team-scoped), a project
+// is durable and cross-cutting and must be addressable: entry verbs take an OPTIONAL
+// `project` ref (id or slug) and fall back to callerProject(auth) — the project
+// resolved from the caller's spawn cwd. That fallback is the blackboard parallel.
+
+export const PROJECT_TOOLS = [
+  {
+    name: "relay_project_list",
+    description: "List the durable projects (the cross-repo knowledge scopes).",
+    requiredScopes: ["project:read"],
+    inputSchema: {
+      type: "object",
+      properties: { includeArchived: { type: "boolean" } },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "relay_project_get",
+    description: "Fetch one project and its registered roots. Defaults to the caller's resolved project (from its spawn cwd) when `project` is omitted.",
+    requiredScopes: ["project:read"],
+    inputSchema: {
+      type: "object",
+      properties: { project: { type: "string", description: "Project id or slug; defaults to the caller's project." } },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "relay_project_add_root",
+    description: "Create-or-update a project by slug and register a repo root path. The create-on-first-use entry point for a new project.",
+    requiredScopes: ["project:write"],
+    inputSchema: {
+      type: "object",
+      properties: {
+        slug: { type: "string" },
+        rootPath: { type: "string" },
+        title: { type: "string" },
+        description: { type: "string" },
+        tenantId: { type: "string" },
+      },
+      required: ["slug", "rootPath"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "relay_project_write_entry",
+    description: "Create a project-scoped entry (rule/fact/decision/memory). Targets `project` if given, else the caller's resolved project.",
+    requiredScopes: ["project:write"],
+    inputSchema: {
+      type: "object",
+      properties: {
+        project: { type: "string", description: "Project id or slug; defaults to the caller's project." },
+        kind: { type: "string", enum: PROJECT_ENTRY_KINDS },
+        title: { type: "string" },
+        body: { type: "string" },
+        tags: { type: "array", items: { type: "string" } },
+        supersedes: { type: "string" },
+        source: { type: "string", enum: PROJECT_ENTRY_SOURCES },
+        originRef: { type: "string" },
+      },
+      required: ["kind", "title"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "relay_project_read",
+    description: "Read a project's active entries, optionally filtered by kind. Includes entries inherited from transitive `contains` ancestors (each tagged `inherited:true`) unless `includeInherited:false`. `depends_on` targets are never folded in — read them explicitly via their own `project` ref. Targets `project` if given, else the caller's resolved project.",
+    requiredScopes: ["project:read"],
+    inputSchema: {
+      type: "object",
+      properties: {
+        project: { type: "string" },
+        kind: { type: "string", enum: PROJECT_ENTRY_KINDS },
+        includeInactive: { type: "boolean" },
+        includeInherited: { type: "boolean", description: "Default true: merge in contains-ancestor entries. Set false for only this project's own." },
+      },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "relay_project_search",
+    description: "Search a project's active entries by title, body, or tags. Targets `project` if given, else the caller's resolved project.",
+    requiredScopes: ["project:read"],
+    inputSchema: {
+      type: "object",
+      properties: {
+        project: { type: "string" },
+        query: { type: "string" },
+        kind: { type: "string", enum: PROJECT_ENTRY_KINDS },
+      },
+      required: ["query"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "relay_project_retract",
+    description: "Retract a project entry without deleting its ledger row. Targets `project` if given, else the caller's resolved project.",
+    requiredScopes: ["project:write"],
+    inputSchema: {
+      type: "object",
+      properties: {
+        project: { type: "string" },
+        id: { type: "string" },
+      },
+      required: ["id"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "relay_project_add_edge",
+    description: "Add a composition-graph edge between two projects. `contains` (umbrella→sub-project) INHERITS — the sub-project's reads pull in the umbrella's entries. `depends_on` is reference-only and never inherits. Cycles are rejected. `from`/`to` are project ids or slugs.",
+    requiredScopes: ["project:write"],
+    inputSchema: {
+      type: "object",
+      properties: {
+        from: { type: "string", description: "Source project id or slug (the umbrella for `contains`, the consumer for `depends_on`)." },
+        to: { type: "string", description: "Target project id or slug (the contained sub-project, or the dependency)." },
+        kind: { type: "string", enum: PROJECT_EDGE_KINDS },
+      },
+      required: ["from", "to", "kind"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "relay_project_remove_edge",
+    description: "Remove a composition-graph edge between two projects. `from`/`to` are project ids or slugs.",
+    requiredScopes: ["project:write"],
+    inputSchema: {
+      type: "object",
+      properties: {
+        from: { type: "string" },
+        to: { type: "string" },
+        kind: { type: "string", enum: PROJECT_EDGE_KINDS },
+      },
+      required: ["from", "to", "kind"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "relay_project_promote_entry",
+    description: "Promote an active blackboard finding (`bb_…`) into durable project knowledge. Copies its content as a `promoted` project entry whose `origin_ref` back-references the blackboard id (kinds: decision→decision, fact→fact, ruled_out→rule). Explicit only — nothing is auto-promoted. Re-promoting the same finding supersedes the prior copy rather than duplicating it. Targets `project` if given, else the caller's resolved project.",
+    requiredScopes: ["project:write"],
+    inputSchema: {
+      type: "object",
+      properties: {
+        blackboardEntryId: { type: "string", description: "The bb_… blackboard entry to promote." },
+        project: { type: "string", description: "Project id or slug; defaults to the caller's project." },
+      },
+      required: ["blackboardEntryId"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "relay_project_ingest_claudemd",
+    description: "Ingest CLAUDE.md from each registered root of a project into project_entries (source:'ingested'), splitting by heading into one entry per section. Idempotent: re-running supersedes prior ingested entries from the same file/section, retracts sections that vanished, and never touches manual/promoted entries. Targets `project` if given, else the caller's resolved project.",
+    requiredScopes: ["project:write"],
+    inputSchema: {
+      type: "object",
+      properties: {
+        project: { type: "string", description: "Project id or slug; defaults to the caller's project." },
+      },
+      additionalProperties: false,
+    },
+  },
+] satisfies Array<{ name: string; description: string; requiredScopes: string[]; inputSchema: Record<string, unknown> }>;
+
+type McpAuthLike = Parameters<typeof authContextFromMcp>[0];
+
+/** The project resolved from the caller's identity: the projectId stamped on the
+ * token at spawn (cwd→root binding), else a live resolution from the caller agent's
+ * cwd. Analogous to callerTeam(auth); returns undefined gracefully when the caller
+ * is in no registered root. */
+function callerProjectId(ctx: AuthContext): string | undefined {
+  if (ctx.constraints?.projectId) return ctx.constraints.projectId;
+  if (!ctx.callerAgentId) return undefined;
+  const agent = getAgent(ctx.callerAgentId);
+  const cwd = typeof agent?.meta?.cwd === "string" ? agent.meta.cwd : undefined;
+  const project = cwd ? resolveProjectForCwd(cwd) : null;
+  return project?.id;
+}
+
+/** Resolve the project an entry verb operates on: the explicit `project` ref (id or
+ * slug) when given, else the caller's resolved project. Throws when neither yields one. */
+function targetProjectId(ctx: AuthContext, explicit: string | undefined): string {
+  if (explicit) {
+    const project = resolveProject(explicit);
+    if (!project) throw new McpNotFoundError("project not found");
+    return project.id;
+  }
+  const id = callerProjectId(ctx);
+  if (!id) throw new ValidationError("no project: pass `project`, or spawn inside a registered project root");
+  return id;
+}
+
+function authorId(ctx: AuthContext): string {
+  return ctx.callerAgentId ?? ctx.actor.id;
+}
+
+function cleanKind(value: unknown): ProjectEntryKind | undefined {
+  return optionalEnum(value, "kind", PROJECT_ENTRY_KINDS) as ProjectEntryKind | undefined;
+}
+
+function cleanEdgeKind(value: unknown): ProjectEdgeKind {
+  const kind = optionalEnum(value, "kind", PROJECT_EDGE_KINDS) as ProjectEdgeKind | undefined;
+  if (!kind) throw new ValidationError(`kind must be one of: ${PROJECT_EDGE_KINDS.join(", ")}`);
+  return kind;
+}
+
+/** Resolve an explicit project ref (id or slug) to its id, or throw not-found. The
+ * graph edges address projects directly, never via caller-cwd fallback. */
+function requireProjectId(ref: unknown, field: string): string {
+  const explicit = cleanString(ref, field, { required: true, max: 200 })!;
+  const project = resolveProject(explicit);
+  if (!project) throw new McpNotFoundError(`project not found: ${explicit}`);
+  return project.id;
+}
+
+function ensureSameProject(entryId: string, projectId: string): void {
+  const entry = getProjectEntry(entryId);
+  if (!entry) throw new McpNotFoundError("project entry not found");
+  if (entry.projectId !== projectId) throw new McpNotFoundError("project entry not found");
+}
+
+export function relayProjectTool(auth: McpAuthLike, name: string, args: Record<string, unknown>): Record<string, unknown> {
+  const ctx = authContextFromMcp(auth);
+
+  if (name === "relay_project_list") {
+    return { projects: listProjects({ includeArchived: args.includeArchived === true }) };
+  }
+
+  if (name === "relay_project_get") {
+    const explicit = cleanString(args.project, "project", { max: 200 });
+    const id = explicit
+      ? (resolveProject(explicit)?.id ?? (() => { throw new McpNotFoundError("project not found"); })())
+      : callerProjectId(ctx);
+    if (!id) throw new McpNotFoundError("project not found");
+    const project = getProject(id);
+    if (!project) throw new McpNotFoundError("project not found");
+    return { project, roots: rootsForProject(id), edges: edgesFor(id) };
+  }
+
+  if (name === "relay_project_add_root") {
+    const slug = cleanString(args.slug, "slug", { required: true, max: 200 })!;
+    const rootPath = cleanString(args.rootPath, "rootPath", { required: true, max: 4000 })!;
+    const project = ensureProject({
+      slug,
+      title: cleanString(args.title, "title", { max: 240 }),
+      description: cleanString(args.description, "description", { max: 16_000 }),
+      tenantId: cleanString(args.tenantId, "tenantId", { max: 200 }),
+    });
+    const roots = addProjectRoot(project.id, rootPath);
+    return { project, roots };
+  }
+
+  if (name === "relay_project_write_entry") {
+    const projectId = targetProjectId(ctx, cleanString(args.project, "project", { max: 200 }));
+    const kind = cleanKind(args.kind);
+    if (!kind) throw new ValidationError("kind required");
+    const supersedes = cleanString(args.supersedes, "supersedes", { max: 120 });
+    if (supersedes) ensureSameProject(supersedes, projectId);
+    return writeProjectEntry({
+      projectId,
+      authorId: authorId(ctx),
+      kind,
+      title: cleanString(args.title, "title", { required: true, max: 240 })!,
+      body: cleanString(args.body, "body", { max: 16_000 }),
+      tags: cleanStringArray(args.tags, "tags", { itemMax: 80, maxItems: 32 }),
+      supersedes,
+      source: optionalEnum(args.source, "source", PROJECT_ENTRY_SOURCES) as ProjectEntrySource | undefined,
+      originRef: cleanString(args.originRef, "originRef", { max: 200 }),
+    }) as unknown as Record<string, unknown>;
+  }
+
+  if (name === "relay_project_read") {
+    const projectId = targetProjectId(ctx, cleanString(args.project, "project", { max: 200 }));
+    return {
+      entries: resolveProjectEntries(projectId, {
+        kind: cleanKind(args.kind),
+        includeInactive: args.includeInactive === true,
+        includeInherited: args.includeInherited !== false,
+      }),
+    };
+  }
+
+  if (name === "relay_project_search") {
+    const projectId = targetProjectId(ctx, cleanString(args.project, "project", { max: 200 }));
+    return { entries: searchProjectEntries(projectId, cleanString(args.query, "query", { required: true, max: 240 })!, { kind: cleanKind(args.kind) }) };
+  }
+
+  if (name === "relay_project_retract") {
+    const projectId = targetProjectId(ctx, cleanString(args.project, "project", { max: 200 }));
+    const id = cleanString(args.id, "id", { required: true, max: 120 })!;
+    ensureSameProject(id, projectId);
+    const entry = retractProjectEntry(id);
+    if (!entry) throw new McpNotFoundError("project entry not found");
+    return entry as unknown as Record<string, unknown>;
+  }
+
+  if (name === "relay_project_add_edge") {
+    const from = requireProjectId(args.from, "from");
+    const to = requireProjectId(args.to, "to");
+    const edge = addEdge(from, to, cleanEdgeKind(args.kind));
+    return { edge: edge as unknown as Record<string, unknown> };
+  }
+
+  if (name === "relay_project_remove_edge") {
+    const from = requireProjectId(args.from, "from");
+    const to = requireProjectId(args.to, "to");
+    const removed = removeEdge(from, to, cleanEdgeKind(args.kind));
+    return { removed };
+  }
+
+  if (name === "relay_project_promote_entry") {
+    const projectId = targetProjectId(ctx, cleanString(args.project, "project", { max: 200 }));
+    const blackboardEntryId = cleanString(args.blackboardEntryId, "blackboardEntryId", { required: true, max: 120 })!;
+    return promoteBlackboardEntry({ blackboardEntryId, projectId }) as unknown as Record<string, unknown>;
+  }
+
+  if (name === "relay_project_ingest_claudemd") {
+    const projectId = targetProjectId(ctx, cleanString(args.project, "project", { max: 200 }));
+    return ingestClaudeMd(projectId, authorId(ctx)) as unknown as Record<string, unknown>;
+  }
+
+  throw new ValidationError(`unknown tool: ${name}`);
+}

package/src/mcp.ts

@@ -49,6 +49,8 @@ import { ServiceAuthError } from "./services/errors";
 import { PLAN_TOOLS, relayPlanTool } from "./mcp-plan-tools";
 import { TEAM_TOOLS, relayTeamTool } from "./mcp-team-tools";
 import { BLACKBOARD_TOOLS, relayBlackboardTool } from "./mcp-blackboard-tools";
+import { PROJECT_TOOLS, relayProjectTool } from "./mcp-project-tools";
+import { PROJECT_INSTRUCTION_POLICY_NAMES, parseProjectInstructions } from "./project-instructions";
 import { AGENT_ACTION_TOOL, relayAgentAction } from "./mcp-agent-action";
 import type { ActivityKind, AgentLifecycle, ArtifactKind, ArtifactSensitivity, AttachmentRef, Command, SendMessageInput, Message, SpawnApprovalMode, SpawnProvider, WorkspaceAutoMergePolicy, WorkspaceMergeStrategy, WorkspaceMode, WorkspaceRecord } from "./types";
 import { LAND_STRATEGIES, applyWorkspaceAction, waitForWorkspaceStatus, type WorkspaceAction } from "./workspace-actions";
@@ -309,6 +311,7 @@ const TOOLS: ToolDefinition[] = [
         prompt: { type: "string", description: "Initial task/message delivered to the agent on launch — spawn and hand it its first instruction in one call (no separate follow-up message needed)." },
         expectReply: { type: "boolean", description: "Require the worker to report back: it gets a pending reply obligation to you and CANNOT go idle until it delivers its result (which routes to your inbox and wakes you). Defaults true when you pass a prompt — set false for a true fire-and-forget worker that needn't report (e.g. one that only lands a branch)." },
         systemPromptAppend: { type: "string" },
+        projectInstructions: { type: "object", description: "#409 — project instruction projection (default OFF). When set, relay composes a knowledge preamble from the spawn cwd's resolved project (own + inherited entries) and prepends it to systemPromptAppend, instead of relying on host CLAUDE.md. `policy: \"all\"` includes ingested host content; `\"vanilla\"` excludes it (manual+promoted only). Omit to keep current behavior.", properties: { policy: { type: "string", enum: PROJECT_INSTRUCTION_POLICY_NAMES } }, additionalProperties: false },
         profile: { type: "string", description: "Agent profile name to apply (env, instructions, permissions, MCP/skills, spawn quota)." },
         tags: { type: "array", items: { type: "string" } },
         capabilities: { type: "array", items: { type: "string" } },
@@ -459,6 +462,7 @@ const TOOLS: ToolDefinition[] = [
   ...TEAM_TOOLS,
   ...PLAN_TOOLS,
   ...BLACKBOARD_TOOLS,
+  ...PROJECT_TOOLS,
 ];
 
 export async function postMcp(req: Request): Promise<Response> {
@@ -574,6 +578,7 @@ async function callTool(auth: McpAuthContext, params: unknown): Promise<Record<s
     else if (name.startsWith("relay_team_")) result = await relayTeamTool(auth, name, args);
     else if (name.startsWith("relay_plan_")) result = relayPlanTool(auth, name, args);
     else if (name.startsWith("relay_blackboard_")) result = relayBlackboardTool(auth, name, args);
+    else if (name.startsWith("relay_project_")) result = relayProjectTool(auth, name, args);
     else throw new ValidationError(`unknown tool: ${name}`);
 
     auditToolCall(auth, name, "ok", result);
@@ -871,6 +876,7 @@ async function relaySpawnAgent(auth: McpAuthContext, args: Record<string, unknow
     prompt: optionalString(args.prompt, "prompt", 16_000),
     expectReply: typeof args.expectReply === "boolean" ? args.expectReply : undefined,
     systemPromptAppend: optionalString(args.systemPromptAppend, "systemPromptAppend", 64_000),
+    projectInstructions: parseProjectInstructions(args.projectInstructions, (m) => new ValidationError(m)),
     tags: optionalStringArray(args.tags, "tags"),
     capabilities: optionalStringArray(args.capabilities, "capabilities"),
     providerArgs: optionalStringArray(args.providerArgs, "providerArgs"),

package/src/project-ingest.ts

@@ -0,0 +1,186 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { listProjectEntries, rootsForProject, retractProjectEntry, writeProjectEntry } from "./db";
+import type { ProjectEntry } from "./types";
+
+// CLAUDE.md ingest on-ramp (#407, part of epic #403). Makes git a *feeder* of
+// project knowledge: read CLAUDE.md from each registered root and project its
+// headings into project_entries with source:'ingested'. The parse is deliberately
+// dumb and predictable — split by heading, one entry per heading — not clever.
+//
+// IDEMPOTENT re-ingest is the core invariant: re-running reconciles against the
+// prior 'ingested' entries keyed on origin_ref (file path + section anchor) —
+// unchanged sections are left alone, changed sections supersede their prior entry,
+// and sections that vanished from the file are retracted. `manual` and `promoted`
+// entries are NEVER read or touched by ingest — only source:'ingested' is.
+
+const INGEST_FILENAME = "CLAUDE.md";
+
+export interface ParsedSection {
+  /** Heading text (the entry title). For pre-heading preamble content: "(preamble)". */
+  title: string;
+  /** Section body — lines under the heading up to the next heading, trimmed. May be "". */
+  body: string;
+  /** GitHub-style heading slug, deduped within the file. "" for the preamble section. */
+  anchor: string;
+}
+
+export interface IngestRootResult {
+  rootPath: string;
+  filePath: string;
+  found: boolean;
+  sections: number;
+}
+
+export interface IngestResult {
+  projectId: string;
+  created: number;
+  updated: number;
+  unchanged: number;
+  retracted: number;
+  roots: IngestRootResult[];
+}
+
+const HEADING_RE = /^(#{1,6})\s+(.+?)\s*#*\s*$/;
+
+/** GitHub-style heading slug: lowercase, spaces→hyphens, drop non-word/-/space. */
+function slugify(heading: string): string {
+  return heading
+    .trim()
+    .toLowerCase()
+    .replace(/[^\w\s-]/g, "")
+    .replace(/\s+/g, "-")
+    .replace(/-+/g, "-")
+    .replace(/^-|-$/g, "");
+}
+
+/** Split a CLAUDE.md document into sections by heading. One section per heading
+ * line (any level), body = the lines until the next heading. Content before the
+ * first heading becomes a "(preamble)" section only when it has real content.
+ * Anchors are deduped (`-1`, `-2`, …) so each section gets a stable, unique ref. */
+export function parseClaudeMdSections(content: string): ParsedSection[] {
+  const lines = content.split("\n");
+  const sections: ParsedSection[] = [];
+  const anchorCounts = new Map<string, number>();
+
+  let title: string | null = null; // null until the first heading; preamble accumulates meanwhile
+  let bodyLines: string[] = [];
+
+  const dedupeAnchor = (base: string): string => {
+    const slug = base || "section";
+    const seen = anchorCounts.get(slug) ?? 0;
+    anchorCounts.set(slug, seen + 1);
+    return seen === 0 ? slug : `${slug}-${seen}`;
+  };
+
+  const flush = () => {
+    const body = bodyLines.join("\n").trim();
+    if (title === null) {
+      // Preamble: emit only if it carries real content.
+      if (body) sections.push({ title: "(preamble)", body, anchor: "" });
+    } else {
+      sections.push({ title, body, anchor: dedupeAnchor(slugify(title)) });
+    }
+    bodyLines = [];
+  };
+
+  for (const raw of lines) {
+    const m = raw.match(HEADING_RE);
+    if (m) {
+      flush();
+      title = m[2]!.trim();
+    } else {
+      bodyLines.push(raw);
+    }
+  }
+  flush();
+
+  return sections;
+}
+
+/** The origin_ref for an ingested section: the absolute file path, plus the
+ * section anchor as a fragment when the section came from a heading. */
+function originRefFor(filePath: string, anchor: string): string {
+  return anchor ? `${filePath}#${anchor}` : filePath;
+}
+
+/** Ingest CLAUDE.md from every registered root of a project into project_entries
+ * (source:'ingested'). Idempotent — see the module header. Returns a summary of
+ * what changed. Reads files synchronously; missing CLAUDE.md in a root is skipped
+ * gracefully (found:false), it is not an error. */
+export function ingestClaudeMd(projectId: string, authorId: string): IngestResult {
+  // Index prior *ingested* entries by origin_ref (newest active wins). We only ever
+  // read source:'ingested' here — manual/promoted are invisible to ingest by design.
+  const byOrigin = new Map<string, ProjectEntry>();
+  for (const entry of listProjectEntries(projectId)) {
+    if (entry.source !== "ingested" || !entry.originRef) continue;
+    if (!byOrigin.has(entry.originRef)) byOrigin.set(entry.originRef, entry);
+  }
+
+  const seen = new Set<string>();
+  const roots: IngestRootResult[] = [];
+  let created = 0;
+  let updated = 0;
+  let unchanged = 0;
+
+  for (const root of rootsForProject(projectId)) {
+    const filePath = join(root.rootPath, INGEST_FILENAME);
+    let content: string;
+    try {
+      content = readFileSync(filePath, "utf8");
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code === "ENOENT") {
+        roots.push({ rootPath: root.rootPath, filePath, found: false, sections: 0 });
+        continue;
+      }
+      throw err;
+    }
+
+    const sections = parseClaudeMdSections(content);
+    for (const section of sections) {
+      const originRef = originRefFor(filePath, section.anchor);
+      seen.add(originRef);
+      const prior = byOrigin.get(originRef);
+      if (prior) {
+        if (prior.title === section.title && (prior.body ?? "") === section.body) {
+          unchanged++;
+          continue;
+        }
+        writeProjectEntry({
+          projectId,
+          authorId,
+          kind: "rule",
+          title: section.title,
+          body: section.body || undefined,
+          source: "ingested",
+          originRef,
+          supersedes: prior.id,
+        });
+        updated++;
+      } else {
+        writeProjectEntry({
+          projectId,
+          authorId,
+          kind: "rule",
+          title: section.title,
+          body: section.body || undefined,
+          source: "ingested",
+          originRef,
+        });
+        created++;
+      }
+    }
+    roots.push({ rootPath: root.rootPath, filePath, found: true, sections: sections.length });
+  }
+
+  // Retract ingested entries whose section disappeared from the file (or whose
+  // file is gone) — they were not re-seen this pass. Never touches manual/promoted.
+  let retracted = 0;
+  for (const [originRef, entry] of byOrigin) {
+    if (seen.has(originRef)) continue;
+    retractProjectEntry(entry.id);
+    retracted++;
+  }
+
+  return { projectId, created, updated, unchanged, retracted, roots };
+}