@akanjs/devkit 2.4.2-rc.2 → 3.0.0-alpha.0

package/abstractCompactor.ts

@@ -0,0 +1,112 @@
+import { Logger } from "akanjs/common";
+import chalk from "chalk";
+import { AbstractDoc, type AbstractKind } from "./abstractDoc";
+import { AiSession } from "./aiEditor";
+import type { SysExecutor } from "./executors";
+
+export interface AbstractCompactOptions {
+  module?: string | null;
+  minLines?: number;
+  interactive?: boolean;
+}
+
+export interface AbstractCompactReport {
+  path: string;
+  beforeLines: number;
+  afterLines: number;
+  status: "compacted" | "unchanged" | "failed";
+}
+
+/** Rewrites bloated `*.abstract.md` files down to the invariants their source files cannot show. */
+export class AbstractCompactor {
+  static readonly #reviewRequest = `Review the compacted file you just wrote against the original.
+- Did you drop an invariant, a security reason, or a workflow step that the source files cannot show by themselves? Restore it.
+- Did you keep anything that only restates code, scaffold wording, or history? Remove it.
+- Is it in the same language as the original, within the line budget, and one short line per bullet?
+Respond with exactly one \`\`\`markdown code block holding the corrected file and nothing else. If nothing needs to change, repeat the file unchanged.`;
+
+  #sys: SysExecutor;
+  #minLines: number;
+  #interactive: boolean;
+  constructor(
+    sys: SysExecutor,
+    { minLines = AbstractDoc.compactMinLines, interactive = false }: AbstractCompactOptions = {},
+  ) {
+    this.#sys = sys;
+    this.#minLines = minLines;
+    this.#interactive = interactive;
+  }
+  async compactAll({ module }: { module?: string | null } = {}) {
+    const docs = await AbstractDoc.findAll(this.#sys, { module });
+    const targets = docs.filter((doc) => doc.lineCount > this.#minLines);
+    const reports: AbstractCompactReport[] = [];
+    // One file at a time: each doc gets its own AI session, and parallel runs would interleave the
+    // streamed response with each other and with the interactive confirm prompt.
+    for (const doc of targets) reports.push(await this.compact(doc));
+    return { scanned: docs.length, reports };
+  }
+  async compact(doc: AbstractDoc): Promise<AbstractCompactReport> {
+    const session = new AiSession("compactAbstract", {
+      workspace: this.#sys.workspace,
+      cacheKey: `${this.#sys.name}-${doc.moduleName}`,
+    });
+    const approve = !this.#interactive;
+    const compacted = await session.editMarkdown(this.#request(doc), { approve });
+    const reviewed = await session.editMarkdown(AbstractCompactor.#reviewRequest, { approve });
+    // The review answers in prose when it finds nothing to fix, so the first compaction is the fallback.
+    const next = [reviewed, compacted]
+      .map((candidate) => candidate.trim())
+      .find((candidate) => doc.canReplaceWith(candidate));
+    const beforeLines = doc.lineCount;
+    if (!next) {
+      Logger.rawLog(chalk.yellow(`${doc.path}: the editor returned no shorter abstract, keeping the current file`));
+      return { path: doc.path, beforeLines, afterLines: beforeLines, status: "failed" };
+    }
+    if (next === doc.content.trim())
+      return { path: doc.path, beforeLines, afterLines: beforeLines, status: "unchanged" };
+    const content = `${next}\n`;
+    await this.#sys.writeFile(doc.path, content);
+    return { path: doc.path, beforeLines, afterLines: AbstractDoc.lineCountOf(content), status: "compacted" };
+  }
+  #targetShape(kind: AbstractKind) {
+    if (kind === "other")
+      return "  - keep the headings that still carry information and drop the rest; do not impose a new structure";
+    return [
+      "  - `# <name> Abstract` title line",
+      "  - one declarative sentence naming what this module owns",
+      "  - `## Rules` — two to five bullets, each an invariant the code cannot show by itself",
+      "  - optional `## Workflow` — the lifecycle as an arrow chain (`draft -> signed -> active`) or a few bullets",
+    ].join("\n");
+  }
+  #request(doc: AbstractDoc) {
+    return `You are compacting an Akan.js abstract file.
+
+An abstract is the summary a coding agent reads before changing a module. Repeated edits have made this one
+bloated, and it has to shrink back to what the source files cannot show by themselves.
+
+# Target file
+${this.#sys.type}s/${this.#sys.name}/${doc.path} (${doc.kind} module "${doc.moduleName}", ${doc.lineCount} lines)
+
+# Source files in the same folder
+${doc.siblingFiles.join(", ") || "none"}
+
+# Current content
+\`\`\`markdown
+${doc.content}
+\`\`\`
+
+# Rules for the compacted file
+- Write it in the SAME language as the current content. Never translate.
+- Keep every invariant, constraint, security reason, and workflow step that the source files cannot show by
+  themselves. Merge duplicates instead of dropping either one.
+- Delete what the code already states: field lists, types, labels, signatures, file lists, and imports.
+- Delete scaffold and placeholder wording, changelog or migration history, TODOs, and any instruction about
+  reading or updating this file.
+- Never invent a rule that the current content does not state.
+- Keep every bullet to one short line, and stay under ${AbstractDoc.compactMinLines} lines in total.
+- Shape:
+${this.#targetShape(doc.kind)}
+
+Respond with exactly one \`\`\`markdown code block holding the whole new file and nothing else.`;
+  }
+}

package/abstractDoc.test.ts

@@ -0,0 +1,78 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { AbstractDoc } from "./abstractDoc";
+import { AppExecutor, WorkspaceExecutor } from "./executors";
+
+const tempRoots: string[] = [];
+
+const makeApp = async (files: Record<string, string>) => {
+  const root = await mkdtemp(path.join(os.tmpdir(), "akan-abstract-doc-"));
+  tempRoots.push(root);
+  const appName = "abstractDemo";
+  for (const [filePath, content] of Object.entries(files)) {
+    const absolutePath = path.join(root, "apps", appName, filePath);
+    await mkdir(path.dirname(absolutePath), { recursive: true });
+    await writeFile(absolutePath, content);
+  }
+  const workspace = WorkspaceExecutor.fromRoot({ workspaceRoot: root, repoName: "repo" });
+  return AppExecutor.from(workspace, appName);
+};
+
+afterEach(async () => {
+  await Promise.all(tempRoots.splice(0).map((root) => rm(root, { recursive: true, force: true })));
+});
+
+describe("AbstractDoc.kindOf", () => {
+  test("reads the module kind off the sys-relative path", () => {
+    expect(AbstractDoc.kindOf("lib/user/user.abstract.md")).toBe("domain");
+    expect(AbstractDoc.kindOf("lib/_payment/payment.abstract.md")).toBe("service");
+    expect(AbstractDoc.kindOf("lib/__scalar/money/money.abstract.md")).toBe("scalar");
+    expect(AbstractDoc.kindOf("ui/Editor/editor.abstract.md")).toBe("other");
+    expect(AbstractDoc.kindOf("lib/user/nested/user.abstract.md")).toBe("other");
+    expect(AbstractDoc.kindOf("lib/__scalar/money.abstract.md")).toBe("other");
+  });
+});
+
+describe("AbstractDoc.canReplaceWith", () => {
+  const doc = new AbstractDoc("lib/user/user.abstract.md", ["# user Abstract", "a", "b", "c", "d", ""].join("\n"), []);
+
+  test("accepts a shorter markdown file", () => {
+    expect(doc.canReplaceWith("# user Abstract\nowns users.\n## Rules\n- one rule")).toBe(true);
+  });
+
+  test("rejects prose, a longer file, and a stub", () => {
+    expect(doc.canReplaceWith("The abstract already meets the requirements.")).toBe(false);
+    expect(doc.canReplaceWith(["# user Abstract", "a", "b", "c", "d", "e"].join("\n"))).toBe(false);
+    expect(doc.canReplaceWith("# user Abstract\nowns users.")).toBe(false);
+  });
+});
+
+describe("AbstractDoc.findAll", () => {
+  test("finds abstracts across facet folders and filters by module", async () => {
+    const app = await makeApp({
+      "lib/user/user.abstract.md": "# user Abstract\n",
+      "lib/user/user.constant.ts": "export class User {}\n",
+      "lib/_payment/payment.abstract.md": "# payment Abstract\n",
+      "lib/__scalar/money/money.abstract.md": "# money Abstract\n",
+      "ui/Editor/editor.abstract.md": "# Editor Abstract\n",
+      "lib/user/user.document.ts": "export class UserModel {}\n",
+    });
+
+    const docs = await AbstractDoc.findAll(app);
+    expect(docs.map((doc) => doc.path)).toEqual([
+      "lib/__scalar/money/money.abstract.md",
+      "lib/_payment/payment.abstract.md",
+      "lib/user/user.abstract.md",
+      "ui/Editor/editor.abstract.md",
+    ]);
+    expect(docs.map((doc) => doc.kind)).toEqual(["scalar", "service", "domain", "other"]);
+
+    const [userDoc] = await AbstractDoc.findAll(app, { module: "user" });
+    expect(userDoc?.siblingFiles.sort()).toEqual(["user.constant.ts", "user.document.ts"]);
+
+    const [serviceDoc] = await AbstractDoc.findAll(app, { module: "_payment" });
+    expect(serviceDoc?.path).toBe("lib/_payment/payment.abstract.md");
+  });
+});

package/abstractDoc.ts

@@ -0,0 +1,70 @@
+import type { SysExecutor } from "./executors";
+
+export type AbstractKind = "domain" | "service" | "scalar" | "other";
+
+/** One `*.abstract.md` file: the agent-facing summary a module carries next to its source. */
+export class AbstractDoc {
+  static readonly suffix = ".abstract.md";
+  /** `akan quality` warns above this and points at `akan compact`. */
+  static readonly maxLines = 300;
+  /** `akan compact` floor, and the line budget it compacts down to, so a compacted file is never a candidate again. */
+  static readonly compactMinLines = 40;
+  // Abstracts only live in facet folders; globbing the sys root instead would walk node_modules.
+  static readonly #facetRoots = "{lib,ui,webkit,srvkit,common,plugin}";
+
+  static isAbstractPath(filePath: string) {
+    return filePath.endsWith(AbstractDoc.suffix);
+  }
+  static lineCountOf(content: string) {
+    return content.split(/\r?\n/).length;
+  }
+  /** Module kind read off the sys-relative path; anything outside a `lib/` module folder is "other". */
+  static kindOf(filePath: string): AbstractKind {
+    const [root, folder, ...rest] = filePath.split("/");
+    if (root !== "lib" || !folder) return "other";
+    if (folder === "__scalar") return rest.length === 2 ? "scalar" : "other";
+    if (rest.length !== 1) return "other";
+    return folder.startsWith("_") ? "service" : "domain";
+  }
+  static async findAll(sys: SysExecutor, { module }: { module?: string | null } = {}) {
+    const filePaths = (await sys.getAllFiles(`${AbstractDoc.#facetRoots}/**/*${AbstractDoc.suffix}`)).sort();
+    const docs = await Promise.all(filePaths.map((filePath) => AbstractDoc.read(sys, filePath)));
+    if (!module) return docs;
+    return docs.filter((doc) => doc.moduleName === module || doc.folderName === module);
+  }
+  static async read(sys: SysExecutor, filePath: string) {
+    const dirPath = filePath.split("/").slice(0, -1).join("/");
+    const [content, folderFiles] = await Promise.all([sys.readFile(filePath), sys.readdir(dirPath)]);
+    return new AbstractDoc(
+      filePath,
+      content,
+      folderFiles.filter((fileName) => !AbstractDoc.isAbstractPath(fileName)),
+    );
+  }
+
+  constructor(
+    readonly path: string,
+    readonly content: string,
+    readonly siblingFiles: string[],
+  ) {}
+  get kind() {
+    return AbstractDoc.kindOf(this.path);
+  }
+  get folderName() {
+    return this.path.split("/").at(-2) ?? "";
+  }
+  get moduleName() {
+    return (this.path.split("/").at(-1) ?? "").slice(0, -AbstractDoc.suffix.length);
+  }
+  get lineCount() {
+    return AbstractDoc.lineCountOf(this.content);
+  }
+  // An AI editor answers in prose when it decides nothing needs changing, and that prose would silently
+  // replace the abstract — so a candidate must look like a markdown file and be shorter than what it replaces.
+  canReplaceWith(candidate: string) {
+    const next = candidate.trim();
+    if (!next.startsWith("#")) return false;
+    const lineCount = AbstractDoc.lineCountOf(next);
+    return lineCount >= 3 && lineCount < this.lineCount;
+  }
+}

package/agentsIndex.test.ts

@@ -0,0 +1,84 @@
+import { describe, expect, test } from "bun:test";
+import { mkdir, mkdtemp, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import {
+  AGENT_BLOCK_END,
+  AGENT_BLOCK_START,
+  collectScopeRecipeSources,
+  extractAgentBlock,
+  renderRecipeEntries,
+  renderScopeAgentBlock,
+  renderScopeAgentsMd,
+  upsertAgentBlock,
+} from "./agentsIndex";
+import type { RecipeInfo } from "./recipeScanner";
+
+const button: RecipeInfo = {
+  name: "buttonRecipe",
+  importFrom: "akanjs/ui",
+  variants: { variant: ["primary", "ghost"], size: ["sm", "md"] },
+  defaultVariants: { variant: "primary", size: "md" },
+  doc: "버튼 look",
+};
+const appCard: RecipeInfo = { name: "appCard", importFrom: "@apps/minimal/ui", variants: { tone: ["muted", "glass"] } };
+
+describe("renderRecipeEntries", () => {
+  test("groups by import path and marks defaults", () => {
+    const entries = renderRecipeEntries([button, appCard]);
+    expect(entries).toContain("Import from `akanjs/ui`:");
+    expect(entries).toContain("Import from `@apps/minimal/ui`:");
+    expect(entries).toContain("`buttonRecipe`(variant: primary*|ghost · size: sm|md*) — 버튼 look");
+    expect(entries).toContain("`appCard`(tone: muted|glass)");
+  });
+});
+
+describe("renderScopeAgentBlock", () => {
+  test("carries the sync/lint contract and the scope's entries", () => {
+    const block = renderScopeAgentBlock({ type: "app", name: "minimal" }, [appCard]);
+    expect(block).toContain("## Recipes In Scope");
+    expect(block).toContain("akan sync minimal");
+    expect(block).toContain("akan lint minimal");
+    expect(block).toContain("`appCard`");
+  });
+  test("empty scope points to authoring instead of listing nothing", () => {
+    const block = renderScopeAgentBlock({ type: "lib", name: "util" }, []);
+    expect(block).toContain("No scope recipes yet");
+    expect(block).toContain("libs/util/ui/Recipe/<name>.ts");
+  });
+});
+
+describe("upsertAgentBlock / extractAgentBlock", () => {
+  test("round-trips: fresh file → replace block → extract equals block", () => {
+    const fresh = renderScopeAgentsMd({ type: "app", name: "minimal" }, "OLD");
+    expect(extractAgentBlock(fresh)).toBe("OLD");
+    const updated = upsertAgentBlock(
+      fresh.replace("markers freely.", "markers freely.\n\nMy hand-written note."),
+      "NEW",
+    );
+    expect(extractAgentBlock(updated)).toBe("NEW");
+    expect(updated).toContain("My hand-written note.");
+    expect(updated).not.toContain("OLD");
+  });
+  test("appends markers to a file that has none", () => {
+    const updated = upsertAgentBlock("# hand-written\n\ncontent\n", "BLOCK");
+    expect(updated).toContain("# hand-written");
+    expect(updated.indexOf(AGENT_BLOCK_START)).toBeLessThan(updated.indexOf("BLOCK"));
+    expect(updated.trimEnd().endsWith(AGENT_BLOCK_END)).toBe(true);
+  });
+});
+
+describe("collectScopeRecipeSources", () => {
+  test("collects own + dependency lib recipes, never the framework's", async () => {
+    const root = await mkdtemp(path.join(tmpdir(), "agents-index-"));
+    const write = async (rel: string, content: string) => {
+      await mkdir(path.dirname(path.join(root, rel)), { recursive: true });
+      await writeFile(path.join(root, rel), content);
+    };
+    await write("apps/minimal/ui/Recipe/appCard.ts", `export const appCard = recipe(tv({ base: "x" }));`);
+    await write("libs/shared/ui/Recipe/panel.ts", `export const panelRecipe = recipe(tv({ base: "y" }));`);
+    await write("pkgs/akanjs/ui/recipe/buttonRecipe.ts", `export const buttonRecipe = recipe(tv({ base: "z" }));`);
+    const sources = await collectScopeRecipeSources(root, { type: "app", name: "minimal" }, ["shared"]);
+    expect(sources.map((source) => source.importFrom).sort()).toEqual(["@apps/minimal/ui", "@libs/shared/ui"]);
+  });
+});

package/agentsIndex.ts

@@ -0,0 +1,146 @@
+import type { RecipeInfo, RecipeSource } from "./recipeScanner";
+
+// recipeScanner 는 상단에서 typescript(~65MB)를 끌어온다. 이 모듈은 executors(CLI 엔트리 그래프)에
+// 상주하므로 스캔 스택은 첫 사용 시점에 지연 로드한다 — 정적 import 로 되돌리면 entryModuleGraph 테스트가 깨진다.
+let recipeScannerLoad: Promise<typeof import("./recipeScanner")> | null = null;
+const loadRecipeScanner = () => (recipeScannerLoad ??= import("./recipeScanner"));
+
+/**
+ * agentsIndex — 스코프별 에이전트 색인의 단일 렌더러.
+ *
+ * 색인은 소유 경계로 쪼갠다: 루트 AGENTS.md 는 프레임워크(akanjs/ui) 레시피만 싣고, 각 앱/lib 은
+ * 자기 스코프에서 import 가능한 레시피(own + 의존 lib)를 자기 AGENTS.md 에 싣는다. 항상 로드되는
+ * 컨텍스트가 앱 수에 비례해 커지는 것과, import 불가능한 이웃 앱 레시피가 환상을 유발하는 것을 막는다.
+ *
+ * 신선도는 두 지점이 보장한다: `SysExecutor.scan(write)` 가 재생성하고(akan sync/build/start 가 전부
+ * 지나가는 길목), `akan lint` 가 스캔 결과와 커밋된 블록을 비교해 stale 이면 실패시킨다.
+ */
+
+export const AGENT_BLOCK_START = "<!-- akan:agent:start -->";
+export const AGENT_BLOCK_END = "<!-- akan:agent:end -->";
+
+export interface AgentsIndexScope {
+  type: "app" | "lib";
+  name: string;
+}
+
+/** Replace the content between the akan:agent markers, preserving everything else; append when absent. */
+export const upsertAgentBlock = (existing: string, block: string): string => {
+  const managed = `${AGENT_BLOCK_START}\n${block}\n${AGENT_BLOCK_END}`;
+  const startIndex = existing.indexOf(AGENT_BLOCK_START);
+  const endIndex = existing.indexOf(AGENT_BLOCK_END);
+  if (startIndex >= 0 && endIndex > startIndex) {
+    return `${existing.slice(0, startIndex)}${managed}${existing.slice(endIndex + AGENT_BLOCK_END.length)}`;
+  }
+  return `${existing.replace(/\s*$/, "")}\n\n${managed}\n`;
+};
+
+/** The content between the akan:agent markers, or null when the file carries no managed block. */
+export const extractAgentBlock = (content: string): string | null => {
+  const startIndex = content.indexOf(AGENT_BLOCK_START);
+  const endIndex = content.indexOf(AGENT_BLOCK_END);
+  if (startIndex < 0 || endIndex <= startIndex) return null;
+  return content.slice(startIndex + AGENT_BLOCK_START.length, endIndex).trim();
+};
+
+// Variant signature — the full consumption contract, so an agent never has to open the recipe
+// file (and pull its css bodies into context) just to call one. `*` = default, `key?` = boolean flag.
+const signatureOf = (recipe: RecipeInfo): string => {
+  const entries = Object.entries(recipe.variants);
+  if (entries.length === 0) return "";
+  const parts = entries.map(([key, values]) => {
+    if (values.length === 1 && values[0] === "true") return `${key}?`;
+    const def = recipe.defaultVariants?.[key];
+    return `${key}: ${values.map((value) => (value === def ? `${value}*` : value)).join("|")}`;
+  });
+  return `(${parts.join(" · ")})`;
+};
+
+/** Recipes grouped by import path as markdown list blocks — the shared body of every recipe index. */
+export const renderRecipeEntries = (recipes: RecipeInfo[]): string => {
+  const groups = new Map<string, RecipeInfo[]>();
+  for (const recipe of recipes) groups.set(recipe.importFrom, [...(groups.get(recipe.importFrom) ?? []), recipe]);
+  return [...groups.entries()]
+    .map(([importFrom, list]) => {
+      const items = list
+        .sort((a, b) => a.name.localeCompare(b.name))
+        .map((recipe) => `- \`${recipe.name}\`${signatureOf(recipe)}${recipe.doc ? ` — ${recipe.doc}` : ""}`)
+        .join("\n");
+      return `Import from \`${importFrom}\`:\n${items}`;
+    })
+    .join("\n\n");
+};
+
+/**
+ * Every recipe source importable from the scope: its own `ui/Recipe/` plus each dependency lib's.
+ * Framework recipes are excluded on purpose — they live in the root AGENTS.md, valid for every scope.
+ */
+export const collectScopeRecipeSources = async (
+  workspaceRoot: string,
+  scope: AgentsIndexScope,
+  libDeps: string[],
+): Promise<RecipeSource[]> => {
+  const { collectRecipeSources } = await loadRecipeScanner();
+  const sources: RecipeSource[] = [
+    ...(await collectRecipeSources(
+      `${workspaceRoot}/${scope.type}s/${scope.name}/ui`,
+      `@${scope.type}s/${scope.name}/ui`,
+    )),
+  ];
+  for (const lib of [...new Set(libDeps)].sort()) {
+    if (scope.type === "lib" && lib === scope.name) continue;
+    sources.push(...(await collectRecipeSources(`${workspaceRoot}/libs/${lib}/ui`, `@libs/${lib}/ui`)));
+  }
+  return sources;
+};
+
+/** Collect + scan in one call, so consumers need no value import of the scanner stack. */
+export const scanScopeRecipes = async (
+  workspaceRoot: string,
+  scope: AgentsIndexScope,
+  libDeps: string[],
+): Promise<RecipeInfo[]> => {
+  const { scanRecipes } = await loadRecipeScanner();
+  return scanRecipes(await collectScopeRecipeSources(workspaceRoot, scope, libDeps));
+};
+
+/** The managed block of a scope AGENTS.md — deterministic, so lint can compare it against a re-scan. */
+export const renderScopeAgentBlock = (scope: AgentsIndexScope, recipes: RecipeInfo[]): string => {
+  const scopePath = `${scope.type}s/${scope.name}`;
+  const intro = `## Recipes In Scope
+
+UI recipes importable from \`${scopePath}\` code, **in addition to** the framework recipes indexed in the root
+\`AGENTS.md\` \`## Recipes\`. Same contract: import by exact name, then \`<name>(variants?, className?)\` — the second
+arg merges internally and takes an array too, so never wrap it in \`cn()\`. \`*\` marks the default, \`key?\` is a
+boolean flag. Do not guess recipe names or import paths; this index is regenerated by \`akan sync ${scope.name}\`
+and verified by \`akan lint ${scope.name}\`.`;
+  if (recipes.length === 0) {
+    return `${intro}
+
+No scope recipes yet. Before inlining a repeated surface (card, box, tile, …), reuse a framework recipe from the
+root \`AGENTS.md\` or author one as \`${scopePath}/ui/Recipe/<name>.ts\` (one recipe per file, re-exported from that
+folder's \`index.ts\`) — see the \`recipeRule\` guideline.`;
+  }
+  return `${intro}
+
+${renderRecipeEntries(recipes)}`;
+};
+
+/** A fresh scope AGENTS.md: a short hand-editable header around the managed block. */
+export const renderScopeAgentsMd = (scope: AgentsIndexScope, block: string): string => `# ${scope.name} — Agent Guide
+
+Scoped guide for coding agents working in \`${scope.type}s/${scope.name}\`. Workspace-wide conventions live in the
+root \`AGENTS.md\`; this file carries what is importable from this ${scope.type === "app" ? "app" : "library"}. The
+section between the \`akan:agent\` markers is regenerated by \`akan sync ${scope.name}\`; edit anything outside the
+markers freely.
+
+${AGENT_BLOCK_START}
+${block}
+${AGENT_BLOCK_END}
+`;
+
+/** Claude Code reads nested CLAUDE.md files as it works under a directory; keep it a thin pointer. */
+export const renderScopeClaudeMd = (scope: AgentsIndexScope): string => `# ${scope.name} — Claude Code Guide
+
+@AGENTS.md
+`;

package/akanContext.ts

@@ -3,6 +3,7 @@ import path from "node:path";
 import { capitalize } from "akanjs/common";
 import { AppExecutor, LibExecutor, type SysExecutor, type WorkspaceExecutor } from "./executors";
 import { FileSys } from "./fileSys";
+import { collectRecipeSources, findInlineRecipeDuplicates, scanRecipes } from "./recipeScanner";
 import type { PackageJson } from "./types";
 import {
   type GeneratedSyncState,
@@ -313,6 +314,9 @@ const constantFieldNames = (content: string) =>
   [...content.matchAll(/\b([A-Za-z_$][\w$]*)\s*:\s*field\(/g)].map((match) => match[1]).filter(Boolean);
 
 const appRootAllowFiles = new Set([
+  // 스코프 에이전트 가이드 — scan(write) 이 유지 (agentsIndex.ts); scanInfo.ts 의 appRootAllowedFiles 와 동기
+  "AGENTS.md",
+  "CLAUDE.md",
   "akan.app.json",
   "akan.config.ts",
   "capacitor.config.ts",
@@ -752,6 +756,124 @@ export class AkanContextAnalyzer {
       }
     }
 
+    // Recipe SSOT advisory (항상 warning — 차단하지 않음): recipe 지문이 인라인 className 으로 재작성된
+    // 곳의 추이를 보이게 한다. 유입이 실제로 재발하면 그때 lint 승격을 검토한다 — 증거 기반 에스컬레이션.
+    for (const sys of [...context.apps, ...context.libs]) {
+      const sources = await collectRecipeSources(path.join(workspace.workspaceRoot, sys.path, "ui"), "ui");
+      if (sources.length === 0) continue;
+      const recipes = scanRecipes(sources);
+      const files: { path: string; content: string }[] = [];
+      const glob = new Bun.Glob("**/*.tsx");
+      for await (const abs of glob.scan({ cwd: path.join(workspace.workspaceRoot, sys.path), absolute: true })) {
+        if (/[\\/](node_modules|\.akan|dist)[\\/]|[\\/]v1[\\/]/.test(abs) || /\.(test|spec)\.tsx$/.test(abs)) continue;
+        files.push({
+          path: abs,
+          content: await Bun.file(abs)
+            .text()
+            .catch(() => ""),
+        });
+      }
+      const duplicates = findInlineRecipeDuplicates(recipes, files);
+      if (duplicates.length === 0) continue;
+      const preview = duplicates
+        .slice(0, 3)
+        .map((duplicate) => `${path.relative(workspace.workspaceRoot, duplicate.path)}:${duplicate.line}`)
+        .join(", ");
+      diagnostics.push({
+        severity: "warning",
+        code: "recipe-inline-duplicate",
+        path: path.join(sys.path, "ui/Recipe"),
+        message: `${sys.name}: ${duplicates.length} inline className(s) re-author a recipe fingerprint (${preview}${duplicates.length > 3 ? ", …" : ""}) — consume the recipe instead.`,
+      });
+    }
+
+    // Recipe index freshness. The recipe indexes are generated and read as authoritative — a recipe missing
+    // from its index gets re-invented inline, and a name lingering in it gets imported and fails. The index is
+    // split by ownership: the root AGENTS.md `## Recipes` lists framework recipes only, and every app/lib lists
+    // what it may additionally import in its own AGENTS.md `## Recipes In Scope`. Doctor never writes, so this
+    // is the check that catches a *committed* stale index (lint/sync self-heal the working tree instead).
+    const scanNames = async (uiDirPath: string, basename?: string) =>
+      new Set(scanRecipes(await collectRecipeSources(uiDirPath, "ui", basename)).map((info) => info.name));
+    const declaredByImport = new Map<string, Set<string>>();
+    declaredByImport.set("akanjs/ui", await scanNames(path.join(workspace.workspaceRoot, "pkgs/akanjs/ui"), "recipe"));
+    for (const sys of [...context.apps, ...context.libs])
+      declaredByImport.set(`@${sys.path}/ui`, await scanNames(path.join(workspace.workspaceRoot, sys.path, "ui")));
+    // Section slice anchors the heading to a full line — the same string appears back-ticked in prose.
+    const sectionOf = (content: string, heading: string) => {
+      const match = new RegExp(`^${heading}$`, "m").exec(content);
+      if (!match) return "";
+      const section = content.slice(match.index);
+      const sectionEnd = section.indexOf("\n## ", 1);
+      return sectionEnd === -1 ? section : section.slice(0, sectionEnd);
+    };
+    // `Import from \`<path>\`:` groups with their `- \`name\`` items, so each name checks against its owner.
+    const listedByImport = (body: string) => {
+      const groups = new Map<string, Set<string>>();
+      let current: Set<string> | null = null;
+      for (const line of body.split("\n")) {
+        const group = /^Import from `([^`]+)`:/.exec(line);
+        if (group) {
+          current = groups.get(group[1]) ?? new Set();
+          groups.set(group[1], current);
+          continue;
+        }
+        const item = /^- `([A-Za-z0-9_$]+)`/.exec(line);
+        if (item && current) current.add(item[1]);
+        else if (!item) current = null;
+      }
+      return groups;
+    };
+    const pushIndexDiagnostic = (indexPath: string, missing: string[], stale: string[], repairCommand: string) => {
+      if (missing.length === 0 && stale.length === 0) return;
+      const action = repairAction(
+        "generated",
+        repairCommand,
+        "Regenerate the recipe index from the scanned recipes.",
+        true,
+      );
+      const parts = [
+        missing.length > 0 ? `${missing.length} declared but unlisted (${missing.slice(0, 5).join(", ")})` : "",
+        stale.length > 0 ? `${stale.length} listed but gone (${stale.slice(0, 5).join(", ")})` : "",
+      ].filter(Boolean);
+      diagnostics.push({
+        severity: "error",
+        code: "recipe-index-stale",
+        path: indexPath,
+        message: `${indexPath} recipe index is out of date — ${parts.join("; ")}. Agents read this list as authoritative.`,
+        repairActions: [action],
+      });
+      repairActions.push(action);
+    };
+    const frameworkDeclared = declaredByImport.get("akanjs/ui") ?? new Set<string>();
+    if (frameworkDeclared.size > 0) {
+      const agentsMd = await Bun.file(path.join(workspace.workspaceRoot, "AGENTS.md"))
+        .text()
+        .catch(() => "");
+      const listed = listedByImport(sectionOf(agentsMd, "## Recipes")).get("akanjs/ui") ?? new Set<string>();
+      pushIndexDiagnostic(
+        "AGENTS.md",
+        [...frameworkDeclared].filter((name) => !listed.has(name)).sort(),
+        [...listed].filter((name) => !frameworkDeclared.has(name)).sort(),
+        "akan agent install agents-md",
+      );
+    }
+    for (const sys of [...context.apps, ...context.libs]) {
+      const own = declaredByImport.get(`@${sys.path}/ui`) ?? new Set<string>();
+      const scopeMd = await Bun.file(path.join(workspace.workspaceRoot, sys.path, "AGENTS.md"))
+        .text()
+        .catch(() => "");
+      const groups = listedByImport(sectionOf(scopeMd, "## Recipes In Scope"));
+      const ownListed = groups.get(`@${sys.path}/ui`) ?? new Set<string>();
+      const missing = [...own].filter((name) => !ownListed.has(name)).sort();
+      // Every listed name — the scope's own and its dependency libs' — must still exist at its owner.
+      const stale = [...groups.entries()]
+        .flatMap(([importFrom, names]) =>
+          [...names].filter((name) => !(declaredByImport.get(importFrom) ?? new Set()).has(name)),
+        )
+        .sort();
+      pushIndexDiagnostic(`${sys.path}/AGENTS.md`, missing, stale, `akan sync ${sys.name}`);
+    }
+
     const scopedDiagnostics = diagnostics.map((diagnostic) => ({
       ...diagnostic,
       scope: workflowPaths.length