scopecairn 0.8.0 → 0.9.0

package/README.md

@@ -36,7 +36,7 @@ No MCP server, no embeddings, no network calls, no telemetry.
 - **Auto-refresh** — `context` and `impact` re-index changed files first;
   run `scan` after editing to close the loop.
 - **Framework adapters** — Next.js (App + Pages Router routes),
-  Prisma models, and Drizzle tables/queries detected automatically.
+  Prisma models, Drizzle tables/queries, Express, FastAPI, NestJS (controllers, routes, injectables), Django (urls, models), SQLAlchemy, and Vue SFC detected automatically.
 - **Multi-language** — TypeScript, JavaScript, Python, Java, Go, Rust,
   PHP, C#, C/C++, Ruby, HTML, Vue SFC (plus config/schema files as
   graph nodes).
@@ -157,14 +157,18 @@ scopecairn agents list
 | `read symbol <name>` | Symbol-level source excerpt (not whole files) |
 | `<agent> install` | Per-agent setup: `antigravity`, `claude`, `gemini`, `cursor`, `windsurf`, `copilot`, `kiro` (each also `uninstall`; `agents list` to see all) |
 | `dashboard` | Generate local HTML dashboard at `.scopecairn/dashboard.html` |
-| `test-select <target>` | List test files affected by a file/symbol change target |
+| `test-select <target> [--run]` | List affected test files via graph dependency traversal & runner detection (`--run` executes runner) |
+| `verify [--task <t>] [--strict]` | Post-edit guard: check modified protected files, task scope creep, and circular dependency regressions |
+| `diff` | Structural symbol-level diff of working tree vs HEAD with breaking impact alerts |
+| `arch-check [--init]` | Check architectural layer rules & disallowed import boundaries (`--init` scaffolds `.scopecairn/arch.json`) |
+| `watch [--debounce <ms>]` | Daemon mode: auto-refresh index in background on file saves |
 | `doctor --verbose` | Also surface adapter/graph errors from `.scopecairn/last-run.log` to stderr |
 | `benchmark [--tune]` | Retrieval recall, irrelevant ratio, context reduction + weight calibration |
 | `update [--check]` | Update ScopeCairn to the latest npm release (`--check` only checks) |
 
-Agent commands (`context`, `impact`, `read`, `graph`, `status`, `doctor`)
+Agent commands (`context`, `impact`, `read`, `graph`, `status`, `doctor`, `verify`, `diff`, `test-select`, `arch-check`)
 are read-only toward source and only write to `.scopecairn/` — safe to
-allowlist. `init`, `scan`, and `rebuild` are manual/user-side commands.
+allowlist. `init`, `scan`, `rebuild`, and `watch` are manual/user-side commands.
 
 ## Framework adapters
 
@@ -178,6 +182,8 @@ No configuration needed.
 | `drizzle` | `drizzle*` paths/config, `db/` schemas | `model` symbols from `pgTable`/`sqliteTable`/`mysqlTable`; `QUERIES` from `db.query.*` relational and `db.select/insert/update/delete` builder calls |
 | `express` | `package.json` deps | Route symbols from `app/router.METHOD(path)`, handler edges |
 | `fastapi` | `.py` routes, requirements/pyproject | Route symbols from `@app.METHOD("/path")` decorators |
+| `nestjs` | `*.controller.ts`, `*.service.ts`, `nest-cli.json` | Route symbols from `@Controller` and `@Get/@Post/...` decorators, `ROUTES_TO` handler edges, `@Injectable()` service providers |
+| `django` | `manage.py`, `urls.py`, `models.py` | Route symbols from `path()`/`re_path()` in `urls.py`, `ROUTES_TO` handler edges, `model` symbols from `models.Model` |
 | `sqlalchemy` | requirements/pyproject | `model` symbols from `class X(Base)`/`__tablename__`; `QUERIES` from `session.query/select` |
 | `vue` | `.vue` SFCs, `package.json` deps | `component` symbols per SFC; `IMPORTS` edges from used components in template |
 

package/dist/chunk-4ZV67SRY.js

