composite adapter + semantic-layer positioning

- @reneza/ats-adapter-composite: query many backends as ONE fused corpus
  (bulkFetch unions every child, each task tagged with its backend). Makes the
  cross-source fusion claim real. 10/10 unit tests, conformance-clean.
- README reframed: 'you already have connectors; ATS is the semantic layer' +
  task-first (your task manager is the memory, supporting tools fused in as
  context, not a pile of MEMORY.md files). Composite in tree + table.
- assets/semantic-layer.png: non-tech explainer (built-in memory vs ATS) on
  first-try accuracy (1 in 5 -> 3 in 5, per bench) + steps to answer.
- dropped 'second-brain' framing from the Notion adapter (task-first, not PKM).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: renezander030

README.md

@@ -57,8 +57,13 @@ ats find "deployment runbook"
 </p>
 
 <p align="center">
-  <img src="assets/demo-fusion.gif" alt="ats find — one query fused across GitHub, Notion, and TickTick with RRF" width="760" />
-  <br><em>One <code>ats find</code> across <strong>GitHub + Notion + TickTick</strong>, fused and ranked by RRF — the one thing no single-vendor MCP server can do.</em>
+  <img src="assets/demo-fusion.gif" alt="ats find — one query fused across GitHub, Notion, and TickTick, ranked by RRF" width="760" />
+  <br><em>One <code>ats find</code> across <strong>GitHub + Notion + TickTick</strong> via the <a href="packages/adapter-composite/">composite adapter</a>, ranked by RRF. Your connectors give the agent access; this is the semantic layer that lands the first query on the right answer.</em>
+</p>
+
+<p align="center">
+  <img src="assets/semantic-layer.png" alt="Claude's built-in memory vs the ATS semantic layer — right answer on the first try, fewer steps" width="760" />
+  <br><em>ATS is <strong>task-first</strong>: your task manager is the agent's memory, with supporting tools (GitHub, Notion, docs) fused in as context — not a pile of <code>MEMORY.md</code> files the agent writes and forgets.</em>
 </p>
 
 ## Why this exists
@@ -206,6 +211,7 @@ agentic-task-system/
 │   ├── adapter-google/             # Google Sheets/Docs/Slides as a read-only corpus
 │   ├── adapter-notion/             # Notion databases + pages (page body as markdown)
 │   ├── adapter-github/             # GitHub issues + discussions as text records
+│   ├── adapter-composite/          # cross-source: query many backends as one fused corpus
 │   ├── cli/                        # `ats` command
 │   └── mcp/                        # `@reneza/ats-mcp` — MCP server
 ├── docs/
@@ -249,13 +255,18 @@ Full spec: [`docs/adapter-interface.md`](docs/adapter-interface.md).
 
 ## Available adapters
 
-**Why an adapter instead of pointing your agent straight at the backend's API?**
-A raw Airtable or Google call returns *that* backend's rows; an adapter makes the
-backend part of one retrieval surface:
-
-- **Fused, ranked retrieval across every source.** One query returns a single
-  RRF-ranked, deduped list spanning Airtable + Google + your task app — not N
-  separate tool calls the model has to stitch together itself.
+**You already have connectors. ATS is the semantic layer they're missing.**
+Every vendor ships an official MCP connector now, so your agent can already *reach*
+Notion, GitHub, and your task app. What it can't do is *retrieve* — answer "what do
+I know about the auth migration?" ranked by relevance, across all of them. That's
+the layer ATS adds:
+
+- **Ranked by meaning, not endpoints.** Hybrid keyword + dense + sparse retrieval,
+  fused with RRF, so the first result is the relevant one — not whatever the model
+  guessed to query.
+- **One query, every source.** The [composite adapter](packages/adapter-composite/)
+  fuses GitHub + Notion + your task app into one ranked, deduped list, each hit
+  tagged with its backend — the cross-source retrieval no single-vendor connector does.
 - **Top-k, not token dumps.** Core runs the hybrid keyword+dense retrieval and
   hands back only what's relevant, so the agent never loads a whole base into
   context or hand-writes `filterByFormula` / Sheets ranges it tends to get wrong.
