fix(coding-agents): scope knowledge pages to the repository they are about (#3571)

A bank collects everything said IN a repository, which is not the same as
everything said ABOUT it. A repo that reads its dependency's source, drafts its
upstream issues or documents how it configures a service files those facts here
too — correctly, since that is where the work happened.

Nothing downstream could tell the two apart. Attribution tags (project:,
harness:, workspace:) record where a fact ARRIVED from, never what it is ABOUT,
and the knowledge:<tier> labels say what KIND of knowledge it is, never whose.
By synthesis time the source document is gone and the fact reads as a bare
technical decision. So "what are this project's key decisions?" was answered
over everything the bank held, and a dependency's decisions were presented as
the repo's own — upstream commit SHAs and all (#3476).

Name the repository in every seeded page's source query and state the
exclusion, so the synthesizer can make that call while it still has the fact's
text in front of it. seedPages() already PATCHes a drifted query, so this
re-syncs onto banks seeded by an earlier version rather than only new ones —
which is why it rides on source_query and not the bank's reflect_mission, which
is seeded ONCE and then belongs to whoever set it (#2492).

Note the queries change, so the next refresh falls out of delta into one full
rebuild per page — which is what re-cleans already-polluted pages.

Author: nicoloboschi

hindsight-integrations/coding-agents/src/core/hindsight.pages.test.ts

@@ -1,8 +1,11 @@
 import { afterEach, describe, expect, it, vi } from "vitest";
 import { HindsightClient } from "./hindsight";
-import { buildPageTrigger, PAGE_MAX_TOKENS, PAGES } from "./missions";
+import { buildPageTrigger, PAGE_MAX_TOKENS, pagesFor } from "./missions";
 import { resolveConfig } from "./config";
 
+/** What a client built with `bank: "repo-a"` and no `project` seeds — the bank id is the fallback. */
+const PAGES = pagesFor("repo-a");
+
 afterEach(() => vi.restoreAllMocks());
 
 function stubFetch(calls: any[], jsonImpl: () => Promise<unknown> = async () => ({ ok: true })) {
@@ -279,6 +282,78 @@ describe("HindsightClient.seedPages", () => {
       tags: drifted.tags,
     });
   });
+
+  it("names the repository in every seeded query, so synthesis can exclude a dependency's facts", async () => {
+    const calls: any[] = [];
+    stubFetchRouted(calls, [
+      { match: (m, u) => m === "GET" && u.endsWith("/knowledge-base/tree"), json: { roots: [] } },
+    ]);
+    const c = new HindsightClient({
+      apiUrl: "http://x",
+      bank: "coding-agent::dotfiles",
+      project: "dotfiles",
+    });
+    await c.seedPages();
+
+    const posts = calls.filter(
+      (k) => k.method === "POST" && k.url.endsWith("/knowledge-base/pages")
+    );
+    expect(posts).toHaveLength(PAGES.length);
+    for (const post of posts) {
+      // The repo is NAMED (not "this project"), and the exclusion is stated — the bank holds
+      // facts about dependencies the repo merely discusses, and they are not its own (#3476).
+      expect(post.body.source_query).toContain("dotfiles");
+      expect(post.body.source_query).toMatch(/external tools, libraries and services/);
+      expect(post.body.source_query).toMatch(/dependency/);
+    }
+  });
+
+  it("falls back to the bank id when no project is supplied, never an unscoped query", async () => {
+    const calls: any[] = [];
+    stubFetchRouted(calls, [
+      { match: (m, u) => m === "GET" && u.endsWith("/knowledge-base/tree"), json: { roots: [] } },
+    ]);
+    const c = new HindsightClient({ apiUrl: "http://x", bank: "coding-agent::dotfiles" });
+    await c.seedPages();
+
+    for (const post of calls.filter((k) => k.method === "POST")) {
+      expect(post.body.source_query).toContain("coding-agent::dotfiles");
+    }
+  });
+});
+
+describe("pagesFor", () => {
+  it("scopes every page in the taxonomy to the named repository", () => {
+    const pages = pagesFor("dotfiles");
+    expect(pages).toHaveLength(5);
+    for (const page of pages) {
+      expect(page.source_query).toContain("Scope this page to dotfiles ITSELF");
+    }
+  });
+
+  it("is a pure function of the project, so a re-seed does not PATCH the same query back", () => {
+    // seedPages() compares the live description against this text on every deepen run; anything
+    // varying per call (a timestamp, a set iteration order) would re-PATCH all five pages forever.
+    expect(pagesFor("dotfiles")).toEqual(pagesFor("dotfiles"));
+    expect(pagesFor("dotfiles")).not.toEqual(pagesFor("other-repo"));
+  });
+
+  it("keeps the taxonomy's names and tier tags untouched", () => {
+    expect(pagesFor("dotfiles").map((p) => p.name)).toEqual([
+      "Component map",
+      "Core concepts",
+      "Conventions and patterns",
+      "Key decisions and rationale",
+      "Initiatives and enhancements",
+    ]);
+    expect(pagesFor("dotfiles").flatMap((p) => p.tags)).toEqual([
+      "knowledge:component",
+      "knowledge:concept",
+      "knowledge:convention",
+      "knowledge:decision",
+      "knowledge:feature-work",
+    ]);
+  });
 });
 
 /** Route JSON responses by (method, url-substring) so multi-call flows can return distinct bodies. */