@@ -0,0 +1,319 @@
+#!/usr/bin/env node
+
+// src/scope/protected.ts
+import fs2 from "fs";
+import path2 from "path";
+
+// src/db.ts
+import fs from "fs";
+import path from "path";
+import crypto from "crypto";
+import { createRequire } from "module";
+function loadDatabaseSync() {
+  const req = createRequire(import.meta.url);
+  const spec = "node:sqlite";
+  const m = req(spec);
+  return m.DatabaseSync;
+}
+var DATA_DIR_NAME = ".scopecairn";
+var DB_FILE_NAME = "scopecairn.db";
+var SCHEMA_VERSION = 6;
+function dataDir(repoRoot) {
+  return path.join(repoRoot, DATA_DIR_NAME);
+}
+function dbPath(repoRoot) {
+  return path.join(dataDir(repoRoot), DB_FILE_NAME);
+}
+function openDb(repoRoot) {
+  fs.mkdirSync(dataDir(repoRoot), { recursive: true });
+  const DatabaseSync = loadDatabaseSync();
+  const db = new DatabaseSync(dbPath(repoRoot));
+  db.exec(`
+    PRAGMA journal_mode = WAL;
+    PRAGMA foreign_keys = ON;
+    CREATE TABLE IF NOT EXISTS files (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      path TEXT NOT NULL UNIQUE,
+      language TEXT NOT NULL,
+      hash TEXT NOT NULL,
+      size INTEGER NOT NULL,
+      created_at TEXT NOT NULL DEFAULT (datetime('now')),
+      updated_at TEXT NOT NULL DEFAULT (datetime('now'))
+    );
+    CREATE TABLE IF NOT EXISTS symbols (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      file_id INTEGER NOT NULL REFERENCES files(id) ON DELETE CASCADE,
+      name TEXT NOT NULL,
+      type TEXT NOT NULL,
+      signature TEXT NOT NULL DEFAULT '',
+      start_line INTEGER NOT NULL DEFAULT 1,
+      end_line INTEGER NOT NULL DEFAULT 1
+    );
+    CREATE INDEX IF NOT EXISTS idx_symbols_file ON symbols(file_id);
+    CREATE INDEX IF NOT EXISTS idx_symbols_name ON symbols(name);
+    CREATE INDEX IF NOT EXISTS idx_symbols_type ON symbols(type);
+    CREATE TABLE IF NOT EXISTS relationships (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      source_id INTEGER NOT NULL REFERENCES symbols(id) ON DELETE CASCADE,
+      target_id INTEGER NOT NULL REFERENCES symbols(id) ON DELETE CASCADE,
+      relationship_type TEXT NOT NULL,
+      weight REAL NOT NULL DEFAULT 0.5,
+      confidence REAL NOT NULL DEFAULT 1.0
+    );
+    CREATE INDEX IF NOT EXISTS idx_rel_source ON relationships(source_id);
+    CREATE INDEX IF NOT EXISTS idx_rel_target ON relationships(target_id);
+    CREATE INDEX IF NOT EXISTS idx_rel_type ON relationships(relationship_type);
+    CREATE TABLE IF NOT EXISTS meta (
+      key TEXT PRIMARY KEY,
+      value TEXT NOT NULL
+    );
+    -- Fase 3: FTS5 symbol index (token match, bukan embedding).
+    CREATE VIRTUAL TABLE IF NOT EXISTS symbol_index USING fts5(
+      symbol_id UNINDEXED, tokens
+    );
+    CREATE TABLE IF NOT EXISTS tasks (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      description TEXT NOT NULL,
+      complexity TEXT NOT NULL DEFAULT '',
+      created_at TEXT NOT NULL DEFAULT (datetime('now')),
+      completed_at TEXT
+    );
+    CREATE TABLE IF NOT EXISTS task_context (
+      task_id INTEGER NOT NULL REFERENCES tasks(id) ON DELETE CASCADE,
+      symbol_id INTEGER NOT NULL REFERENCES symbols(id) ON DELETE CASCADE,
+      score REAL NOT NULL DEFAULT 0,
+      reason TEXT NOT NULL DEFAULT ''
+    );
+    CREATE INDEX IF NOT EXISTS idx_task_context_task ON task_context(task_id);
+    -- Fase 5: invocation log untuk compliance rate (AI-5, \xA718).
+    CREATE TABLE IF NOT EXISTS invocations (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      task_id INTEGER REFERENCES tasks(id) ON DELETE SET NULL,
+      command TEXT NOT NULL,
+      timestamp TEXT NOT NULL DEFAULT (datetime('now'))
+    );
+    CREATE INDEX IF NOT EXISTS idx_invocations_cmd ON invocations(command);
+    -- Graphify Engine: node centrality, community clustering, cycle cache.
+    CREATE TABLE IF NOT EXISTS node_metrics (
+      node_id INTEGER PRIMARY KEY,
+      pagerank REAL NOT NULL DEFAULT 0.0,
+      betweenness REAL NOT NULL DEFAULT 0.0,
+      in_degree INTEGER NOT NULL DEFAULT 0,
+      out_degree INTEGER NOT NULL DEFAULT 0,
+      updated_at TEXT NOT NULL DEFAULT (datetime('now')),
+      FOREIGN KEY(node_id) REFERENCES symbols(id) ON DELETE CASCADE
+    );
+    CREATE TABLE IF NOT EXISTS clusters (
+      node_id INTEGER PRIMARY KEY,
+      cluster_id INTEGER NOT NULL,
+      cluster_name TEXT,
+      modularity REAL,
+      FOREIGN KEY(node_id) REFERENCES symbols(id) ON DELETE CASCADE
+    );
+    CREATE INDEX IF NOT EXISTS idx_clusters_cid ON clusters(cluster_id);
+    CREATE TABLE IF NOT EXISTS cycles (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      cycle_hash TEXT UNIQUE,
+      length INTEGER NOT NULL DEFAULT 0,
+      nodes_json TEXT NOT NULL DEFAULT '[]',
+      created_at TEXT NOT NULL DEFAULT (datetime('now'))
+    );
+  `);
+  db.prepare(
+    `INSERT INTO meta(key, value) VALUES ('schema_version', ?)
+     ON CONFLICT(key) DO UPDATE SET value = excluded.value`
+  ).run(String(SCHEMA_VERSION));
+  for (const [table, column, ddl] of [
+    ["relationships", "evidence", "evidence TEXT NOT NULL DEFAULT 'EXTRACTED'"],
+    ["symbols", "doc", "doc TEXT NOT NULL DEFAULT ''"]
+  ]) {
+    const cols = db.prepare(`PRAGMA table_info(${table})`).all();
+    if (!cols.some((c) => c.name === column)) db.exec(`ALTER TABLE ${table} ADD COLUMN ${ddl}`);
+  }
+  db.exec(
+    `UPDATE relationships SET evidence = 'INFERRED'
+     WHERE relationship_type IN ('QUERIES','ROUTES_TO','TESTS') AND evidence = 'EXTRACTED'`
+  );
+  db.exec(
+    `UPDATE relationships SET evidence = 'AMBIGUOUS'
+     WHERE relationship_type = 'CALLS' AND confidence < 1.0 AND evidence = 'EXTRACTED'`
+  );
+  return db;
+}
+function hashContent(buf) {
+  return crypto.createHash("sha256").update(buf).digest("hex");
+}
+
+// src/scope/protected.ts
+var DEFAULT_PROTECTED_PATTERNS = [
+  "migrations/**",
+  "prisma/**",
+  "schema.prisma",
+  "*.sql",
+  "alembic/**",
+  ".env*",
+  "package.json",
+  "package-lock.json",
+  "pnpm-lock.yaml",
+  "yarn.lock",
+  "bun.lockb"
+];
+function globToRegExp(pattern) {
+  let re = "";
+  let i = 0;
+  while (i < pattern.length) {
+    const c = pattern[i];
+    if (c === "*") {
+      if (pattern[i + 1] === "*") {
+        if (pattern[i + 2] === "/") {
+          re += "(.*/)?";
+          i += 3;
+        } else {
+          re += ".*";
+          i += 2;
+        }
+      } else {
+        re += "[^/]*";
+        i++;
+      }
+    } else if (c === "?") {
+      re += "[^/]";
+      i++;
+    } else {
+      re += c.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+      i++;
+    }
+  }
+  return new RegExp(`^${re}$`);
+}
+function matchPattern(pattern, posixPath) {
+  const base = posixPath.split("/").pop() ?? posixPath;
+  if (pattern.endsWith("/")) {
+    const dir = pattern.slice(0, -1);
+    return posixPath === dir || posixPath.startsWith(dir + "/");
+  }
+  if (!pattern.includes("/")) {
+    return globToRegExp(pattern).test(base);
+  }
+  return globToRegExp(pattern).test(posixPath);
+}
+function loadProtectedPatterns(repoRoot) {
+  const p = path2.join(dataDir(repoRoot), "protected.yml");
+  if (!fs2.existsSync(p)) return [...DEFAULT_PROTECTED_PATTERNS];
+  try {
+    const patterns = [];
+    for (const line of fs2.readFileSync(p, "utf8").split("\n")) {
+      const t = line.trim();
+      if (!t || t.startsWith("#")) continue;
+      patterns.push(t);
+    }
+    return patterns.length > 0 ? patterns : [...DEFAULT_PROTECTED_PATTERNS];
+  } catch {
+    return [...DEFAULT_PROTECTED_PATTERNS];
+  }
+}
+function isProtected(posixPath, patterns = DEFAULT_PROTECTED_PATTERNS) {
+  let hit = false;
+  for (const p of patterns) {
+    if (p.startsWith("!")) {
+      if (matchPattern(p.slice(1), posixPath)) hit = false;
+    } else if (matchPattern(p, posixPath)) {
+      hit = true;
+    }
+  }
+  return hit;
+}
+var SECRET_PATTERNS = [
+  ".env",
+  ".env.*",
+  "*.pem",
+  "*.key",
+  "credentials.*",
+  "secrets.*"
+];
+function isSecretFile(posixPath) {
+  return SECRET_PATTERNS.some((p) => matchPattern(p, posixPath));
+}
+var META_EXTS = /* @__PURE__ */ new Set([
+  ".json",
+  ".yaml",
+  ".yml",
+  ".toml",
+  ".sql",
+  ".prisma",
+  ".cfg",
+  ".ini"
+]);
+var META_BASENAMES = /* @__PURE__ */ new Set([
+  "dockerfile",
+  "makefile",
+  "package.json"
+]);
+function isIndexableMetaFile(posixPath, patterns) {
+  if (isSecretFile(posixPath)) return false;
+  const base = (posixPath.split("/").pop() ?? "").toLowerCase();
+  if (META_BASENAMES.has(base)) return true;
+  const dot = base.lastIndexOf(".");
+  if (dot !== -1 && META_EXTS.has(base.slice(dot))) return true;
+  if (patterns ? isProtected(posixPath, patterns) : isProtected(posixPath)) return true;
+  return false;
+}
+function ensureProtectedFile(repoRoot) {
+  const dir = dataDir(repoRoot);
+  fs2.mkdirSync(dir, { recursive: true });
+  const p = path2.join(dir, "protected.yml");
+  if (!fs2.existsSync(p)) {
+    fs2.writeFileSync(
+      p,
+      `# ScopeCairn Protected patterns (FR-07). Satu pola per baris, \`!\` negasi.
+` + DEFAULT_PROTECTED_PATTERNS.join("\n") + `
+`
+    );
+  }
+}
+
+// src/scope/scope.ts
+function computeScope(highFiles, mediumFiles, testFiles, patterns) {
+  const required = [];
+  const optional = [];
+  const protectedFiles = [];
+  const seen = /* @__PURE__ */ new Set();
+  const place = (f) => {
+    if (seen.has(f)) return;
+    seen.add(f);
+    if (isProtected(f, patterns)) protectedFiles.push(f);
+    else if (highFiles.includes(f)) required.push(f);
+    else optional.push(f);
+  };
+  for (const f of highFiles) place(f);
+  for (const f of mediumFiles) place(f);
+  for (const t of testFiles) {
+    if (seen.has(t)) continue;
+    seen.add(t);
+    if (isProtected(t, patterns)) protectedFiles.push(t);
+    else optional.push(t);
+  }
+  return { required, optional, protected: protectedFiles };
+}
+function scopeBlock(scope) {
+  const fmt = (xs) => xs.length > 0 ? xs.join(", ") : "-";
+  return `## Scope
+Required: ${fmt(scope.required)}
+Optional: ${fmt(scope.optional)}
+Protected: ${fmt(scope.protected)}
+`;
+}
+
+export {
+  dataDir,
+  dbPath,
+  openDb,
+  hashContent,
+  matchPattern,
+  loadProtectedPatterns,
+  isProtected,
+  isIndexableMetaFile,
+  ensureProtectedFile,
+  computeScope,
+  scopeBlock
+};