@@ -283,6 +294,7 @@ with everything else.**
 | `google`        | shipped v0.8      | Google Sheets / Docs / Slides (read-only corpus) |
 | `notion`        | shipped v0.8      | Notion databases + pages (page body as markdown) |
 | `github`        | shipped v0.8      | GitHub issues + discussions (repo = project, issue = task) |
+| `composite`     | shipped v0.8      | many adapters fused as one cross-source corpus |
 | `things`        | wishlist          | Things URL scheme + AppleScript |
 | `apple-notes`   | wishlist          | AppleScript                     |
 | `google-tasks`  | wishlist          | Google Tasks API                |
@@ -364,8 +376,8 @@ ats find "Q3 pricing model"
 
 The [Notion adapter](packages/adapter-notion/README.md) maps a database to a
 project and a page to a task — the page title is the title, the block tree renders
-to a markdown body — so your "second brain" is searchable through `ats find` and
-fused with everything else. Auth is an internal integration token, and the
+to a markdown body — so the Notion specs and docs that *support your tasks* are
+searchable through `ats find` and fused in alongside them. Auth is an internal integration token, and the
 security boundary is Notion's own per-page sharing: the integration only sees the
 databases you explicitly share with it.
 

assets/build-semantic-layer.mjs

@@ -0,0 +1,81 @@
+/**
+ * build-semantic-layer.mjs — generates assets/semantic-layer.png
+ *
+ * A non-technical, single-image explainer: Claude's built-in memory
+ * (CLAUDE.md / memory files) vs the ATS semantic layer, in terms a
+ * non-engineer cares about — getting the right answer on the FIRST try, fast.
+ *
+ * Reproduce:  node assets/build-semantic-layer.mjs
+ * Deps:       rsvg-convert (librsvg)
+ */
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+const W = 1000;
+const H = 600;
+const OUT = path.join('assets', 'semantic-layer.png');
+
+const SLATE = '#0f172a';
+const GRAY = '#64748b';
+const TEAL = '#0d9488';
+const TEAL_BG = '#d9f2ee';
+const AMBER = '#c2701c';
+const AMBER_BG = '#fbe8d3';
+
+function panel(x, title, subtitle, headBg, accent, lines, mark, outcome, outcomeBg) {
+  const w = 440;
+  const rows = lines
+    .map((t, i) => {
+      const y = 214 + i * 34;
+      return `<text x="${x + 22}" y="${y}" font-size="17" fill="${accent}" font-weight="bold">${mark}</text>
+    <text x="${x + 48}" y="${y}" font-size="17" fill="${SLATE}">${t}</text>`;
+    })
+    .join('\n    ');
+  return `
+    <rect x="${x}" y="120" width="${w}" height="222" rx="12" fill="#ffffff" stroke="${accent}" stroke-width="1.5"/>
+    <path d="M${x} 132 a12 12 0 0 1 12 -12 h416 a12 12 0 0 1 12 12 v36 h-440 z" fill="${headBg}"/>
+    <text x="${x + 22}" y="148" font-size="19" font-weight="bold" fill="${SLATE}">${title}</text>
+    <text x="${x + 22}" y="170" font-size="13" fill="${GRAY}">${subtitle}</text>
+    ${rows}
+    <rect x="${x + 22}" y="306" width="${outcome.length * 9.2 + 26}" height="26" rx="13" fill="${outcomeBg}"/>
+    <text x="${x + 35}" y="324" font-size="14" font-weight="bold" fill="${accent}">${outcome}</text>`;
+}
+
+function stat(x, label, before, after) {
+  const w = 440;
+  return `
+    <rect x="${x}" y="392" width="${w}" height="168" rx="12" fill="#f8fafc" stroke="#e2e8f0"/>
+    <text x="${x + 24}" y="428" font-size="16" fill="${GRAY}">${label}</text>
+    <text x="${x + 24}" y="492" font-size="30" font-weight="bold" fill="${AMBER}" text-decoration="line-through">${before}</text>
+    <path d="M${x + 200} 482 h54 m-12 -8 l12 8 l-12 8" fill="none" stroke="${GRAY}" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round"/>
+    <text x="${x + 270}" y="494" font-size="40" font-weight="bold" fill="${TEAL}">${after}</text>
+    <text x="${x + 24}" y="534" font-size="13" fill="${GRAY}">built-in memory</text>
+    <text x="${x + 270}" y="534" font-size="13" fill="${TEAL}" font-weight="bold">with ATS</text>`;
+}
+
+const svg = `<svg xmlns="http://www.w3.org/2000/svg" width="${W}" height="${H}" viewBox="0 0 ${W} ${H}" font-family="ui-sans-serif, system-ui, -apple-system, Segoe UI, Roboto, sans-serif">
+  <rect width="${W}" height="${H}" fill="#ffffff"/>
+  <rect x="0.5" y="0.5" width="${W - 1}" height="${H - 1}" rx="14" fill="#ffffff" stroke="#cbd5e1"/>
+  <text x="${W / 2}" y="54" font-size="30" font-weight="bold" fill="${SLATE}" text-anchor="middle">Ask once. Get the right answer first.</text>
+  <text x="${W / 2}" y="86" font-size="16" fill="${GRAY}" text-anchor="middle">The semantic layer ATS adds on top of the connectors your agent already has</text>
+
+  ${panel(40, "Claude's built-in memory", 'CLAUDE.md + memory files', AMBER_BG, AMBER,
+    ['Matches the exact words only', 'Re-reads whole files each time', 'Misses, then asks again'],
+    '✗', 'Often wrong first, slow', AMBER_BG)}
+
+  ${panel(520, 'The ATS semantic layer', 'your curated tools + hybrid RRF search', TEAL_BG, TEAL,
+    ['Understands what you mean', 'Searches every tool at once', 'Right answer first, with sources'],
+    '✓', 'Right first, fast', TEAL_BG)}
+
+  ${stat(40, 'Right on the first try', '1 in 5', '3 in 5')}
+  ${stat(520, 'Steps to the answer', '3–4 tries', '1')}
+</svg>`;
+
+const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'sem-'));
+const svgPath = path.join(tmp, 'semantic.svg');
+fs.writeFileSync(svgPath, svg);
+execFileSync('rsvg-convert', ['-z', '2', svgPath, '-o', OUT]);
+fs.rmSync(tmp, { recursive: true, force: true });
+console.log(`wrote ${OUT} (${Math.round(fs.statSync(OUT).size / 1024)} KB)`);

