diff --git a/src/main/agent-runtime/artifact-projector.ts b/src/main/agent-runtime/artifact-projector.ts
index d328fc26..949392fb 100644
--- a/src/main/agent-runtime/artifact-projector.ts
+++ b/src/main/agent-runtime/artifact-projector.ts
@@ -1,3 +1,6 @@
+// TODO: decompose — M-followup. File is 637 lines and mixes fs-walk
+// baseline capture, git-diff projection, and work-product reconciliation.
+// Split into baseline / diff / projector modules in a future milestone.
 import { isAbsolute, relative, resolve } from "node:path";
 import { execFileSync } from "node:child_process";
 import { readdirSync, statSync } from "node:fs";
diff --git a/src/main/agent-runtime/runtime-bridge.ts b/src/main/agent-runtime/runtime-bridge.ts
index 45783416..db4c2c60 100644
--- a/src/main/agent-runtime/runtime-bridge.ts
+++ b/src/main/agent-runtime/runtime-bridge.ts
@@ -1,3 +1,7 @@
+// TODO: decompose — M-followup. File is 648 lines; split into
+// sqlite-session-store wiring, cost/metrics routing, and hook-dispatch
+// assembly. Tracked as a future milestone; no structural change in this
+// pass.
 import type { AgentMessage } from "@mariozechner/pi-agent-core";
 import type { AppDatabase } from "@main/database";
 import type { AgentMessageRecord, DesktopEvent } from "@shared/types";
diff --git a/src/main/database-base.ts b/src/main/database-base.ts
index 0a2d3201..353f4787 100644
--- a/src/main/database-base.ts
+++ b/src/main/database-base.ts
@@ -52,9 +52,10 @@ export class AppDatabaseBase {
   readonly vault: SecretVault;
   protected db: DatabaseSync;
 
-  // Domain modules. New code should prefer `db.tasks.saveTask(...)` over the
-  // legacy pass-through methods on AppDatabase. Pass-through remains for
-  // back-compat until all call sites migrate.
+  // Domain modules. The canonical surface — call these directly from
+  // every consumer (`db.tasks.saveTask(...)`, not `db.saveTask(...)`).
+  // The ESLint rule in eslint.config.mjs blocks new top-level methods
+  // on AppDatabase so the old pass-through layer cannot grow back.
   public readonly threads: ReturnType<typeof buildThreadMethods>;
   public readonly company: ReturnType<typeof buildCompanyMethods>;
   public readonly agents: ReturnType<typeof buildAgentMethods>;