package/dist/chunk-BTRFJORI.js

@@ -0,0 +1,217 @@
+#!/usr/bin/env node
+import {
+  computeScope,
+  loadProtectedPatterns,
+  scopeBlock
+} from "./chunk-4ZV67SRY.js";
+
+// src/scope/guard.ts
+var TASK_GUARD_RULES = [
+  "Ubah hanya file Required dan Optional; Protected perlu persetujuan user.",
+  "Jangan refactor, upgrade dependency, atau abstraksi prematur yang tak diminta.",
+  "Jangan tulis ulang kode berjalan; jangan tambah file/komentar tak perlu.",
+  "Berhenti saat acceptance criteria terpenuhi."
+];
+var DEFINITION_OF_DONE = [
+  "Fungsionalitas yang diminta terimplementasi",
+  "Test relevan lulus",
+  "Tidak ada file berubah tanpa alasan",
+  "Tidak ada refactoring tak terkait",
+  "Acceptance criteria terpenuhi",
+  "Index dimutakhirkan (`scopecairn scan`)"
+];
+function guardBlock() {
+  return `## Task Guard
+${TASK_GUARD_RULES.map((r) => `- ${r}`).join("\n")}
+
+## Definition of Done
+${DEFINITION_OF_DONE.map((d) => `- [ ] ${d}`).join("\n")}
+`;
+}
+
+// src/retrieval/contextBuilder.ts
+function buildContext(db, task, result, cls, opts) {
+  const complex = cls.complexity === "COMPLEX" || opts?.escalate === true;
+  if (!complex) {
+    const files = [];
+    for (const r of result.ranked) {
+      if (!files.includes(r.file)) files.push(r.file);
+      if (files.length >= 3) break;
+    }
+    const cand = files.length > 0 ? files.map((f) => `\`${f}\``).join(", ") : "pencarian langsung (tidak ada simbol cocok di index)";
+    return {
+      markdown: `# Task Context
+
+## Task
+${task}
+
+## Complexity
+SIMPLE (${cls.reasons.join("; ")})
+
+Task sederhana. Gunakan pencarian langsung. Kandidat: ${cand}
+`,
+      high: [],
+      medium: [],
+      tests: [],
+      dependencies: []
+    };
+  }
+  const ranked = result.ranked;
+  const hi = ranked.filter((r) => r.score >= 0.3).slice(0, 10);
+  const med = ranked.filter((r) => r.score >= 0.15 && r.score < 0.3).slice(0, 10);
+  const highFiles = [...new Set(hi.map((r) => r.file))];
+  const medFiles = [...new Set(med.map((r) => r.file))].filter((f) => !highFiles.includes(f));
+  const deps = [];
+  if (highFiles.length > 0) {
+    const ph = highFiles.map(() => "?").join(",");
+    try {
+      const rows = db.prepare(
+        `SELECT DISTINCT f1.path AS a, f2.path AS b
+           FROM relationships r
+           JOIN symbols s1 ON s1.id = r.source_id
+           JOIN symbols s2 ON s2.id = r.target_id
+           JOIN files f1 ON f1.id = s1.file_id
+           JOIN files f2 ON f2.id = s2.file_id
+           WHERE r.relationship_type IN ('IMPORTS','CALLS')
+             AND f1.path IN (${ph}) AND f2.path IN (${ph}) AND f1.path != f2.path
+           LIMIT 10`
+      ).all(...highFiles, ...highFiles);
+      for (const r of rows) deps.push(`${r.a} \u2192 ${r.b}`);
+    } catch {
+    }
+  }
+  const isTestFileLike = (p) => p.includes(".test.") || p.includes(".spec.") || p.includes("__tests__") || (p.split("/").pop() ?? "").startsWith("test_");
+  const testSet = /* @__PURE__ */ new Set();
+  if (highFiles.length > 0) {
+    const ph = highFiles.map(() => "?").join(",");
+    try {
+      const rows = db.prepare(
+        `SELECT DISTINCT f2.path AS t
+           FROM relationships r
+           JOIN symbols s1 ON s1.id = r.source_id
+           JOIN symbols s2 ON s2.id = r.target_id
+           JOIN files f1 ON f1.id = s1.file_id
+           JOIN files f2 ON f2.id = s2.file_id
+           WHERE r.relationship_type = 'TESTS'
+             AND (f1.path IN (${ph}) OR f2.path IN (${ph}))`
+      ).all(...highFiles, ...highFiles);
+      for (const r of rows) testSet.add(r.t);
+    } catch {
+    }
+    try {
+      const symRows = db.prepare(
+        `SELECT s.id AS id FROM symbols s
+           JOIN files f ON f.id = s.file_id
+           WHERE f.path IN (${ph}) LIMIT 50`
+      ).all(...highFiles);
+      const targetIds = symRows.map((r) => r.id);
+      if (targetIds.length > 0) {
+        const inClause = targetIds.map(() => "?").join(",");
+        const callerRows = db.prepare(
+          `SELECT DISTINCT s.file_id AS fid, f.path AS p
+             FROM relationships r
+             JOIN symbols s ON s.id = r.source_id
+             JOIN files f ON f.id = s.file_id
+             WHERE r.target_id IN (${inClause})`
+        ).all(...targetIds);
+        const intermediateIds = [];
+        for (const c of callerRows) {
+          if (isTestFileLike(c.p)) testSet.add(c.p);
+        }
+        try {
+          const idRows = db.prepare(`SELECT DISTINCT r.source_id AS id FROM relationships r WHERE r.target_id IN (${inClause}) LIMIT 100`).all(...targetIds);
+          intermediateIds.push(...idRows.map((r) => r.id));
+        } catch {
+        }
+        if (intermediateIds.length > 0) {
+          const interClause = intermediateIds.map(() => "?").join(",");
+          const indirectRows = db.prepare(
+            `SELECT DISTINCT f.path AS p
+               FROM relationships r
+               JOIN symbols s ON s.id = r.source_id
+               JOIN files f ON f.id = s.file_id
+               WHERE r.target_id IN (${interClause})`
+          ).all(...intermediateIds);
+          for (const r of indirectRows) {
+            if (isTestFileLike(r.p)) testSet.add(r.p);
+          }
+        }
+      }
+    } catch {
+    }
+  }
+  for (const r of ranked) {
+    if (isTestFileLike(r.file)) testSet.add(r.file);
+  }
+  const tests = [...testSet].slice(0, 10);
+  const symLine = (r) => `- ${r.name} (${r.type}) \u2014 \`${r.file}\` [${r.score.toFixed(2)} ${r.reason}]`;
+  let hotspots = [];
+  let cycleWarn = "";
+  try {
+    const ids = ranked.slice(0, 20).map((r) => r.id);
+    if (ids.length > 0) {
+      const ph = ids.map(() => "?").join(",");
+      const prRows = db.prepare(`SELECT node_id AS id, pagerank AS pr FROM node_metrics WHERE node_id IN (${ph})`).all(...ids);
+      const pr = new Map(prRows.map((r) => [r.id, r.pr]));
+      const boosted = ranked.slice(0, 20).map((r) => ({ r, boost: r.score + (pr.get(r.id) ?? 0) * 2 })).sort((a, b) => b.boost - a.boost).slice(0, 5);
+      hotspots = boosted.map(
+        (b) => `- ${b.r.name} (${b.r.type}) \u2014 \`${b.r.file}\` [pr=${(pr.get(b.r.id) ?? 0).toFixed(4)}]`
+      );
+      const cycRows = db.prepare(`SELECT nodes_json AS js FROM cycles`).all();
+      const inCycle = /* @__PURE__ */ new Set();
+      for (const c of cycRows) {
+        try {
+          for (const n of JSON.parse(c.js)) inCycle.add(n);
+        } catch {
+        }
+      }
+      const trapped = ranked.slice(0, 10).filter((r) => inCycle.has(r.id));
+      if (trapped.length > 0) {
+        cycleWarn = `
+## Circular dependency warning
+` + trapped.slice(0, 5).map((r) => `- ${r.name} (\`${r.file}\`) is inside a dependency cycle`).join("\n") + `
+`;
+      }
+    }
+  } catch {
+  }
+  const scope = computeScope(
+    highFiles,
+    medFiles,
+    tests,
+    loadProtectedPatterns(opts?.repoRoot ?? ".")
+  );
+  const md = `# Task Context
+
+## Task
+${task}
+
+## Complexity
+${cls.complexity} (${cls.reasons.join("; ")})
+
+## Relevant Files
+### HIGH
+${highFiles.map((f) => `- ${f}`).join("\n") || "-"}
+### MEDIUM
+${medFiles.map((f) => `- ${f}`).join("\n") || "-"}
+
+## Key Symbols
+${hi.slice(0, 8).map(symLine).join("\n") || "-"}
+
+` + (hotspots.length > 0 ? `## Critical hotspots (PageRank)
+${hotspots.join("\n")}
+
+` : ``) + `## Dependencies
+${deps.map((d) => `- ${d}`).join("\n") || "-"}
+
+## Related Tests
+${tests.map((t) => `- ${t}`).join("\n") || "-"}
+
+` + cycleWarn + scopeBlock(scope) + `
+` + guardBlock();
+  return { markdown: md, high: highFiles, medium: medFiles, tests, dependencies: deps };
+}
+
+export {
+  buildContext
+};