assets/semantic-layer.png

@@ -0,0 +1,93 @@
+# @reneza/ats-adapter-composite
+
+**ats-adapter-composite** is the cross-source adapter for the [Agentic Task System](https://github.com/renezander030/agentic-task-system) (ATS). It queries several backends — GitHub, Notion, TickTick, Obsidian, and more — as **one fused corpus**, so a single `ats find` returns one RRF-ranked list across all of them, each result tagged with its backend.
+
+![ats find — one query fused across GitHub, Notion, and TickTick, ranked by RRF](https://raw.githubusercontent.com/renezander030/agentic-task-system/main/assets/demo-fusion.gif)
+
+## You already have connectors. This is the semantic layer they're missing.
+
+Your agent can already reach Notion, GitHub, and your task app — every vendor ships an official MCP connector now. That gives the agent *access*: read this page, create that issue, list those tasks. What it does not give you is **retrieval**.
+
+A connector answers "fetch page X." It cannot answer "what do I know about the auth migration?" across three tools, ranked by relevance. That is a search problem, and connectors don't solve it — they hand the model an API and hope it queries the right thing.
+
+ats-adapter-composite is the **semantic layer over your connectors**:
+
+- **Ranked by meaning, not endpoints.** Hybrid retrieval (keyword + dense + sparse) fused with Reciprocal Rank Fusion, so the first result is the relevant one — not whatever the model guessed to query.
+- **One query, every source.** GitHub issues, Notion pages, and your tasks come back in a single ranked list, deduped, each tagged with its backend. No connector does cross-source.
+- **Provenance.** Every hit says which retrieval branch found it and which backend it came from.
+- **No vector database.** Keyword + RRF works out of the box; dense search is optional (local Qdrant + Ollama), never a hosted vector store to maintain.
+
+The connectors are the plumbing. This is the retrieval brain on top.
+
+## Setup
+
+Install the composite plus whichever child adapters you want fused:
+
+```bash
+npm install -g @reneza/ats-cli @reneza/ats-mcp \
+  @reneza/ats-adapter-composite \
+  @reneza/ats-adapter-github @reneza/ats-adapter-notion @reneza/ats-adapter-ticktick
+```
+
+List the children in `~/.config/ats/composite.json`:
+
+```json
+{
+  "adapters": [
+    "@reneza/ats-adapter-github",
+    "@reneza/ats-adapter-notion",
+    "@reneza/ats-adapter-ticktick"
+  ]
+}
+```
+
+Each child reads **its own** existing config and auth (`ATS_GITHUB_TOKEN`, `ATS_NOTION_TOKEN`, the TickTick OAuth login). The composite adds none of its own — it just namespaces ids and routes. Then:
+
+```bash
+ats config use @reneza/ats-adapter-composite
+ats doctor                                  # shows per-backend auth
+ats find "auth token migration"             # one ranked list across all backends
+claude mcp add ats -e ATS_ADAPTER=@reneza/ats-adapter-composite -- ats-mcp
+```
+
+## Mapping
+
+| ATS        | Composite                                                        |
+| ---------- | --------------------------------------------------------------- |
+| Project    | a child project, id namespaced `<backend>:<projectId>` (e.g. `github:owner/repo`, `notion:db-1111`) |
+| Task       | a child record, re-stamped with `source: <backend>`             |
+| `find`     | `bulkFetch()` concatenates every child's corpus → Core runs hybrid + RRF over the union |
+| writes     | routed to the child named by the project id's `<backend>:` prefix |
+
+## FAQ
+
+**I already have a Notion MCP server and a GitHub MCP server. Why this?**
+Those are connectors — they give your agent access to one tool each. This is the retrieval layer: one query, ranked by meaning, fused across all of them, with provenance. Access is not search.
+
+**Does it need a vector database?**
+No. Keyword + RRF works out of the box across every backend; dense retrieval is optional (local Qdrant + Ollama).
+
+**How does auth work across backends?**
+Each child authenticates itself with its own token/OAuth. The composite aggregates status (`ats doctor`) but holds no credentials of its own.
+
+## Part of the Agentic Task System
+
+The composite fuses these backends (install the ones you use):
+
+- [@reneza/ats-adapter-ticktick](https://www.npmjs.com/package/@reneza/ats-adapter-ticktick)
+- [@reneza/ats-adapter-obsidian](https://www.npmjs.com/package/@reneza/ats-adapter-obsidian)
+- [@reneza/ats-adapter-notion](https://www.npmjs.com/package/@reneza/ats-adapter-notion)
+- [@reneza/ats-adapter-github](https://www.npmjs.com/package/@reneza/ats-adapter-github)
+- [@reneza/ats-adapter-airtable](https://www.npmjs.com/package/@reneza/ats-adapter-airtable)
+- [@reneza/ats-adapter-google](https://www.npmjs.com/package/@reneza/ats-adapter-google)
+- [@reneza/ats-adapter-okf](https://www.npmjs.com/package/@reneza/ats-adapter-okf)
+- [@reneza/ats-adapter-taskmaster](https://www.npmjs.com/package/@reneza/ats-adapter-taskmaster)
+- [@reneza/ats-adapter-beads](https://www.npmjs.com/package/@reneza/ats-adapter-beads)
+
+Main repo: [agentic-task-system](https://github.com/renezander030/agentic-task-system).
+
+## Verify
+
+```sh
+node --test     # offline unit tests (fake child adapters)
+```

packages/adapter-composite/README.md

@@ -0,0 +1,126 @@
+/**
+ * Helpers for @reneza/ats-adapter-composite — the cross-source adapter.
+ *
+ * The composite wraps N child ATS adapters and presents them as one corpus, so
+ * `ats find` (which builds its corpus from a single adapter's bulkFetch) actually
+ * fuses results across GitHub + Notion + TickTick + ... in one ranked list. Each
+ * child keeps its own config/auth; the composite only namespaces ids and routes.
+ *
+ * Project ids are namespaced `<backendKey>:<childProjectId>` (e.g. `github:owner/repo`,
+ * `notion:db-1111`). Every returned Task is tagged with `source: <backendKey>` so
+ * the originating backend is visible in results and deep links.
+ *
+ * Zero runtime deps.
+ */
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+export function configPath() {
+  return process.env.ATS_COMPOSITE_CONFIG || path.join(os.homedir(), '.config', 'ats', 'composite.json');
+}
+
+/**
+ * Config: a list of child adapters. Either env `ATS_COMPOSITE_ADAPTERS`
+ * (comma-separated package names/paths) or ~/.config/ats/composite.json:
+ *   { "adapters": ["@reneza/ats-adapter-github", "@reneza/ats-adapter-notion"] }
+ * or with explicit keys:
+ *   { "adapters": [{ "package": "@reneza/ats-adapter-github", "key": "github" }] }
+ */
+export function loadConfig() {
+  let file = {};
+  try {
+    const p = configPath();
+    if (fs.existsSync(p)) file = JSON.parse(fs.readFileSync(p, 'utf8')) || {};
+  } catch {
+    file = {};
+  }
+  const env = process.env.ATS_COMPOSITE_ADAPTERS;
+  const raw = env ? env.split(',') : Array.isArray(file.adapters) ? file.adapters : [];
+  const specs = raw
+    .map((entry) => {
+      if (typeof entry === 'string') {
+        const pkg = entry.trim();
+        return pkg ? { package: pkg, key: backendKeyFor(pkg) } : null;
+      }
+      if (entry && entry.package) return { package: String(entry.package).trim(), key: entry.key || backendKeyFor(entry.package) };
+      return null;
+    })
+    .filter(Boolean);
+  return { specs };
+}
+
+/** Derive a short backend key from a package name or path: `@reneza/ats-adapter-github` -> `github`. */
+export function backendKeyFor(spec) {
+  return String(spec)
+    .replace(/\/+$/, '')
+    .split('/')
+    .pop()
+    .replace(/^@[^/]+\//, '')
+    .replace(/^ats-adapter-/, '')
+    .replace(/[^a-z0-9]+/gi, '-')
+    .replace(/^-+|-+$/g, '')
+    .toLowerCase() || 'child';
+}
+
+/** Dynamically import each configured child adapter. Failures are skipped, not fatal. */
+export async function loadChildren(cfg = loadConfig()) {
+  const children = [];
+  const seen = new Set();
+  for (const spec of cfg.specs) {
+    let key = spec.key;
+    while (seen.has(key)) key = `${key}_`; // de-dupe keys
+    seen.add(key);
+    try {
+      const mod = await import(spec.package);
+      const adapter = mod.default || mod.adapter || mod;
+      if (adapter && typeof adapter.listProjects === 'function') {
+        children.push({ key, package: spec.package, adapter });
+      }
+    } catch {
+      // child not installed / failed to import — skip it
+    }
+  }
+  return children;
+}
+
+const SEP = ':';
+
+export function makeProjectId(key, childProjectId) {
+  return `${key}${SEP}${childProjectId}`;
+}
+
+/** Split a namespaced project id back into { key, childProjectId }. */
+export function splitProjectId(projectId) {
+  const s = String(projectId);
+  const i = s.indexOf(SEP);
+  if (i < 0) return { key: '', childProjectId: s };
+  return { key: s.slice(0, i), childProjectId: s.slice(i + 1) };
+}
+
+/** Re-stamp a child's Task so its projectId is namespaced and its backend is tagged. */
+export function remapTask(key, task) {
+  if (!task) return task;
+  return {
+    ...task,
+    projectId: makeProjectId(key, task.projectId),
+    source: key,
+  };
+}
+
+export function remapProject(key, project) {
+  return {
+    id: makeProjectId(key, project.id),
+    name: `[${key}] ${project.name}`,
+    kind: project.kind,
+    raw: { backend: key, ...(project.raw || {}) },
+  };
+}
+
+/** Find the child whose key matches a namespaced project id. */
+export function childForProject(children, projectId) {
+  const { key, childProjectId } = splitProjectId(projectId);
+  const child = children.find((c) => c.key === key);
+  return { child, childProjectId, key };
+}