pi-fovea 0.1.2 → 0.3.0

package/README.md

@@ -120,7 +120,34 @@ Global `~/.pi/agent/fovea.json`; project override `<repo>/.pi/fovea.json` when t
 
 ## Repo rule packs
 
-Drop `.fovea/rules.json` in a repo to extend anchor detection beyond the built-ins (express/orval chains, NestJS decorators, Flask/FastAPI decorators, Go chi/mux, axum):
+The built-in pack catches route declarations by **port shape**, not framework name — five shapes cover almost the whole ecosystem:
+
+| Port shape | Examples |
+|---|---|
+| `recv.verb("path", handlers…)` | express, koa, fastify, hono, gin, echo, chi, net/http (any quotes, incl. TS template literals and Python f-strings) |
+| verb-annotation + optional class prefix | NestJS `@Controller + @Get`, Flask/FastAPI decorators, Spring `@RequestMapping + @GetMapping` |
+| verb embedded in the path | Go 1.22 `mux.HandleFunc("GET /x", h)` |
+| verb as first string argument | chi `r.Method("GET", path, h)`, aiohttp `router.add_route("GET", path, h)` |
+| receiver-less DSL macros | Rails `routes.rb`, Phoenix `router.ex`, Django `path()`, Ktor `routing { get("/x") {} }` |
+
+File-convention routers never write a route string at all — those anchors are derived from **file paths** (Next.js App Router `app/**/route.ts` + `page.tsx`, Pages Router `pages/api/**`, SvelteKit `+server.ts` / `+page.svelte`, Nuxt `server/api/**.get.ts`, Astro endpoints), with verbs pulled from exported handler names or file-name suffixes.
+
+**Known blind spots** (deliberate, logged in `src/core/anchors.ts`): Rust proc-macro attribute routers (actix `#[get("/x")]`, rocket) — ast-grep patterns can't parameterize attribute paths; frameworks with constructor-assigned prefixes (Flask Blueprint, FastAPI `APIRouter(prefix=…)`, chi `Mount`, Express `Router` mounts) — variable binding tracking is out of band; `scope`/`namespace` nesting in Phoenix/Rails/Django `include()` — prefixes across blocks aren't composed; tRPC/GraphQL/gRPC — no path token exists to anchor on.
+
+### Tier 3: discovery mode
+
+Unknown shapes self-heal. During the literal pass fovea harvests a per-repo histogram of *call-shape signatures* — `(lang · shape · callee · argIdx)` with a path-precision — and promotes statistically significant unknown ones into **implicit rules**: exact-arity ast-grep patterns, synthesized automatically, wired into the graph at **half hub gravity** with a `△` sigil in `fovea anchors` output. Sync reports discovered churn but never lets an unconfirmed hypothesis escalate to red; a hub upgrades to first-class the moment any site matches a non-implicit rule.
+
+Promotion needs: ≥4 path-carrying sites, spread over ≥2 files, and a Jeffreys-smoothed posterior `p̂ = (pathN + .5) / (n + 1) ≥ 0.55`. Measured against 8 cloned projects, junk bands land below p̂≈0.27 and real shapes above p̂≈0.75 — the line is not tuned to the corpus, it sits mid-cliff. Frameworks already known to the static pack are never re-promoted.
+
+```sh
+fovea anchors <root> --discovered   # only the △ hypothesis hubs
+fovea rules <root>                  # promoted rules + evidence, ready to paste into .fovea/rules.json
+fovea rules <root> --sigs           # every path-touching signature, by precision (audit the corpus)
+fovea rules <root> --adopt          # write them into the repo's rule pack explicitly
+```
+
+Drop `.fovea/rules.json` in a repo to extend anchor detection beyond the built-ins:
 
 ```json
 {

package/cli.ts

@@ -5,12 +5,17 @@
 //   fovea focus [root] <query> [budget]
 //   fovea dwell [root] [factor] [budget]     (deepens the in-process focus)
 //   fovea impact [root] [--files a,b] [--symbols x,y] [--base ref] [--no-uncommitted] [budget]
+//   fovea anchors [root] [filter]             (every feature anchor, sorted)
+//   fovea rules [root]                        (tier-3 discovered shape hypotheses)
 //
 // The CLI is stateless across invocations (dwell needs a prior focus in the
 // same process — combine ops inside pi, where sessions persist); stdout is
 // the rendered field, nothing else, so it composes with head/grep/$().
 
-import { sketch, focus, dwell, impact } from "./src/core/ops.js";
+import { statSync } from "node:fs";
+import { ensureState, sketch, focus, dwell, impact } from "./src/core/ops.js";
+import { aggregateFiles, posterior, promote } from "./src/core/discover.js";
+import { DEFAULT_PACK } from "./src/core/anchors.js";
 
 const [, , cmd = "status", ...argv] = process.argv;
 
@@ -36,9 +41,15 @@ const numAt = (i: number): number | undefined => {
   return Number.isFinite(n) && n > 0 ? n : undefined;
 };
 // Root is the first positional that names a path; everything else is arg data.
+// Existing directories count as paths even when bare ("next", "kernel").
 const rootAt = (i: number): string => {
   const p = pos[i];
-  return p !== undefined && (p.includes("/") || p === ".") ? p : ".";
+  if (p === undefined) return ".";
+  if (p.includes("/") || p === ".") return p;
+  try {
+    if (statSync(p).isDirectory()) return p;
+  } catch { /* not a path */ }
+  return ".";
 };
 
 try {
@@ -71,6 +82,53 @@ try {
       includeUncommitted: !flags.has("no-uncommitted"),
       budget: B ?? 2000,
     }).text;
+  } else if (cmd === "anchors") {
+    const root = rootAt(0);
+    const filter = pos.find((p) => p !== root);
+    const rows = ensureState(root).graph.anchors
+      .map((a) => `${a.implicit ? "△" : " "}\t${a.kind}\t${a.id}\t${a.file}:${a.line}`)
+      .filter((r) => (!filter || r.includes(filter)) && (!flags.has("discovered") || r.startsWith("△")))
+      .sort();
+    out = rows.join("\n");
+  } else if (cmd === "rules") {
+    const root = rootAt(0);
+    const st = ensureState(root);
+    const sigs = aggregateFiles(Object.fromEntries(Object.entries(st.facts).map(([k, v]) => [k, v.sigs])));
+    const promoted = promote(sigs, DEFAULT_PACK);
+    if (flags.has("adopt") && promoted.length) {
+      const { mkdirSync, writeFileSync, readFileSync } = await import("node:fs");
+      const { join } = await import("node:path");
+      mkdirSync(join(root, ".fovea"), { recursive: true });
+      const rulesFile = join(root, ".fovea", "rules.json");
+      let existing = { rules: [] as unknown[] };
+      try { existing = JSON.parse(readFileSync(rulesFile, "utf8")); } catch { /* new */ }
+      const stamp = promoted.map((r) => ({
+        id: r.id.slice("implicit:".length),
+        langs: r.langs,
+        pattern: r.patterns[0],
+        methods: r.methods,
+        kind: r.kind,
+      }));
+      existing.rules = [...existing.rules, ...stamp];
+      writeFileSync(rulesFile, JSON.stringify(existing, null, 2) + "\n");
+      out = `wrote ${stamp.length} discovered rule(s) to .fovea/rules.json`;
+    } else if (flags.has("sigs")) {
+      out = sigs.filter((s) => s.pathN > 0)
+        .sort((a, b) => posterior(b.pathN, b.n) - posterior(a.pathN, a.n))
+        .map((s) => `${posterior(s.pathN, s.n).toFixed(2)}  ${s.pathN}/${s.n} across ${s.files} files  ${s.key}`)
+        .join("\n");
+    } else if (!promoted.length) {
+      out = "(no unknown shape passes the promotion floor — tier-1/2 coverage is doing fine)";
+    } else {
+      out = promoted.map((r) => JSON.stringify({
+        id: r.id.slice("implicit:".length),
+        langs: r.langs,
+        pattern: r.patterns[0],
+        methods: r.methods.replace(/\(\?i\)/, ""),
+        kind: r.kind,
+        _evidence: `p̂=${r.evidence.posterior.toFixed(2)} (${r.evidence.pathN}/${r.evidence.n} sites, ${r.evidence.files} files)`,
+      })).join("\n");
+    }
   } else {
     console.error(`unknown command: ${cmd}`);
     process.exit(2);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-fovea",
-  "version": "0.1.2",
+  "version": "0.3.0",
   "description": "Token-budgeted repo mapping for agent sessions: foveated heat diffusion over a cross-language code graph, with progressive disclosure.",
   "type": "module",
   "license": "MIT",

package/src/core/anchors.ts

@@ -1,8 +1,19 @@
 // Feature anchors: where a feature touches the outside world. Anchors are
 // extracted by a declarative rule pack (ast-grep patterns + metadata), so new
-// frameworks are added as data. A route registration is the canonical anchor:
-// one pattern shape covers express/koa (TS), gin/echo/chi (Go), flask/fastapi
-// decorators (Python), and axum-style chains (Rust).
+// frameworks are added as data. The pack covers five port shapes:
+//
+//   1. recv.verb("path", handlers...)        express/koa/gin/echo/chi(net style)
+//   2. verb-annotation on handler            Nest/Flask/FastAPI(+class prefix)
+//   3. verb embedded in the path string      Go 1.22 mux.HandleFunc("GET /x", h)
+//   4. receiver-less route DSL               Rails, Phoenix, Django
+//   5. file-convention routes                Next/SvelteKit/Nuxt (extractFileRoutes)
+//
+// Every captured token still has to validate as a path before it can become a
+// hub — the route string is the real discriminator, the call shape is flavor.
+// Known blind spots (documented in README): Rust proc-macro attributes
+// (actix/rocket) — ast-grep cannot parameterize attribute paths; frameworks
+// with constructor-assigned prefixes (Flask Blueprint, FastAPI APIRouter,
+// chi Mount); tRPC/GraphQL/gRPC have no path token to anchor at all.
 
 import { createHash } from "node:crypto";
 import { readFileSync } from "node:fs";
@@ -15,7 +26,8 @@ import type { Anchor } from "./types.js";
 export interface AnchorRule {
   id: string;
   langs: string[];
-  pattern: string;
+  /** Single ast-grep pattern; tier-3 synthesized rules use `patterns` instead. */
+  pattern?: string;
   methods: string; // regex tested against the captured method metavar
   kind: string;
   /**
@@ -24,15 +36,56 @@ export interface AnchorRule {
    * prefix + suffix so the anchor id is the full router-visible path.
    */
   prefixPattern?: string[];
+  /** Metavar name that carries the HTTP verb (e.g. chi `r.Method("GET", …)`). */
+  verbFrom?: string;
+  /** Idiom writes paths mount-relative (Django `path("users/")`): root them. */
+  mountRoot?: boolean;
+  /** Synthesized tier-3 rules ship as variant lists (exact arity + trailing $$$H). */
+  patterns?: string[];
+  /** Discovered rules: half hub gravity until a real join upgrades them. */
+  implicit?: boolean;
 }
 
-const PLACEHOLDER_ONLY = /^(:[A-Za-z_]\w*|\{[A-Za-z_]\w*\})$/;
+const HTTP_VERB_RE = /^(?i:get|post|put|delete|patch|head|options)$/;
+
+// Verbs-in-path: Go 1.22 net/http ServeMux writes the verb inside the pattern.
+const VERB_IN_PATH = /^(GET|POST|PUT|DELETE|PATCH|HEAD|OPTIONS)\s+(\/\S*)$/;
+
+// Arg-node captures land with their quote chars (and Python prefixes):
+// '"/users"', "'/items'", '`/users/${id}`', 'f"/users/{id}"' → inner content.
+const QUOTED_RE = /^[rbfuRBFU]{0,3}(["'`])([\s\S]*)\1$/;
+const unquote = (s: string): string => {
+  const m = QUOTED_RE.exec(s.trim());
+  return m ? m[2]! : s.trim();
+};
+
+const PLACEHOLDER_ONLY = /^(:[A-Za-z_]\w*|\{[A-Za-z_]\w*\}|\[[A-Za-z_]\w*\])$/;
+
+// Method names that are mounts, not verbs: Django urls, Rails match/root,
+// Spring's umbrella RequestMapping. They anchor as ANY so the hub exists
+// without pretending a verb was declared.
+// Method names that mount a target rather than declare a verb. fetch(url)
+// and redirect targets both resolve to GET; Django urlconfs and Rails mounts
+// accept any verb.
+const METHOD_ALIASES: Record<string, string> = {
+  PATH: "ANY", RE_PATH: "ANY", URL: "ANY", MATCH: "ANY", ROOT: "ANY",
+  REQUESTMAPPING: "ANY", RESOURCES: "ANY", FORWARD: "ANY",
+  FETCH: "GET", REDIRECT: "GET", RESPONDREDIRECT: "GET", REDIRECT_TO: "GET",
+};
+
+const deriveVerb = (method: string): string => {
+  let up = method.toUpperCase();
+  if (up.endsWith("MAPPING")) up = up.slice(0, -"MAPPING".length); // Spring GetMapping → GET
+  return METHOD_ALIASES[up] ?? up;
+};
 
 export const DEFAULT_PACK: AnchorRule[] = [
   {
+    // `$P` as an arg NODE, not in-string: binds across double/single quotes,
+    // backticks and Python f-strings. Quote chars are stripped by unquote().
     id: "http-route-call",
     langs: ["TypeScript", "Tsx", "JavaScript", "Go"],
-    pattern: '$R.$M("$P", $$$H)',
+    pattern: "$R.$M($P, $$$H)",
     methods: "^(?i:get|post|put|delete|patch|head|options|all|use|any|handle|handlefunc|route|group)$",
     kind: "route",
   },
@@ -41,56 +94,141 @@ export const DEFAULT_PACK: AnchorRule[] = [
     // feature hubs when they reference a real path (validated below).
     id: "http-verb-single-arg",
     langs: ["TypeScript", "Tsx", "JavaScript"],
-    pattern: '$R.$M("$P")',
+    pattern: "$R.$M($P)",
     methods: "^(?i:get|post|put|delete|patch)$",
     kind: "route",
   },
   {
-    id: "http-route-call-singlequote",
-    langs: ["TypeScript", "Tsx", "JavaScript"],
-    pattern: "$R.$M('$P', $$$H)",
-    methods: "^(?i:get|post|put|delete|patch|all|use|handle|route)$",
+    id: "http-verb-single-arg-py",
+    langs: ["Python"],
+    pattern: "$R.$M($P)",
+    methods: "^(get|post|put|delete|patch|head|options)$",
     kind: "route",
   },
   {
-    // NestJS / decorator shape: @Get("/users/:id") on a controller method.
-    id: "ts-http-decorator",
-    langs: ["TypeScript", "Tsx"],
-    pattern: '@$M("$P")',
-    methods: "^(?i:get|post|put|delete|patch|options|head)$",
+    id: "python-route-call",
+    langs: ["Python"],
+    pattern: "$R.$M($P, $$$H)",
+    methods: "^(?:add_)?(?:get|post|put|delete|patch|head|options|route)$",
     kind: "route",
-    prefixPattern: ['@Controller("$P")', "@Controller('$P')"],
   },
   {
-    // Single-quotes dominate real NestJS codebases (NOMAD, starters, docs).
-    id: "ts-http-decorator-singlequote",
+    // NestJS / Angular-style decorators; class prefix via @Controller.
+    id: "ts-http-decorator",
     langs: ["TypeScript", "Tsx"],
-    pattern: "@$M('$P')",
+    pattern: "@$M($P)",
     methods: "^(?i:get|post|put|delete|patch|options|head)$",
     kind: "route",
-    prefixPattern: ['@Controller("$P")', "@Controller('$P')"],
+    prefixPattern: ["@Controller($P)"],
   },
   {
     id: "python-decorator-route",
     langs: ["Python"],
-    pattern: '@$R.$M("$P")',
+    pattern: "@$R.$M($P)",
     methods: "^(get|post|put|delete|patch|route|websocket)$",
     kind: "route",
   },
   {
-    id: "python-decorator-route-singlequote",
+    // chi r.Method("GET", "/x", h), aiohttp web.route(...)/router.add_route(...).
+    id: "verb-as-argument",
+    langs: ["Go", "Python", "TypeScript", "Tsx", "JavaScript"],
+    pattern: '$R.$M("$V", "$P", $$$H)',
+    methods: "^(?i:method|methodfunc|add_route|add_view|route)$",
+    kind: "route",
+    verbFrom: "V",
+  },
+  {
+    // aiohttp module-level / receiver-free form: route("GET", "/x", h).
+    id: "verb-as-argument-norecv",
     langs: ["Python"],
-    pattern: "@$R.$M('$P')",
-    methods: "^(get|post|put|delete|patch|route|websocket)$",
+    pattern: '$M("$V", "$P", $$$H)',
+    methods: "^route$",
+    kind: "route",
+    verbFrom: "V",
+  },
+  {
+    // Django urlconf; mounts for every verb, so they anchor as ANY /x.
+    id: "django-url",
+    langs: ["Python"],
+    pattern: '$M("$P", $$$H)',
+    methods: "^(path|re_path|url)$",
+    kind: "route",
+    mountRoot: true,
+  },
+  {
+    // Rails routes.rb macros. Bare word form, string content capture.
+    id: "rails-route-macro",
+    langs: ["Ruby"],
+    pattern: '$M "$P", $$$R',
+    methods: "^(get|post|put|delete|patch|match|redirect|mount|root|head|options)$",
+    kind: "route",
+  },
+  {
+    id: "rails-route-macro-sq",
+    langs: ["Ruby"],
+    pattern: "$M '$P', $$$R",
+    methods: "^(get|post|put|delete|patch|match|redirect|mount|root|head|options)$",
+    kind: "route",
+  },
+  {
+    // Phoenix router.ex macros. Scope prefixes are not composed (see README).
+    // resources expands to the REST verb set — anchor the mount as ANY,
+    // the hub still merges with controller code via literal joins.
+    id: "phoenix-route-macro",
+    langs: ["Elixir"],
+    pattern: '$M "$P", $$$R',
+    methods: "^(get|post|put|delete|patch|head|options|forward|resources)$",
+    kind: "route",
+  },
+  {
+    id: "phoenix-route-call",
+    langs: ["Elixir"],
+    pattern: '$M("$P", $$$R)',
+    methods: "^(get|post|put|delete|patch|head|options|forward|resources)$",
+    kind: "route",
+  },
+  {
+    // Ktor routing DSL: get("/health") { … }
+    id: "ktor-routing-dsl",
+    langs: ["Kotlin"],
+    pattern: '$M("$P") { $$$B }',
+    methods: "^(get|post|put|delete|patch|head|options|route)$",
+    kind: "route",
+  },
+  {
+    // Spring MVC / WebFlux: class @RequestMapping prefix x method @GetMapping.
+    id: "spring-mapping-annotation",
+    langs: ["Java", "Kotlin"],
+    pattern: '@$M("$P")',
+    methods: "^(Get|Post|Put|Delete|Patch)Mapping$",
     kind: "route",
+    prefixPattern: ['@RequestMapping("$P")'],
   },
   {
     id: "flask-add-url-rule",
     langs: ["Python"],
-    pattern: '$R.add_url_rule("$P", $$$H)',
+    pattern: "$R.add_url_rule($P, $$$H)",
     methods: "^add_url_rule$",
     kind: "route",
   },
+  {
+    // Client fetch with no receiver: fetch("/api/x"). Precision-audited by
+    // discovery (~93% path precision in the next.js clone corpus).
+    id: "fetch-bare",
+    langs: ["TypeScript", "Tsx", "JavaScript"],
+    pattern: "$M($P, $$$H)",  // trailing $$$H absorbs the options bag; zero-arg tail matches fetch("/x") too
+    methods: "^fetch$",
+    kind: "route",
+  },
+  {
+    // Response-side route linkage: ktor respondRedirect("/myfiles") references
+    // an existing route without declaring it. Discovery found it at p̂≈0.81.
+    id: "ktor-respond-redirect",
+    langs: ["Kotlin"],
+    pattern: "$R.$M($P, $$$H)",
+    methods: "^respondRedirect$",
+    kind: "route",
+  },
   {
     id: "rust-router-chain",
     langs: ["Rust"],
@@ -123,26 +261,40 @@ export const extractAnchors = (
     for (const lang of rule.langs) {
       const langFiles = byLang.get(lang);
       if (!langFiles?.length) continue;
-      const prefixes = new Map<string, string>(); // file -> @Controller prefix
+      const prefixes = new Map<string, string>(); // file -> class-level path prefix
       if (rule.prefixPattern?.length) {
         for (const pm of patternRunAll(rule.prefixPattern, lang, langFiles, cwd)) {
           const p = pm.single.P?.trim();
-          if (p !== undefined && !prefixes.has(pm.file)) prefixes.set(pm.file, p);
+          if (p !== undefined && !prefixes.has(pm.file)) prefixes.set(pm.file, unquote(p));
         }
       }
-      for (const m of patternRun(rule.pattern, lang, langFiles, cwd)) {
+      const matchSets = patternRunAll(rule.patterns ?? [rule.pattern!], lang, langFiles, cwd);
+      for (const m of matchSets) {
         const method = m.single.M;
-        const path = m.single.P;
-        if (!method || !path || !methodRe.test(method)) continue;
+        const pathLike = m.single.P;
+        if (!method || !pathLike || !methodRe.test(method)) continue;
         const prefix = prefixes.get(m.file);
-        const raw = prefix !== undefined && prefix !== "" ? joinRoute(prefix, path.trim()) : path.trim();
+        let raw = prefix !== undefined && prefix !== "" ? joinRoute(prefix, unquote(pathLike)) : unquote(pathLike);
+        if (rule.mountRoot && !raw.startsWith("/")) raw = "/" + raw.replace(/^\/+/, "");
+        // Verb embedded in the path string (Go 1.22 mux, Starlette Route).
+        const vip = VERB_IN_PATH.exec(raw);
+        let verbOverride: string | undefined;
+        if (vip) {
+          verbOverride = vip[1]!.toUpperCase();
+          raw = vip[2]!;
+        }
         // $R.$M(...) also matches Map.get("key")-style data access; only real
-        // paths (or router-relative placeholders like ":id") may anchor.
+        // paths (or router-relative placeholders like ":id", "[id]") anchor.
         if (!PATH_TOKEN_RE.test(raw) && !PLACEHOLDER_ONLY.test(raw)) continue;
+        let httpMethod: string;
+        if (rule.verbFrom) {
+          const v = m.single[rule.verbFrom];
+          if (!v || !HTTP_VERB_RE.test(v)) continue;
+          httpMethod = v.toUpperCase();
+        } else {
+          httpMethod = verbOverride ?? deriveVerb(method);
+        }
         const norm = normalizeLiteral(raw, "path");
-        const httpMethod = method.toUpperCase() === "ROUTE" || method.toLowerCase() === "route" || method.toLowerCase() === "use" || method.toLowerCase() === "any"
-          ? method.toUpperCase()
-          : method.toUpperCase();
         const label = `${httpMethod} ${norm}`;
         const enclosing = resolveEnclosing(m.file, m.line);
         out.push({
@@ -152,6 +304,7 @@ export const extractAnchors = (
           nodeId: enclosing ?? `file:${m.file}`,
           file: m.file,
           line: m.line,
+          ...(rule.implicit ? { implicit: true } : {}),
         });
       }
     }
@@ -166,26 +319,132 @@ export const extractAnchors = (
   });
 };
 
+// --- file-convention routes -------------------------------------------------
+
+// Frameworks where the route *is* the file path (no route string exists in
+// code at all): Next App Router, SvelteKit, Nuxt. Each rule is a regex with
+// capture group 1 = route stem, plus how verbs are known.
+export interface FileRouteRule {
+  id: string;
+  re: string;
+  verbs: "exports" | "suffix";
+  pathPrefix?: string; // prepended to the derived route (Nuxt /api)
+  kind?: string; // default "route"
+}
+
+export const DEFAULT_FILE_ROUTES: FileRouteRule[] = [
+  { id: "next-app-route", re: "(?:^|/)app/(.+)/route\\.(?:ts|tsx|js|jsx|mjs)$", verbs: "exports", kind: "route" },
+  { id: "next-app-page", re: "(?:^|/)app/(?:(.+)/)?page\\.(?:tsx|jsx|mdx)$", verbs: "suffix", kind: "page" },
+  { id: "next-pages-api", re: "(?:^|/)pages/api/(.+)\\.(?:ts|tsx|js|jsx)$", verbs: "suffix", pathPrefix: "/api", kind: "route" },
+  { id: "sveltekit-server", re: "(?:^|/)src/routes/(?:(.+)/)?\\+server\\.(?:ts|js)$", verbs: "exports", kind: "route" },
+  { id: "sveltekit-page", re: "(?:^|/)src/routes/(?:(.+)/)?\\+page\\.(?:svelte|md)$", verbs: "suffix", kind: "page" },
+  { id: "nuxt-server-api", re: "(?:^|/)server/api/(.+)\\.(?:ts|js|mjs)$", verbs: "suffix", pathPrefix: "/api", kind: "route" },
+  { id: "astro-endpoint", re: "(?:^|/)src/pages/(.+)\\.(?:ts|js|mjs)$", verbs: "exports", kind: "route" },
+];
+
+// `export async function GET`, `export const POST` — route handler verbs.
+const EXPORTED_VERB_RE = /\bexport\s+(?:(?:async\s+)?function\s+|const\s+)(GET|POST|PUT|DELETE|PATCH|HEAD|OPTIONS)\b/g;
+const SUFFIX_VERB_RE = /\.(get|post|put|delete|patch|head|options)$/i;
+
+// Cards → concrete path. `(group)` segments vanish (Next), dynamic segments
+// become the canonical {*} placeholder, `index` is the path itself.
+const FILE_DYNAMIC_SEG = /^@?\[+(?:\.\.\.)?[^\]]+\]+$/; // [x], [...x], [[...x]] (optional catch-all), @[x]
+const toFileRoutePath = (stem: string): string => {
+  if (stem === "") return "/";
+  const segs = stem.split("/").flatMap((seg) => {
+    if (!seg || /^\(.+\)$/.test(seg)) return [];
+    if (FILE_DYNAMIC_SEG.test(seg)) return ["{*}"];
+    if (seg === "index") return [];
+    return [seg];
+  });
+  return "/" + segs.filter((s) => s !== "").join("/");
+};
+
+export const extractFileRoutes = (files: string[], root: string, rules: FileRouteRule[] = DEFAULT_FILE_ROUTES): AnchorDraft[] => {
+  const compiled = rules.map((r) => ({ rule: r, re: new RegExp(r.re) }));
+  const out: AnchorDraft[] = [];
+  for (const file of files) {
+    for (const { rule, re } of compiled) {
+      const match = re.exec(file);
+      if (!match) continue;
+      let stem = match[1] ?? ""; // optional dir group: route lives at the root
+      if (!stem && !rule.pathPrefix) { /* root page/endpoint: keep going, path is / */ }
+      const verbs = new Set<string>();
+      let suffixVerb: string | undefined;
+      const sv = SUFFIX_VERB_RE.exec(stem);
+      if (sv) {
+        suffixVerb = sv[1]!.toUpperCase();
+        stem = stem.slice(0, -sv[0].length);
+      }
+      if (rule.verbs === "suffix") {
+        if (suffixVerb) verbs.add(suffixVerb);
+      } else {
+        let content = "";
+        try {
+          content = readFileSync(joinPath(root, file), "utf8");
+        } catch {
+          // unreadable: fall through with no verbs
+        }
+        for (const vm of content.matchAll(EXPORTED_VERB_RE)) verbs.add(vm[1]!);
+      }
+      if (verbs.size === 0) verbs.add("ANY")
+      const rel = (rule.pathPrefix ?? "") + toFileRoutePath(stem);
+      const norm = normalizeLiteral(rel, "path");
+      for (const verb of verbs) {
+        const label = `${verb} ${norm}`;
+        out.push({
+          id: label,
+          kind: rule.kind ?? "route",
+          label,
+          nodeId: `file:${file}`,
+          file,
+          line: 0,
+        });
+      }
+    }
+  }
+  return dedupeAnchors(out);
+};
+
+const dedupeAnchors = (out: AnchorDraft[]): AnchorDraft[] => {
+  const seen = new Set<string>();
+  return out.filter((a) => {
+    const k = `${a.id}|${a.file}|${a.line}`;
+    if (seen.has(k)) return false;
+    seen.add(k);
+    return true;
+  });
+};
+
 // Re-export so callers can classify an anchor path like any literal.
 export const anchorClassify = classifyLiteral;
 
-// Repo-local overrides: .fovea/rules.json = { "rules": AnchorRule[] }.
-// Merged after the default pack; the content hash invalidates the fact cache
-// so changing rules rebuilds anchors only.
-export const loadRepoRules = (root: string): { pack: AnchorRule[]; sha: string } => {
+// Hash of the built-in packs: code changes to the default pack invalidate
+// cached anchor facts even when a repo ships no rules.json of its own.
+const DEFAULTS_SHA = createHash("sha1")
+  .update(JSON.stringify(DEFAULT_PACK))
+  .update(JSON.stringify(DEFAULT_FILE_ROUTES))
+  .digest("hex");
+
+// Repo-local overrides: .fovea/rules.json = { "rules": AnchorRule[], "fileRoutes": FileRouteRule[] }.
+export const loadRepoRules = (root: string): { pack: AnchorRule[]; fileRoutes: FileRouteRule[]; sha: string } => {
   let raw = "";
   try {
     raw = readFileSync(joinPath(root, ".fovea", "rules.json"), "utf8");
   } catch {
-    return { pack: DEFAULT_PACK, sha: "" };
+    return { pack: DEFAULT_PACK, fileRoutes: DEFAULT_FILE_ROUTES, sha: DEFAULTS_SHA };
   }
+  // Repo rules extend defaults; the defaults themselves ride in the hash,
+  // so upgrading pi-fovea invalidates anchors even with no repo rules file.
+  const sha = createHash("sha1").update(DEFAULTS_SHA + raw).digest("hex");
   try {
-    const parsed = JSON.parse(raw) as { rules?: AnchorRule[] };
+    const parsed = JSON.parse(raw) as { rules?: AnchorRule[]; fileRoutes?: FileRouteRule[] };
     const rules = (parsed.rules ?? []).filter(
       (r) => r && typeof r.pattern === "string" && typeof r.methods === "string" && Array.isArray(r.langs),
     );
-    return { pack: [...DEFAULT_PACK, ...rules], sha: createHash("sha1").update(raw).digest("hex") };
+    const fileRoutes = (parsed.fileRoutes ?? []).filter((r) => r && typeof r.re === "string" && typeof r.verbs === "string");
+    return { pack: [...DEFAULT_PACK, ...rules], fileRoutes: [...DEFAULT_FILE_ROUTES, ...fileRoutes], sha };
   } catch {
-    return { pack: DEFAULT_PACK, sha: createHash("sha1").update(raw).digest("hex") };
+    return { pack: DEFAULT_PACK, fileRoutes: DEFAULT_FILE_ROUTES, sha: createHash("sha1").update(raw).digest("hex") };
   }
 };

package/src/core/build.ts

@@ -8,10 +8,11 @@ import { existsSync, readFileSync, readdirSync, writeFileSync, mkdirSync } from
 import { tmpdir } from "node:os";
 import { basename, dirname, join as joinPath, posix } from "node:path";
 import { spawnSync } from "node:child_process";
-import { LANG_BY_EXT, isBinaryExt, isConfigFile } from "./astgrep.js";
+import { LANG_BY_EXT, isBinaryExt, isConfigFile, langOf } from "./astgrep.js";
 import { extractCalls, extractImports, extractLiterals, extractSymbols, isTestFile } from "./extract.js";
 import { buildJoinIndex } from "./join.js";
-import { extractAnchors, loadRepoRules } from "./anchors.js";
+import { extractAnchors, extractFileRoutes, loadRepoRules } from "./anchors.js";
+import { aggregateFiles, harvestFile, promote, type FileSigs, type SynthesizedRule } from "./discover.js";
 import type { CallSite, Edge, Graph, ImportSite, LiteralSite, NodeRec, SymbolRec } from "./types.js";
 import type { AnchorDraft } from "./anchors.js";
 import { coChangePairs } from "./cochange.js";
@@ -23,9 +24,13 @@ export interface FileFacts {
   calls: CallSite[];
   literals: LiteralSite[];
   anchors: AnchorDraft[];
+  // Tier-3 discovery: per-file histogram of call-shape signatures
+  // (sig -> [totalSites, pathSites]); aggregated repo-wide at load to promote
+  // statistically significant unknown shapes into implicit half-weight rules.
+  sigs?: FileSigs;
 }
 
-const CACHE_VERSION = 4; // bump when extractor semantics change
+const CACHE_VERSION = 6; // bump when extractor semantics change
 const IGNORE_DIRS = new Set([".git", "node_modules", "dist", "vendor", ".venv", "venv", "target", "coverage", ".next", "build", "__pycache__", ".pi", ".pi-fovea", "deps", "_build", ".tox", "Pods"]);
 const MAX_FILES = 24000;
 // Generated dependency manifests are enormous and carry no first-class routes.
@@ -41,12 +46,14 @@ const isJunk = (f: string): boolean => {
   return LOCKFILE_NAMES.has(base) || base.endsWith(".lock");
 };
 
-const supported = (f: string): boolean => {
+const supported = (f: string, routeRes?: RegExp[]): boolean => {
   const ext = f.split(".").pop()?.toLowerCase() ?? "";
-  return !isBinaryExt(f) && (ext in LANG_BY_EXT || isConfigFile(f));
+  if (!isBinaryExt(f) && (ext in LANG_BY_EXT || isConfigFile(f))) return true;
+  // File-convention routers use extensions with no ast-grep lang (.svelte, .mdx).
+  return routeRes?.some((re) => re.test(f)) ?? false;
 };
 
-export const listFiles = (root: string): string[] => {
+export const listFiles = (root: string, routeRes?: RegExp[]): string[] => {
   const res = spawnSync("git", ["-C", root, "ls-files", "-co", "--exclude-standard"], {
     encoding: "utf8",
     timeout: 30_000,
@@ -67,14 +74,14 @@ export const listFiles = (root: string): string[] => {
         const rel = prefix ? `${prefix}/${e.name}` : e.name;
         if (e.isDirectory()) {
           if (!IGNORE_DIRS.has(e.name)) walk(joinPath(dir, e.name), rel);
-        } else if (e.isFile() && supported(rel)) {
+        } else if (e.isFile() && supported(rel, routeRes)) {
           files.push(rel);
         }
       }
     };
     walk(root, "");
   }
-  files = files.filter((f) => supported(f) && !isJunk(f));
+  files = files.filter((f) => supported(f, routeRes) && !isJunk(f));
   files.sort();
   return files.slice(0, MAX_FILES);
 };
@@ -101,8 +108,12 @@ export const loadFacts = (root: string, files: string[]): Record<string, FileFac
   } catch {
     cached = undefined;
   }
-  const { pack: anchorPack, sha: rulesSha } = loadRepoRules(root);
-  const rulesChanged = cached !== undefined && cached.rulesSha !== rulesSha;
+  const { pack: basePack, fileRoutes, sha: baseRulesSha } = loadRepoRules(root);
+  const anchorPack = [...basePack];
+  // Implicit rules promote AFTER the first fact pass: their evidence lives in
+  // freshly harvested sigs, so the pack can only be finalized once facts exist.
+  let implicitRules: SynthesizedRule[] = [];
+  let rulesSha = baseRulesSha;
   if (cached && (cached.version !== CACHE_VERSION || cached.root !== root)) cached = undefined;
   const facts: Record<string, FileFacts> = {};
   const dirty: string[] = [];
@@ -131,12 +142,31 @@ export const loadFacts = (root: string, files: string[]): Record<string, FileFac
     putByFile(extractImports(code, root), (f, v) => f.imports.push(v));
     putByFile(extractCalls(code, root), (f, v) => f.calls.push(v));
     putByFile(extractLiterals(dirty, root), (f, v) => f.literals.push(v));
+    // Tier-3 harvest: regex histogram of call-shape signatures per file. Cheap
+    // (line scan, no ast-grep) and cached alongside the other facts.
+    for (const f of code) {
+      const lang = langOf(f);
+      if (!lang) continue;
+      let text = "";
+      try { text = readFileSync(joinPath(root, f), "utf8"); } catch { continue; }
+      const sigs = harvestFile(lang, text);
+      if (Object.keys(sigs).length) facts[f]!.sigs = sigs;
+    }
+  }
+  // Tier-3: promote harvested signatures into implicit rules BEFORE anchors
+  // run, and fold their ids into the rules hash so a promotion change rebuilds
+  // anchors exactly like a rules.json edit would.
+  implicitRules = promote(aggregateFiles(Object.fromEntries(Object.entries(facts).map(([k, v]) => [k, v.sigs]))), anchorPack);
+  if (implicitRules.length) {
+    anchorPack.push(...implicitRules);
+    rulesSha = createHash("sha1").update(baseRulesSha).update(JSON.stringify(implicitRules.map((r) => r.id).sort())).digest("hex");
   }
+  const rulesChangedFinal = cached !== undefined && cached.rulesSha !== rulesSha;
   // Anchors need enclosing-symbol resolution. Symbols, imports, calls and
   // literals are rules-independent — when only the rule pack changed, re-run
   // anchor extraction over every code file against cached symbols and keep
   // every other fact (green-node reuse one level up).
-  const anchorTargets = rulesChanged
+  const anchorTargets = rulesChangedFinal
     ? files.filter((f) => !isConfigFile(f))
     : dirty.filter((f) => !isConfigFile(f));
   if (anchorTargets.length) {
@@ -149,7 +179,7 @@ export const loadFacts = (root: string, files: string[]): Record<string, FileFac
     const symsByFile = new Map<string, SymbolRec[]>();
     for (const rel of anchorTargets) {
       symsByFile.set(rel, facts[rel]?.symbols.length ? facts[rel]!.symbols : (cached?.facts[rel]?.symbols ?? []));
-      if (rulesChanged) facts[rel] && (facts[rel]!.anchors = []);
+      if (rulesChangedFinal) facts[rel] && (facts[rel]!.anchors = []);
     }
     const enclosingId = (file: string, line: number): string | undefined => {
       const syms = symsByFile.get(file) ?? [];
@@ -158,6 +188,9 @@ export const loadFacts = (root: string, files: string[]): Record<string, FileFac
       return best ? `${best.name}@${best.file}` : `file:${file}`;
     };
     putByFile(extractAnchors(anchorTargets, root, enclosingId, anchorPack), (f, v) => f.anchors.push(v));
+    // File-convention routes (Next/SvelteKit/Nuxt): the route path is derived
+    // from the file path; verbs come from exported handler names or suffix.
+    putByFile(extractFileRoutes(anchorTargets, root, fileRoutes), (f, v) => f.anchors.push(v));
   }
   try {
     mkdirSync(dirname(cacheFile), { recursive: true });
@@ -386,13 +419,18 @@ export const assembleGraph = (root: string, files: string[], facts: Record<strin
   for (const [label, sites] of draftsByLabel) {
     const first = sites[0]!;
     const filesOf = [...new Set(sites.map((s) => s.file))];
-    anchors.push({ id: label, kind: first.kind, label: sites.length > 1 ? `${label} · ${sites.length} sites` : label, nodeId: first.nodeId, file: first.file, line: first.line });
+    // A hub is implicit only when EVERY site came from a discovered rule — a
+    // match by any real rule upgrades it back to first-class instantly.
+    const hubImplicit = sites.every((s) => s.implicit === true);
+    anchors.push({ id: label, kind: first.kind, label: sites.length > 1 ? `${label} · ${sites.length} sites` : label, nodeId: first.nodeId, file: first.file, line: first.line, ...(hubImplicit ? { implicit: true } : {}) });
     const idx = addNode(nodes, seen, {
       id: `anchor:${label}`, name: label, kind: "anchor", file: first.file, line: first.line,
-      sig: sites.length > 1 ? `${label} (${sites.length} sites)` : label, lang: "anchor",
+      sig: `${hubImplicit ? "(△ discovered) " : ""}${sites.length > 1 ? `${label} (${sites.length} sites)` : label}`, lang: "anchor",
     });
     (byFile.get(first.file) ?? byFile.set(first.file, []).get(first.file)!).push(idx);
-    const w = 1 / Math.sqrt(sites.length);
+    // Tier-3 hubs prove themselves at half conductance; a later literal join
+    // against a first-class hub can still warm them via the channel edges.
+    const w = (hubImplicit ? 0.5 : 1) / Math.sqrt(sites.length);
     for (const s of sites) {
       const handler = seen.get(s.nodeId) ?? fileIdx.get(s.file)!;
       pushEdge(idx, handler, "anchors", w);

package/src/core/discover.ts

@@ -0,0 +1,188 @@
+// Tier-3: autonomy for route extraction. The static pack catches known port
+// shapes; this module watches the literal channel for shapes the pack does NOT
+// declare, promotes statistically significant ones into synthesized "implicit"
+// rules at half hub gravity, and lets confirmatory joins against real hubs
+// upgrade them to full first-class weight.
+//
+// The promotion statistic is a per-argument conditional: given the string arg
+// at position i of call-shape (lang·shape·callee), how often does it classify
+// as a path? A Jeffreys-smoothed posterior with global floors decides — not raw
+// frequency, under which chaff like `assertEquals(...)` dwarfs every real shape.
+//
+// Corpus audit (8 repos, 183 sigs n≥4): junk bands sit below p̂≈0.27, real
+// shapes above p̂≈0.75 — the 0.55 line is a cliff, not a gradient.
+//
+// Harvest is line-regex over source text — no ast-grep pass needed. Per file we
+// store a compact signature histogram (sig -> [sites, pathSites]); promotions
+// aggregate across ALL files of the repo, so a dependency update or a style
+// drift can only flip a marginal signature when its repo-wide evidence moves.
+
+import { classifyLiteral } from "./join.js";
+
+export type Shape = "recv" | "bare" | "dec";
+
+// Compacted per-file histogram: sigKey -> [totalSites, pathSites]
+export type FileSigs = Record<string, [number, number]>;
+
+const QUOTED = /^[rbfuRBFU]{0,3}(["'`])([\s\S]*)\1$/;
+const unquote = (s: string): string | undefined => {
+  const m = QUOTED.exec(s.trim());
+  return m ? m[2] : undefined;
+};
+
+// Line-local call scan: grabs the callee shape (recv chain, bare, decorator)
+// and the raw arg list of every `X(...)` on the line. Multi-line calls still
+// land because route strings overwhelmingly sit on the call's first line.
+const CALL_LINE_RE = /(?<at>@)?(?<recv>(?:[A-Za-z_$][\w$]*\.)+)?(?<method>[A-Za-z_$][\w$]*)\s*\((?<args>[^()]*)\)/g;
+const STRING_RE = /([rbfuRBFU]{0,3})(["'`])((?:\\.|(?!\2)[^\\])*)\2/g;
+
+// Callees that are noise even at 100% precision (env/fs access, string ctors,
+// module loading — dynamic import()/require() hits the path channel but the
+// import edge already covers it, an anchor would double-count the site).
+const CALLEE_DENY = new Set([
+  "join", "resolve", "dirname", "basename", "expand_path",
+  "readFile", "readFileSync", "existsSync", "open", "load", "loads",
+  "import", "require",
+  // String predicates: membership tests hit the path column at high rate but
+  // never refer to routes. (Distinguishing cause from noise is callee-semantic.)
+  "startsWith", "endsWith", "contains", "includes", "equals", "equalsIgnoreCase",
+  "matches", "matchesPattern", "useParams", "matchPath",
+]);
+
+export const harvestFile = (lang: string, text: string): FileSigs => {
+  const sigs: FileSigs = {};
+  for (const line of text.split("\n")) {
+    if (!line.includes("(") || !(line.includes('"') || line.includes("'") || line.includes("`"))) continue;
+    CALL_LINE_RE.lastIndex = 0;
+    let c: RegExpExecArray | null;
+    while ((c = CALL_LINE_RE.exec(line))) {
+      const method = c.groups?.method;
+      if (!method || CALLEE_DENY.has(method)) continue;
+      const shape: Shape = c.groups?.at ? "dec" : c.groups?.recv ? "recv" : "bare";
+      const argsText = c.groups?.args ?? "";
+      if (!argsText) continue;
+      // True argument index of each string literal (split tolerantly on commas).
+      const args = argsText.split(",");
+      let idx = 0;
+      for (const raw of args) {
+        STRING_RE.lastIndex = 0;
+        const sm = STRING_RE.exec(raw);
+        const idxNow = idx++;
+        if (!sm) continue;
+        const lit = sm[3];
+        if (lit === undefined || lit === "") continue;
+        const key = `${lang}|${shape}|${method}|${idxNow}`;
+        const rec = sigs[key] ?? [0, 0];
+        rec[0]++;
+        if (classifyLiteral(lit) === "path") rec[1]++;
+        sigs[key] = rec;
+      }
+    }
+  }
+  return sigs;
+};
+
+export interface SigStats {
+  key: string;
+  lang: string;
+  shape: Shape;
+  callee: string;
+  argIdx: number;
+  n: number;
+  pathN: number;
+  files: number;
+}
+
+export const aggregateFiles = (perFile: Record<string, FileSigs | undefined>): SigStats[] => {
+  const agg = new Map<string, SigStats>();
+  for (const sigs of Object.values(perFile)) {
+    if (!sigs) continue;
+    for (const [key, [n, p]] of Object.entries(sigs)) {
+      const stat = agg.get(key);
+      if (stat) {
+        stat.n += n;
+        stat.pathN += p;
+        stat.files++;
+      } else {
+        const [lang, shape, callee, argIdx] = key.split("|");
+        agg.set(key, { key, lang: lang!, shape: shape as Shape, callee: callee!, argIdx: Number(argIdx), n, pathN: p, files: 1 });
+      }
+    }
+  }
+  return [...agg.values()];
+};
+
+/** Jeffreys-ish posterior: p̂ = (pathN + .5) / (n + 1). */
+export const posterior = (pathN: number, n: number): number => (pathN + 0.5) / (n + 1);
+
+export const MIN_SITES = 4;
+export const MIN_FILES = 2;
+export const MIN_POSTERIOR = 0.55;
+
+const escapeRe = (s: string): string => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+
+// Pattern synthesis per shape and arg position: dummy metavars for the slots
+// the corpus says are not the path, $P at the proven position. Two variants
+// per site — exact arity and with a trailing $$$H absorb — because some
+// dialects only match with explicit tail holes (Python `$X, $P, $$$H`).
+export interface SynthesizedRule {
+  id: string;
+  langs: string[];
+  patterns: string[];   // patternRunAll variants
+  methods: string;
+  kind: string;
+  implicit: true;
+  evidence: { n: number; pathN: number; files: number; posterior: number };
+}
+
+export const synthesize = (s: SigStats): SynthesizedRule | undefined => {
+  const slots: string[] = [];
+  for (let i = 0; i <= s.argIdx; i++) slots.push(i === s.argIdx ? "$P" : `$X${i}`);
+  const inner = slots.join(", ");
+  let variants: string[];
+  switch (s.shape) {
+    case "recv": variants = [`$R.$M(${inner})`, `$R.$M(${inner}, $$$H)`]; break;
+    case "bare": variants = [`$M(${inner})`, `$M(${inner}, $$$H)`]; break;
+    case "dec":  variants = [`@$M(${inner})`, `@$M(${inner}, $$$H)`]; break;
+  }
+  return {
+    id: `implicit:${s.lang.toLowerCase()}:${s.shape}:${s.callee}:${s.argIdx}`,
+    langs: [s.lang],
+    patterns: variants,
+    methods: `^(?i:${escapeRe(s.callee)})$`,
+    kind: "route",
+    implicit: true,
+    evidence: { n: s.n, pathN: s.pathN, files: s.files, posterior: posterior(s.pathN, s.n) },
+  };
+};
+
+// Shape-shape compatibility: a discovery is only NEW when no existing rule
+// already binds the callee with a compatible pattern shape in that language.
+// e.g. Java's @GetMapping is in the pack, so java:dec:GetMapping promotes nothing.
+const shapeCompatPatterns: Record<Shape, RegExp> = {
+  recv: /^\$R\.\$M\(/,
+  bare: /^\$M[(\s]/,
+  dec: /^@\$(R\.)?M\(/,
+};
+
+const isCovered = (sig: SigStats, pack: Array<{ langs: string[]; methods: string; pattern?: string; patterns?: string[] }>): boolean => {
+  const mre = (methods: string, callee: string): boolean => new RegExp(methods.replace(/^\^\(\?i\)/, "^(?i:")).test(callee);
+  return pack.some((r) => {
+    if (!r.langs.includes(sig.lang)) return false;
+    if (!mre(r.methods, sig.callee)) return false;
+    const pats = r.patterns ?? (r.pattern ? [r.pattern] : []);
+    return pats.some((p) => shapeCompatPatterns[sig.shape].test(p));
+  });
+};
+
+export const promote = (sigs: SigStats[], pack: Array<{ id: string; langs: string[]; methods: string; pattern?: string; patterns?: string[] }> = []): SynthesizedRule[] => {
+  const out: SynthesizedRule[] = [];
+  for (const s of sigs) {
+    if (s.n < MIN_SITES || s.files < MIN_FILES) continue;
+    if (posterior(s.pathN, s.n) < MIN_POSTERIOR) continue;
+    if (isCovered(s, pack)) continue;
+    const r = synthesize(s);
+    if (r) out.push(r);
+  }
+  return out;
+};

package/src/core/join.ts

@@ -14,7 +14,7 @@ export interface LitOccurrence { node: number; line: number; file: string; }
 
 export interface JoinEdge { a: number; b: number; w: number; }
 
-const PLACEHOLDER_SEGMENT = /^(?::[^/]+|\{[^}/]*\}|\$\{[^}/]*\}|\*+)$/;
+const PLACEHOLDER_SEGMENT = /^(?::[^/]+|\{[^}/]*\}|\$\{[^}/]*\}|\$[A-Za-z_]\w*|<[^/>]+>|\*+)$/; // $x = Kotlin template shorthand
 const WORD_RE = /^[A-Za-z][\w$.\-]{6,63}$/;
 const URLISH_RE = /^(?:https?|wss?):\/\/[^/]+/;
 

package/src/core/ops.ts

@@ -9,6 +9,7 @@ import { spawnSync } from "node:child_process";
 import { posix } from "node:path";
 import { hasAstGrep } from "./astgrep.js";
 import { assembleGraph, listFiles, loadFacts, type FileFacts } from "./build.js";
+import { loadRepoRules } from "./anchors.js";
 import { buildCsr, chebyshevVectors, chooseOrder, heatField, type Csr } from "./heat.js";
 import { revealFoveated, revealGroups, tokenEstimate, type GroupLine } from "./render.js";
 import { getSession, TK_ORDER } from "./session.js";
@@ -49,7 +50,9 @@ export const ensureState = (root: string): RepoState => {
       "fovea: `ast-grep` binary not found on PATH (set FOVEA_AST_GREP to override). Install: https://ast-grep.github.io/",
     );
   }
-  const files = listFiles(root);
+  const { fileRoutes } = loadRepoRules(root);
+  const routeRes = fileRoutes.map((r) => new RegExp(r.re));
+  const files = listFiles(root, routeRes);
   const facts = loadFacts(root, files);
   const version = graphVersion(facts);
   const cached = states.get(root);

package/src/core/sync.ts

@@ -64,10 +64,14 @@ export const sync = (root: string, params: SyncParams, now?: RepoState): SyncOut
     };
   }
 
-  // Version drifted: measure what moved.
-  const current = new Set(state.graph.anchors.map((a) => a.id));
-  const added = [...current].filter((id) => !prev.anchors.has(id));
-  const removed = [...prev.anchors].filter((id) => !current.has(id));
+  // Version drifted: measure what moved. Implicit (tier-3 discovered) hubs
+  // churn is reported but NEVER escalates alone — hypotheses with no first-class
+  // backing don't get to wake the model with a red verdict.
+  const current = new Map(state.graph.anchors.map((a) => [a.id, a.implicit === true]));
+  const currentIds = new Set(current.keys());
+  const added = [...currentIds].filter((id) => !prev.anchors.has(id));
+  const removed = [...prev.anchors].filter((id) => !currentIds.has(id));
+  const newlyImplicit = added.filter((id) => current.get(id));
 
   const session = getSession(root);
   const disclosedFiles = new Set<string>();
@@ -92,7 +96,7 @@ export const sync = (root: string, params: SyncParams, now?: RepoState): SyncOut
 
   baselines.set(root, { ...snapshot(state), warmed: warmNow });
 
-  const red = added.length + removed.length > 0 || warmNew.length >= Math.max(1, params.warmFileThreshold);
+  const red = (added.length - newlyImplicit.length) + removed.length > 0 || warmNew.length >= Math.max(1, params.warmFileThreshold);
   if (!red) {
     return {
       structural: true, red: false, tokens: 0,
@@ -102,7 +106,8 @@ export const sync = (root: string, params: SyncParams, now?: RepoState): SyncOut
 
   const lines: string[] = [];
   lines.push(`fovea sync · v ${state.version} · edit cascade did not stay local`);
-  for (const id of added.slice(0, 12)) lines.push(`  ⚑=new ${id}`);
+  for (const id of added.filter((a) => !newlyImplicit.includes(a)).slice(0, 12)) lines.push(`  ⚑=new ${id}`);
+  for (const id of newlyImplicit.slice(0, 6)) lines.push(`  △ newly discovered hub ${id}`);
   for (const id of removed.slice(0, 12)) lines.push(`  ⚑-removed ${id}`);
   if (warmNew.length) {
     lines.push(`  newly warm undisclosed files (revisit with fovea_focus):`);

package/src/core/types.ts

@@ -48,6 +48,7 @@ export interface Anchor {
   nodeId: string;    // handler symbol node id, or enclosing node
   file: string;
   line: number;
+  implicit?: boolean; // tier-3 discovered shape: half hub gravity, shown with △
 }
 
 export interface Graph {