hindsight-integrations/coding-agents/src/core/hindsight.ts

@@ -10,7 +10,7 @@ import {
   CODING_BANK_STRUCTURE,
   CODING_BANK_TEMPLATE,
   PAGE_MAX_TOKENS,
-  PAGES,
+  pagesFor,
   type PageTrigger,
 } from "./missions";
 import { pool, semverGte, sleep } from "./util";
@@ -30,6 +30,10 @@ export interface ClientOpts {
   apiUrl: string;
   apiToken?: string;
   bank: string;
+  /** Repository this bank is about, named in every seeded page's query (`pageScopeRule`). Only
+   *  `seedPages()` reads it; it falls back to the bank id, which carries the repo name in the
+   *  default `coding-agent::{gitProject}` template. */
+  project?: string;
   log?: (msg: string) => void;
   /** Cap on concurrent retain-related requests (drain op polls, deepen pools). Default 10. */
   maxParallelRetains?: number;
@@ -114,6 +118,7 @@ export class HindsightClient {
   readonly apiUrl: string;
   readonly apiToken?: string;
   readonly bank: string;
+  readonly project?: string;
   readonly opIds: string[] = []; // async operation ids collected by retain(), for drain()
   /** Tri-state capability probe: unknown until the first page request, then cached. */
   knowledgePagesSupported: boolean | undefined;
@@ -126,6 +131,7 @@ export class HindsightClient {
     this.apiUrl = o.apiUrl.replace(/\/$/, "");
     this.apiToken = o.apiToken;
     this.bank = o.bank;
+    this.project = o.project;
     this.log = o.log ?? (() => {});
     this.maxParallelRetains = o.maxParallelRetains || DEFAULT_MAX_PARALLEL_RETAINS;
   }
@@ -470,16 +476,18 @@ export class HindsightClient {
   }
 
   /**
-   * Seed the fixed `PAGES` taxonomy as knowledge-base pages at the tree root, idempotently.
+   * Seed the fixed page taxonomy as knowledge-base pages at the tree root, idempotently.
    *
    * Matched by NAME, not id: `/knowledge-base/pages` mints its own `kp-…` id, so a stable
    * client-chosen id isn't available to match on (unlike the old mental-model path, which keyed
    * off a slug). Names are unique per folder server-side, which makes them a sound key.
    *
    * An existing page is PATCHed rather than recreated so a plugin upgrade that rewords a
-   * `source_query` re-syncs onto the live page instead of orphaning its synthesized content.
+   * `source_query` re-syncs onto the live page instead of orphaning its synthesized content —
+   * which is how `pageScopeRule`'s repo name reaches banks seeded by an earlier version.
    */
   async seedPages(pageTrigger: PageTrigger = buildPageTrigger()): Promise<void> {
+    const pages = pagesFor(this.project ?? this.bank);
     const existing = new Map<string, KnowledgeNode>();
     let roots: KnowledgeNode[];
     try {
@@ -496,7 +504,7 @@ export class HindsightClient {
     }
     let created = 0;
     let updated = 0;
-    for (const page of PAGES) {
+    for (const page of pages) {
       const hit = existing.get(page.name.toLowerCase());
       const body = {
         name: page.name,
@@ -536,7 +544,7 @@ export class HindsightClient {
     }
     this.log(
       `[bank] knowledge pages seeded on ${this.bank}: ${created} created, ${updated} re-synced, ` +
-        `${PAGES.length - created - updated} unchanged`
+        `${pages.length - created - updated} unchanged`
     );
   }
 

hindsight-integrations/coding-agents/src/core/missions.ts

@@ -185,14 +185,46 @@ export const KNOWLEDGE_LABELS: EntityLabelGroup = {
 // any repo; the curator populates each from history+chats and can spawn per-component sub-pages.
 // A seeded page is a tag-scoped synthesis view: `tags` pins it to one `knowledge:<tier>` label so
 // its synthesis draws from the facts the extractor routed to that tier (exact set-ops — see
-// KNOWLEDGE_LABELS above; names/tiers mirror the label vocabulary).
+// KNOWLEDGE_LABELS above; names/tiers mirror the label vocabulary). The tiers say what KIND of
+// knowledge a fact is, never WHOSE — `pageScopeRule` below carries that half.
 export interface KnowledgePage {
   name: string;
   source_query: string;
   tags: string[];
 }
 
-export const PAGES: KnowledgePage[] = [
+/**
+ * The subject-scoping clause every seeded page's query carries, naming the repository it is about.
+ *
+ * A bank collects everything said IN a repository, which is NOT the same as everything said ABOUT
+ * it: a repo that reads its dependency's source, drafts its upstream issues, or documents how it
+ * configures a service files those facts here too — correctly, since that is where the work
+ * happened. Nothing downstream can tell the two apart. Attribution tags (`project:`, `harness:`,
+ * `workspace:`) record where a fact ARRIVED from, never what it is ABOUT, and by synthesis time the
+ * source document is gone: the fact reads as a bare technical decision with no hint whose codebase
+ * it belongs to. So the page builder answered "what are this project's key decisions?" over
+ * everything the bank held and presented a dependency's decisions as the repo's own, upstream
+ * commit SHAs and all (#3476).
+ *
+ * Naming the repo and stating the exclusion is what lets the synthesizer make that call while it
+ * still has the fact's text in front of it. It rides on `source_query` rather than the bank's
+ * `reflect_mission` because the mission is seeded ONCE and then belongs to whoever set it
+ * (CODING_BANK_STRUCTURE, #2492) — a mission-only fix would never reach an existing bank, while a
+ * reworded query re-syncs through `seedPages()`'s drift PATCH on the next run.
+ */
+function pageScopeRule(project: string): string {
+  return (
+    ` Scope this page to ${project} ITSELF: the bank also holds facts about external tools, ` +
+    `libraries and services that ${project} merely uses, configures, deploys or discusses, and ` +
+    `those belong to somebody else's codebase. Include something only when its subject is ` +
+    `${project}'s own code, configuration or process; when it is about a dependency, leave it out ` +
+    `however well-evidenced it looks — including any commit SHA or identifier that belongs to that ` +
+    `dependency's repository rather than this one.`
+  );
+}
+
+/** The taxonomy before scoping — never seeded directly; `pagesFor` binds it to a repository. */
+const PAGE_TAXONOMY: readonly KnowledgePage[] = [
   {
     name: "Component map",
     source_query:
@@ -236,6 +268,17 @@ export const PAGES: KnowledgePage[] = [
   },
 ];
 
+/**
+ * The seeded pages for one repository: the taxonomy above with `project` named in every query.
+ *
+ * A pure function of `project`, so the query text is STABLE for a given repo and `seedPages()`
+ * PATCHes once (on the upgrade that introduces the clause) rather than on every deepen run.
+ */
+export function pagesFor(project: string): KnowledgePage[] {
+  const scope = pageScopeRule(project);
+  return PAGE_TAXONOMY.map((page) => ({ ...page, source_query: page.source_query + scope }));
+}
+
 // Refresh policy shared by every page this plugin creates — the seeded taxonomy above and the
 // per-initiative pages `captureInitiative` adds.
 export const PAGE_MAX_TOKENS = 4096;

hindsight-integrations/coding-agents/src/deepen.ts

@@ -133,6 +133,10 @@ async function main() {
       apiUrl: API_URL,
       apiToken: API_TOKEN,
       bank: FINAL_BANK!,
+      // Names the repository in every seeded page's query, so page synthesis can tell this
+      // project's decisions from those of a dependency it merely discusses (#3476). Same
+      // worktree-aware name the gitlog document id uses, so all worktrees agree on it.
+      project: repoNameOf(REPO!),
       maxParallelRetains: cfg.maxParallelRetains,
       log,
     });