@design-ai/cli 4.60.0 → 4.62.0

package/cli/lib/search-eval.mjs

@@ -0,0 +1,241 @@
+// Ranked-search eval checkpoint generation and reports for `design-ai search`.
+// Mirrors cli/lib/route.mjs's eval-checkpoint pattern (docs/AI-LEARNING-PHASE2.md
+// FU-3): runs hand-authored / generated cases through the shipped deterministic
+// ranked search path (rankedSearchCorpus, BM25-style lexical scorer) and reports
+// pass/warn/fail. This is the standing evidence artifact for any future decision
+// to promote `--ranked` to the default `search` behavior.
+
+import { rankedSearchCorpus } from "./search-ranked.mjs";
+import { DEFAULT_SEARCH_DIRS } from "./search.mjs";
+
+export const SEARCH_EVAL_VERSION = 1;
+// Default per-case result limit when a case does not specify its own `limit`.
+// Kept small and eval-appropriate (route's default is 3; search corpus hits are
+// noisier, so 10 gives enough headroom for `minHits` assertions without needing
+// a large recall window).
+export const SEARCH_EVAL_DEFAULT_LIMIT = 10;
+
+function isoTimestamp(now = new Date()) {
+  return (now instanceof Date ? now : new Date(now)).toISOString();
+}
+
+export function buildSearchEvalTemplate({ sourceRoot, generatedAt = new Date() } = {}) {
+  return {
+    version: SEARCH_EVAL_VERSION,
+    generatedAt: isoTimestamp(generatedAt),
+    description: "Deterministic ranked-search checkpoints for design-ai's BM25-style lexical retrieval.",
+    cases: [
+      {
+        id: "korean-button-stem",
+        query: "버튼",
+        minHits: 1,
+      },
+      {
+        id: "korean-button-particle",
+        query: "버튼을",
+        minHits: 1,
+      },
+      {
+        id: "korean-accessibility-particle",
+        query: "접근성이",
+        minHits: 1,
+      },
+      {
+        id: "accessibility-english",
+        query: "accessibility",
+        minHits: 5,
+        matchedTokenIncludes: ["accessibility"],
+      },
+      {
+        id: "button-component-spec-english",
+        query: "button component spec",
+        minHits: 5,
+        matchedTokenIncludes: ["button", "component", "spec"],
+      },
+      {
+        id: "color-palette-english",
+        query: "color palette",
+        expectRelPathIn: ["commands/palette-from-brand.md"],
+        minHits: 5,
+        matchedTokenIncludes: ["color", "palette"],
+      },
+    ],
+  };
+}
+
+function searchEvalStatus(counts) {
+  if (counts.fail > 0) return "fail";
+  if (counts.warn > 0) return "warn";
+  return "pass";
+}
+
+export function normalizeSearchEvalPayload(evalText, source = "search-eval.json") {
+  let payload;
+  try {
+    payload = JSON.parse(evalText);
+  } catch (err) {
+    throw new Error(`Could not parse search eval JSON from ${source}: ${err.message}`);
+  }
+
+  if (!payload || typeof payload !== "object" || Array.isArray(payload)) {
+    throw new Error("Search eval payload must be a JSON object");
+  }
+  if (payload.version !== SEARCH_EVAL_VERSION) {
+    throw new Error(`Search eval payload version must be ${SEARCH_EVAL_VERSION}`);
+  }
+  if (!Array.isArray(payload.cases)) {
+    throw new Error("Search eval payload must include a cases array");
+  }
+
+  return payload;
+}
+
+function normalizeStringList(value, { field, id }) {
+  if (value === undefined || value === null) return [];
+  if (!Array.isArray(value)) {
+    throw new Error(`Search eval case ${id} field ${field} must be an array`);
+  }
+  return value.map((item) => String(item || "").trim()).filter(Boolean);
+}
+
+export function normalizeSearchEvalCase(rawCase, index) {
+  if (!rawCase || typeof rawCase !== "object" || Array.isArray(rawCase)) {
+    throw new Error(`Search eval case ${index + 1} must be a JSON object`);
+  }
+
+  const id = String(rawCase.id || `case-${index + 1}`).trim();
+  if (!id) throw new Error(`Search eval case ${index + 1} is missing id`);
+
+  const query = String(rawCase.query || "").trim();
+  if (!query) throw new Error(`Search eval case ${id} is missing query`);
+
+  const dirs = normalizeStringList(rawCase.dirs, { field: "dirs", id });
+  for (const dir of dirs) {
+    if (!DEFAULT_SEARCH_DIRS.includes(dir)) {
+      throw new Error(`Search eval case ${id} field dirs has invalid value: ${dir}`);
+    }
+  }
+
+  const limit = rawCase.limit === undefined || rawCase.limit === null
+    ? SEARCH_EVAL_DEFAULT_LIMIT
+    : Number(rawCase.limit);
+  if (!Number.isInteger(limit) || limit < 1 || limit > 500) {
+    throw new Error(`Search eval case ${id} limit must be an integer from 1 to 500`);
+  }
+
+  const expectRelPathIn = normalizeStringList(rawCase.expectRelPathIn, { field: "expectRelPathIn", id });
+  const matchedTokenIncludes = normalizeStringList(rawCase.matchedTokenIncludes, { field: "matchedTokenIncludes", id })
+    .map((token) => token.toLowerCase());
+
+  let minHits;
+  if (rawCase.minHits === undefined || rawCase.minHits === null) {
+    minHits = undefined;
+  } else {
+    minHits = Number(rawCase.minHits);
+    if (!Number.isInteger(minHits) || minHits < 0) {
+      throw new Error(`Search eval case ${id} field minHits must be a non-negative integer`);
+    }
+  }
+
+  return {
+    id,
+    query,
+    dirs: dirs.length > 0 ? dirs : DEFAULT_SEARCH_DIRS,
+    limit,
+    expectRelPathIn,
+    minHits,
+    matchedTokenIncludes,
+  };
+}
+
+export function evaluateSearchEvalCase(testCase, sourceRoot, defaultLimit) {
+  const limit = testCase.limit || defaultLimit || SEARCH_EVAL_DEFAULT_LIMIT;
+  const { hits } = rankedSearchCorpus({
+    query: testCase.query,
+    designAiPath: sourceRoot,
+    dirs: testCase.dirs,
+    limit,
+  });
+  const topHit = hits[0] || null;
+  const topRelPath = topHit?.relPath || "";
+  const topMatchedTokens = (topHit?.matchedTokens || []).map((token) => token.toLowerCase());
+
+  const hasAssertions = testCase.expectRelPathIn.length > 0
+    || testCase.minHits !== undefined
+    || testCase.matchedTokenIncludes.length > 0;
+
+  let status = "pass";
+  let message = "All checkpoint expectations were satisfied.";
+
+  if (!hasAssertions) {
+    status = "warn";
+    message = "Case has no expectRelPathIn, minHits, or matchedTokenIncludes assertion.";
+  } else if (testCase.expectRelPathIn.length > 0 && !testCase.expectRelPathIn.includes(topRelPath)) {
+    status = "fail";
+    message = topRelPath
+      ? `Expected top hit in [${testCase.expectRelPathIn.join(", ")}], but top hit was ${topRelPath}.`
+      : `Expected top hit in [${testCase.expectRelPathIn.join(", ")}], but there were no hits.`;
+  } else if (testCase.minHits !== undefined && hits.length < testCase.minHits) {
+    status = "fail";
+    message = `Expected at least ${testCase.minHits} hit(s), got ${hits.length}.`;
+  } else if (
+    testCase.matchedTokenIncludes.length > 0
+    && !testCase.matchedTokenIncludes.every((token) => topMatchedTokens.includes(token))
+  ) {
+    status = "fail";
+    const missing = testCase.matchedTokenIncludes.filter((token) => !topMatchedTokens.includes(token));
+    message = topHit
+      ? `Top hit ${topRelPath} did not match expected token(s): ${missing.join(", ")}.`
+      : `Expected matched tokens [${missing.join(", ")}], but there were no hits.`;
+  }
+
+  return {
+    id: testCase.id,
+    status,
+    message,
+    query: testCase.query,
+    dirs: testCase.dirs,
+    limit,
+    topRelPath,
+    hitCount: hits.length,
+    matchedTokens: topHit?.matchedTokens || [],
+    expectRelPathIn: testCase.expectRelPathIn,
+    minHits: testCase.minHits ?? null,
+    matchedTokenIncludes: testCase.matchedTokenIncludes,
+    hits,
+  };
+}
+
+export function searchEvalReport({
+  evalText,
+  source = "search-eval.json",
+  sourceRoot,
+  limit = SEARCH_EVAL_DEFAULT_LIMIT,
+  generatedAt = new Date(),
+}) {
+  const payload = normalizeSearchEvalPayload(evalText, source);
+  const normalizedCases = payload.cases.map((testCase, index) => normalizeSearchEvalCase(testCase, index));
+  const results = normalizedCases.map((testCase) => evaluateSearchEvalCase(testCase, sourceRoot, limit));
+  const counts = results.reduce(
+    (acc, result) => ({
+      ...acc,
+      [result.status]: acc[result.status] + 1,
+    }),
+    { pass: 0, warn: 0, fail: 0 },
+  );
+  const summary = {
+    total: results.length,
+    pass: counts.pass,
+    warn: counts.warn,
+    fail: counts.fail,
+  };
+
+  return {
+    evalVersion: payload.version,
+    source,
+    generatedAt: isoTimestamp(generatedAt),
+    status: searchEvalStatus(counts),
+    summary,
+    cases: results,
+  };
+}

package/cli/lib/search-ranked.mjs

@@ -40,6 +40,24 @@ export function isGeneratedIndexDoc(relPath) {
     || normalized.startsWith("docs/reference/");
 }
 
+// Predicate for the full RECALL-injection exclusion set (docs/DOGFOOD-SDK-FINDINGS.md,
+// F-2): generated index/meta docs (isGeneratedIndexDoc) OR anything under docs/.
+// Rationale: recall injects DESIGN KNOWLEDGE into an agent's context, and the
+// design corpus lives in knowledge/, examples/, skills/, agents/, commands/ —
+// docs/ is product documentation (guides, roadmap, dogfood/inspection records,
+// portfolio material, integration walkthroughs). Enumerating individual meta
+// files proved to be whack-a-mole: the Phase 764 dogfood first surfaced
+// docs/case-study.md ranked #1, and the follow-up probe surfaced
+// docs/DOGFOOD-SDK-FINDINGS.md itself at 3x the top knowledge score because it
+// quotes the brief's vocabulary. Same recall-injection-surfaces-only boundary
+// as isGeneratedIndexDoc: raw `search --ranked` never applies this — a user
+// explicitly searching docs/ still gets docs/ hits.
+export function isRecallExcludedDoc(relPath) {
+  const normalized = String(relPath || "").replace(/\\/g, "/");
+  return isGeneratedIndexDoc(normalized)
+    || normalized.startsWith("docs/");
+}
+
 // N = max(limit*5, 25): the number of top lexical candidates handed to the embedding
 // reranker. Documented constant (docs/AI-LEARNING-PHASE2.md, Phase B CLI wiring).
 export function embeddingCandidateCount(limit) {
@@ -82,25 +100,27 @@ export function rankedSearchCorpus({
   dirs = DEFAULT_SEARCH_DIRS,
   limit = 20,
   indexDir = defaultIndexDir(),
-  // Opt-in RECALL filter: when true, drop generated index/meta docs
-  // (isGeneratedIndexDoc) BEFORE applying `limit`, so the limit fills with real
-  // knowledge instead of index files. Default false keeps raw `search --ranked`
-  // byte-unchanged. Filtering before the limit preserves determinism (score desc,
-  // id asc) — the rank pass already orders fully, we only remove excluded ids.
-  excludeGeneratedIndex = false,
+  // Opt-in RECALL filter: when true, drop non-knowledge docs (isRecallExcludedDoc —
+  // generated index/meta docs, package-excluded repo-meta docs, docs/integrations/
+  // walkthroughs) BEFORE applying `limit`, so the limit fills with real knowledge
+  // instead of those files. Default false keeps raw `search --ranked` byte-unchanged.
+  // Filtering before the limit preserves determinism (score desc, id asc) — the rank
+  // pass already orders fully, we only remove excluded ids.
+  excludeNonKnowledge = false,
 } = {}) {
   const documents = collectCorpusDocuments({ designAiPath, dirs });
   const stats = buildLexicalStats(documents.map(({ id, text }) => ({ id, text })));
   const textById = new Map(documents.map((doc) => [doc.id, doc.text]));
 
   // When excluding, rank the FULL candidate pool first (limit = documents.length)
-  // so that filtering out index docs cannot let a real-knowledge hit fall off the
-  // pre-limit cutoff; then re-apply `limit`. Ordering is unchanged (score desc, id asc).
+  // so that filtering out non-knowledge docs cannot let a real-knowledge hit fall
+  // off the pre-limit cutoff; then re-apply `limit`. Ordering is unchanged (score
+  // desc, id asc).
   const ranked = rankLexical(query, stats, {
-    limit: excludeGeneratedIndex ? documents.length : limit,
+    limit: excludeNonKnowledge ? documents.length : limit,
   });
-  const filtered = excludeGeneratedIndex
-    ? ranked.filter((hit) => !isGeneratedIndexDoc(hit.id)).slice(0, limit)
+  const filtered = excludeNonKnowledge
+    ? ranked.filter((hit) => !isRecallExcludedDoc(hit.id)).slice(0, limit)
     : ranked;
 
   const hits = filtered.map((hit) => ({

package/cli/lib/search.mjs

@@ -7,6 +7,7 @@ import {
 } from "node:fs";
 import path from "node:path";
 
+import { parseBriefSourceFlag } from "./brief.mjs";
 import { expectedValueMessage, unknownOptionMessage } from "./suggest.mjs";
 
 export const DEFAULT_SEARCH_DIRS = [
@@ -20,7 +21,21 @@ export const DEFAULT_SEARCH_DIRS = [
 
 const PREVIEW_LEN = 120;
 const PREVIEW_BEFORE = 50;
-const SEARCH_OPTIONS = ["-h", "--help", "--json", "--limit", "--dir", "--ranked", "--embeddings", "--provider"];
+const SEARCH_OPTIONS = [
+  "-h",
+  "--help",
+  "--json",
+  "--limit",
+  "--dir",
+  "--ranked",
+  "--embeddings",
+  "--provider",
+  "--eval-template",
+  "--eval",
+  "--strict",
+  "--from-file",
+  "--stdin",
+];
 
 function exists(p) {
   try {
@@ -118,11 +133,17 @@ export function parseSearchArgs(args) {
     ranked: false,
     embeddings: false,
     provider: "",
+    evalTemplate: false,
+    eval: false,
+    strict: false,
+    fromFile: "",
+    stdin: false,
     help: false,
   };
 
   for (let i = 0; i < args.length; i += 1) {
     const arg = args[i];
+    out.index = i;
     if (arg === "-h" || arg === "--help") {
       out.help = true;
     } else if (arg === "--json") {
@@ -131,9 +152,17 @@ export function parseSearchArgs(args) {
       out.ranked = true;
     } else if (arg === "--embeddings") {
       out.embeddings = true;
+    } else if (arg === "--eval-template") {
+      out.evalTemplate = true;
+    } else if (arg === "--eval") {
+      out.eval = true;
+    } else if (arg === "--strict") {
+      out.strict = true;
     } else if (arg === "--provider") {
       out.provider = args[i + 1] || "";
       i += 1;
+    } else if (parseBriefSourceFlag(args, out)) {
+      i = out.index;
     } else if (arg === "--limit") {
       const next = args[i + 1];
       const limit = Number(next);
@@ -156,8 +185,34 @@ export function parseSearchArgs(args) {
     }
   }
 
+  if (out.eval && out.evalTemplate) {
+    throw new Error("Choose either --eval-template or --eval, not both");
+  }
+  if (out.strict && !out.eval) {
+    throw new Error("--strict can only be used with --eval");
+  }
+  if (
+    out.evalTemplate
+    && (out.fromFile || out.stdin || out.queryParts.length > 0 || out.ranked || out.embeddings || out.provider || out.dirs.length > 0)
+  ) {
+    throw new Error("--eval-template cannot be combined with a query, --from-file, --stdin, --ranked, --embeddings, --provider, or --dir");
+  }
+  if (out.eval && (!out.fromFile && !out.stdin)) {
+    throw new Error("--eval requires --from-file or --stdin");
+  }
+  if ((out.fromFile || out.stdin) && !out.eval) {
+    throw new Error("--from-file and --stdin require --eval");
+  }
+  if (
+    out.eval
+    && (out.queryParts.length > 0 || out.ranked || out.embeddings || out.provider || out.dirs.length > 0)
+  ) {
+    throw new Error("--eval cannot be combined with an inline query, --ranked, --embeddings, --provider, or --dir");
+  }
+
   return {
     ...out,
+    index: undefined,
     query: out.queryParts.join(" ").trim(),
     dirs: out.dirs.length > 0 ? out.dirs : DEFAULT_SEARCH_DIRS,
   };

package/docs/AI-LEARNING-PHASE2.md

@@ -202,8 +202,19 @@ This review answers the five open questions against the shipped Phase A implemen
 
 - **FU-1 (Q4, before Phase B):** Add Hangul-aware tokenization (CJK bigramming or particle stripping) in `cli/lib/lexical.mjs` behind Korean `learn --eval` checkpoints; regression-test that `버튼`, `버튼을`, `버튼이` converge on the same button docs. _Done (2026-07-03): Hangul runs >= 2 chars now emit overlapping character bigrams alongside the surface form; the review's zero-hit queries recover (`버튼` 0 → 3 ranked hits, `접근성이` 0 → 3), with unit regression coverage in `lexical.test.mjs`._
 - **FU-2 (Q2, before Phase B index-as-source-of-truth):** Key the corpus index by corpus digest / record `designAiPath` in the payload so multiple checkouts do not overwrite each other once the index is read for content rather than staleness. _Done (2026-07-03): sidecar format bumped to version 2 (auto-invalidating v1 files); the corpus payload records resolved `designAiPath` and the learning payload the resolved `learningFile`, and `index --status` reports `sourceMatch` and treats identity mismatch as not fresh._
-- **FU-3 (Q1, gates default promotion):** Land a ranked-search eval checkpoint so any future `--ranked` default promotion is evidence-backed and announced.
-- **FU-4 (Q5, Phase B):** Specify and implement `~/.design-ai/config.json` as the Phase B provider config home with per-invocation `--embeddings` still required.
+- **FU-3 (Q1, gates default promotion):** Land a ranked-search eval checkpoint so any future `--ranked` default promotion is evidence-backed and announced. _Done (2026-07-05): `design-ai search --eval-template`/`--eval [--strict]` landed in `cli/lib/search-eval.mjs` and `cli/commands/search.mjs`, mirroring the route/prompt/pack/learn eval-checkpoint pattern; cases run through `rankedSearchCorpus` (the shipped ranked path), and the default template includes the three Korean particle-form regression cases from FU-1 (버튼/버튼을/접근성이) plus English cases, doubling as a retrieval-level Hangul-bigram regression check._
+- **FU-4 (Q5, Phase B):** Specify and implement `~/.design-ai/config.json` as the Phase B provider config home with per-invocation `--embeddings` still required. _Done (2026-07-03, Phase B): `cli/lib/local-config.mjs` reads `~/.design-ai/config.json` (or `DESIGN_AI_CONFIG_FILE`); the config only supplies the provider — every invocation still requires the explicit `--embeddings` flag to arm it._
+
+### Ranked-default decision closure (2026-07-06)
+
+With FU-3 landed and shipped (v4.61.0), the promotion question that Decision 1 deferred was formally revisited and **closed for the 4.x line: `search --ranked` remains opt-in across all three surfaces (CLI, MCP `design_ai_search`, SDK `search()`)**. The evidence and reasoning:
+
+- **The two modes answer different questions.** Default `search` is grep-like — line-precise hits (`lineNumber`) that feed the `show file:line` workflow. Ranked is retrieval-like — file-level relevance (`score`, `matchedTokens`). Neither is a strict upgrade of the other; flipping the default would remove the line-precise contract rather than improve it.
+- **The SDK semver contract now binds the default.** Since v4.59.0/v4.60.0, `search(query)`'s unranked return shape (including `lineNumber`) is pinned by the SDK contract test as a semver-stable surface. Changing any surface's default without the others desynchronizes CLI/MCP/SDK; changing all three is by definition a major-version event — exactly the "announced major-version default change, never a silent one" bar Decision 1 set.
+- **The practical benefit is already absorbed.** Every surface where relevance ranking matters (recall injection in `prompt`/`pack`, `learn --recall`, `route --explain` related knowledge) already uses the ranked scorer internally. The remaining delta from flipping the interactive default is small, and agent consumers opt in explicitly today.
+- **Quality stays evidence-backed either way.** The FU-3 checkpoint (`search --eval`, 6/6 passing incl. the Korean particle-form cases) runs in the release gates, so ranked quality is continuously measured without needing the default flip to justify the eval.
+
+If a future major version (5.0) reopens this, the prerequisites are already written: flip CLI + MCP + SDK defaults together, provide a line-hit escape hatch (e.g. `--lines`), re-pin the smoke assertions and SDK contract in the same change, and cite the then-current FU-3 eval results in the CHANGELOG announcement.
 
 ### Phase B gate: cleared-with-conditions
 

package/docs/DOGFOOD-SDK-FINDINGS.md

@@ -0,0 +1,56 @@
+# Dogfood findings — Agent SDK end-to-end flow (Phase 764)
+
+A real design task driven entirely through the Agent SDK (`@design-ai/cli/sdk`, shipped v4.59.0–v4.61.0), per the accepted composed slice in [NEXT-SURFACE-DECISION.md](NEXT-SURFACE-DECISION.md): SDK adoption evidence and a dogfood pass in one run.
+
+**Scope of this dogfood**: the full consumer flow `route(brief)` → `pack(brief, { withRecall })` → author the artifact → `check(artifact, { routeId })` → `learn.captureFromCheck(artifact, { routeId })`, on a genuine brief, with the learning write isolated to a temp profile via `DESIGN_AI_LEARNING_FILE`.
+
+**The brief** (deliberately chosen from a suspected corpus gap): 커뮤니티 앱의 게시물 신고 및 사용자 차단 플로우 설계 — 신고 사유 선택, 처리 상태 안내, 차단 후 상호작용 차단 범위.
+
+## What worked
+
+### 1. The SDK flow itself: zero friction
+
+Every step worked first-try in a plain Node ESM script — no CLI shell-out, no MCP server, no docs consultation beyond `docs/SDK.md`:
+
+- `route(brief, { limit: 3, explain: true })` returned scored routes with `relatedKnowledge`.
+- `pack(brief, { withRecall: true, recallLimit: 5, maxBytes: 60000 })` returned a bounded 15-file context bundle (60,000 bytes exactly at budget) with the plan, checklist, and recall block.
+- `check(artifact, { routeId })` returned `warn 9/10` with a precise per-result breakdown.
+- `learn.captureFromCheck(artifact, { routeId })` captured the single non-pass result into the temp profile (`added 1, skipped 0`) and wrote nothing anywhere else.
+- `DESIGN_AI_LEARNING_FILE` isolation behaved exactly as documented — the real user profile was untouched.
+
+This is the adoption story: the flow a hosted agent would run is four function calls. It is recorded as the basis for the Agent SDK walkthrough.
+
+### 2. The eval/check loop caught the routing mismatch on its own
+
+The one `warn` (`route-design-from-brief-design-system-foundation`) is not noise — it is the check system correctly reporting that a flow-design artifact lacks design-system-foundation evidence, which is exactly what finding 1 below predicts: the brief should never have landed on `design-from-brief` in the first place.
+
+## Findings
+
+### F-1. Route-table gap: flow/feature-design briefs fall through to the wrong route
+
+`route()` scored the report/block brief `[low] score=1`, matching only the keyword `앱`, and fell back to `design-from-brief` — whose command, skills (`color-palette`, `design-system-builder`, `handoff-spec`), checklist ("Produce foundations, tokens, component baseline"), and check requirements all target a **from-scratch design-system brief**, not a **feature-flow spec**. There is no route for interaction/flow design (신고, 차단, 온보딩, 결제 플로우류) — a very common real-task class. The mismatch propagated end-to-end: wrong skills in the pack, wrong checklist, and a guaranteed check warn.
+
+**Proposed fix**: a `flow-design` (or `feature-flow`) route with keywords for common flows (신고/차단/온보딩/가입/결제/설정/알림, report/block/onboarding/signup/checkout/settings), curated knowledge (`ui-reasoning`, `async-control`, forms/patterns), and route-specific check requirements suited to flow specs (states, edge cases, error paths) rather than token foundations.
+
+_Done (2026-07-06): `flow-design` route added to `cli/lib/route.mjs` (`command: null`, mirroring `handoff-spec`/`design-system-qa`), with skills `ux-audit` + `design-critique`, agent `a11y-reviewer`, and curated knowledge `ui-reasoning`, `async-control`, `trust-safety-moderation` (F-3), `form-design`, `error-states`, `onboarding`. Keywords use compound Korean/English terms (`결제 플로우`, `설정 화면`, `알림 설정`, `report flow`, `signup flow`, `moderation flow`, …) chosen to avoid stealing bare terms already owned by other routes (`앱`/`서비스`/`프로덕트`/`app`/`product` → `design-from-brief`; `component`/`form` → `component-spec`). Re-ran the dogfood brief: `route()` now returns `[high] flow-design score=4` (matched `플로우`, `신고`, `차단`, `처리 상태`), with `design-from-brief` still present at `[low] score=1` (matched `앱`) as a secondary candidate — up from the prior single `[low] design-from-brief score=1` result. Added `ROUTE_REQUIREMENTS["flow-design"]` to `cli/lib/check.mjs` (states/steps, edge/error paths, entry/exit/completion — bilingual patterns mirroring house style); the Walkthrough 3 sample artifact now scores `warn 8/12` against `--route flow-design` (3 route-specific warns, as expected for a short sample), matching the walkthrough doc's existing "mostly-pass" framing. Added `examples/flow-design-report-block.md`, an expanded version of the dogfooded artifact that satisfies every example-qa bar (12/12) and is now the top-ranked example for the route. Updated the `EXPECTED_ROUTE_CATALOG_IDS` tuple in `tools/audit/smoke_assertions.py` (the single source both `package-smoke.py` and `registry-smoke.py` import from) and both README example-count badges (221 → 222, matching `check-coverage.py`'s top-level-only `examples/*.md` count — the new file lives at `examples/flow-design-report-block.md`, not under `examples/cases/`). `knowledge/COVERAGE.md` was left to its normal regeneration via `tools/audit/check-coverage.py` (not hand-edited), matching the F-3 precedent. Incidental fix: this route's 15-file pack combination exposed a pre-existing off-by-a-few-bytes bug in `cli/lib/pack.mjs`'s `takeUtf8` — truncating mid-UTF-8-character let `Buffer.toString("utf8")` insert a 3-byte U+FFFD replacement character that could be larger than the partial bytes it replaced, letting `usedBytes` exceed `maxBytes` by 1-2 bytes on multi-file packs with tight budgets; fixed by trimming to the last complete UTF-8 character boundary before decoding (`trimIncompleteUtf8Tail`), verified against ASCII, Korean (1/2/3-byte-cut), and 4-byte emoji boundary cases. Full suite green (585 tests), all 8 audits, release-metadata, package-smoke, registry-smoke self-test, and ci:local pass. Route eval: default `--eval-template` checkpoint (6 cases) still `pass 6/6` under `--eval --strict`; four other representative briefs (design-review, website-improvement, component-spec, palette-from-brand, design-system-qa, motion-design eval checkpoints) all still resolve to their prior top route unchanged._
+
+### F-2. Recall pollution: repo-meta docs outrank design knowledge
+
+For this brief, `relatedKnowledge` surfaced `pricing-page-design` (37.0), `korean-document-style` (22.8), `dashboard-composition` (10.8) — none relevant — and the pack's recall block selected `docs/case-study.md` (49.1, the **top** hit), `docs/project-card.md` (30.8), `docs/interview-story.md` (30.4), and `docs/integrations/codex-walkthrough.ko.md` (30.2). Those are repo-meta documents (portfolio/case-study material, integration walkthroughs), not design knowledge; three of the four are even excluded from the npm package by the `files` field. The v4.58 generated-index exclusion (`COVERAGE.md`, `INDEX.md`, `docs/reference/*`) does not cover them.
+
+**Proposed fix**: extend the recall exclusion list from "generated index files" to a "non-knowledge docs" set — at minimum the package-excluded meta docs (`docs/case-study.md`, `docs/project-card.md`, `docs/interview-story.md`, `docs/resume-bullets.md`, …) and `docs/integrations/*` walkthroughs — for recall-injection surfaces only (raw `search` stays unfiltered, same boundary as v4.58).
+
+_Done (2026-07-06): `isRecallExcludedDoc(relPath)` added in `cli/lib/search-ranked.mjs`, extending `isGeneratedIndexDoc` with the package-excluded repo-meta docs (the exact `!docs/*.md` set from `package.json` `files`: case-study, evidence-checklist, evidence-gallery, implementation-evidence, interview-story, project-card, project-roadmap, readme-improvement, resume-bullets) and the `docs/integrations/` prefix. `rankedSearchCorpus`'s opt-in filter option was renamed `excludeGeneratedIndex` → `excludeNonKnowledge` (only 3 internal call sites + tests referenced the old name) and now applies the broader predicate; `cli/lib/recall.mjs` (both call sites) and `cli/lib/route.mjs`'s `relatedKnowledgeFor` pass it unchanged. Re-ran the dogfood brief through the SDK: `recall()`'s `corpus.selected` and `route --explain`'s `relatedKnowledge` no longer surface `docs/case-study.md` / `docs/project-card.md` / `docs/interview-story.md` / `docs/integrations/codex-walkthrough.ko.md` — those slots are now filled by real corpus knowledge. Raw `search --ranked` is unaffected (verified unfiltered). Full suite green (585 tests), all 8 audits, release-metadata, package-smoke, registry-smoke self-test, and ci:local pass._
+
+_Follow-up F-2b (2026-07-06): the enumerated meta-doc list proved to be whack-a-mole — the post-fix probe surfaced `docs/DOGFOOD-SDK-FINDINGS.md` itself as the new top recall hit (141.2, ~3× the best knowledge score) because this document quotes the brief's vocabulary, with `docs/inspection-*.md` and `docs/announcements/*` next in line. Resolved by the principled rule: `isRecallExcludedDoc` now excludes **everything under `docs/`** (recall injects design knowledge; the design corpus is `knowledge/`, `examples/`, `skills/`, `agents/`, `commands/` — `docs/` is product documentation). The per-file meta list was removed as dead code. Raw `search`/`search --ranked` still returns `docs/` hits unfiltered. Post-change probe: `recall()` top hit for the dogfood brief is `knowledge/patterns/trust-safety-moderation.md` (the F-3 file), with zero `docs/` entries._
+
+### F-3. Corpus gap: no trust & safety / moderation UX knowledge
+
+Nothing in `knowledge/` covers report/block/moderation patterns: 신고 사유 분류 설계, 처리 상태 커뮤니케이션(접수→검토→조치), 차단 의미론(양방향 범위, 비통지 원칙), 신고 남용 방지, and the Korean regulatory angle (정보통신망법 제44조의2 임시조치 30일, KCSC 처리 관행). For a product with Korean community/social apps in scope, this is a real gap — the artifact had to be authored from general principles alone.
+
+**Proposed fix**: `knowledge/patterns/trust-safety-moderation.md` (hand-written), covering the above plus accessibility specifics for report sheets/status badges; pairs naturally with the F-1 flow route's curated knowledge.
+
+## Verdict
+
+- **SDK**: walkthrough-ready as-is; no API changes needed. The flow is the walkthrough.
+- **Backlog generated (evidence-backed, in priority order)**: F-2 recall exclusion (small, mirrors the shipped v4.58 exclusion mechanism), F-3 trust-safety knowledge file (corpus), F-1 flow-design route (route table + check requirements + smoke surface updates).

package/docs/NEXT-SURFACE-DECISION.md

@@ -118,8 +118,42 @@ Cross-check any surface work against the release gate: `npm run audit` (8/8, lin
 
 ## Decision record
 
-- **Status:** proposed — awaiting maintainer sign-off
-- **Date:** 2026-07-03
+- **Status:** accepted and executed — both recommended surfaces shipped
+- **Date:** 2026-07-03 (proposed) / 2026-07-05 (executed)
 - **Deciders:** maintainer
 - **Supersedes:** none
 - **Related:** [`PRODUCT-READINESS.md`](PRODUCT-READINESS.md), [`external-status.md`](external-status.md), `AI-LEARNING-PHASE2.md`
+
+### Outcome (2026-07-05)
+
+The recommendation was executed in order and both surfaces are live:
+
+- **CLI deepening** shipped as v4.57.0 (local retrieval memory: `index`, `search --ranked`, `--with-recall`, `learn --recall`, opt-in embedding rerank) and v4.58.0 (`route --explain` related knowledge, recall quality, corpus depth). The dogfood friction this document identified — missing corpus and missing flags — is retired; retrieval spans every CLI/MCP surface.
+- **Agent SDK** followed exactly on the stated revisit trigger (recall interface stable across two releases): design doc [`AGENT-SDK.md`](AGENT-SDK.md), then v4.59.0 (Phase A — read-only `@design-ai/cli/sdk`, 8 verbs) and v4.60.0 (TypeScript declarations + the opt-in `learn.*` local-write namespace).
+
+The deferred surfaces (VS Code deepening, Web UI, Figma plugin) remain deferred with the same revisit triggers. The next-surface question is open again; re-evaluate against the criteria above when the next planning window opens, factoring in that the SDK now also serves programmatic adopters.
+
+## Re-evaluation (2026-07-06)
+
+Scored with the same seven criteria, in the post-execution landscape: CLI deepening and the Agent SDK are shipped (v4.57–v4.61), the AI-learning Phase A follow-ups and Phase B are all closed, and the ranked-default question is decided for 4.x (see [`AI-LEARNING-PHASE2.md`](AI-LEARNING-PHASE2.md)). The SDK's existence opens a new leverage axis — programmatic consumers — that did not exist at the original scoring.
+
+| Candidate | Leverage | Reach | Build cost | Maintenance | Distribution | Risk | Synergy | Total |
+|---|---|---|---|---|---|---|---|---|
+| Dogfood verification pass | 5 | 4 | 4 | 5 | 3 | 5 | 5 | **31** |
+| SDK adoption enablement | 4 | 4 | 5 | 4 | 4 | 5 | 4 | **30** |
+| Web UI expansion | 4 | 3 | 3 | 4 | 3 | 4 | 3 | 24 |
+| VS Code deepening | 4 | 3 | 3 | 3 | 4 | 3 | 3 | 23 |
+| Component spec extractor v2 | 3 | 3 | 3 | 4 | 3 | 4 | 2 | 22 |
+| Skill-proposal apply path | 3 | 3 | 3 | 3 | 4 | 2 | 4 | 22 |
+
+- **Dogfood verification pass** — use design-ai itself to produce a real design artifact end-to-end and capture the gaps. This is how the async-control and Korean-density corpus gaps were found; it generates the next backlog organically and exercises every shipped surface.
+- **SDK adoption enablement** — a real, runnable SDK consumer example plus an agent-integration recipe and docs. Converts the just-shipped SDK investment into adoption; zero new product code, zero platform risk.
+- VS Code / Web UI / Figma: unchanged constraints, unchanged revisit triggers, no new demand signal — still deferred.
+- Spec extractor: coverage is already 90.5%, so its value has shrunk from coverage-push to maintenance automation.
+- Skill-proposal apply path: still gated on a separate approval + archive/review design per the standing constraint.
+
+### Recommendation (2026-07-06)
+
+**Run the two leaders as one composed slice: a real SDK consumer example that drives a design task end-to-end (`route` → `pack` → `check` → `learn.captureFromCheck`), documented as the SDK walkthrough.** The example is simultaneously the SDK adoption artifact (D) and a dogfood pass (G): building it exercises the shipped surfaces against a genuine task, and any friction or corpus gaps it surfaces become the evidence-backed next backlog — the same loop that produced the v4.58 corpus additions.
+
+- **Status:** accepted — maintainer signed off 2026-07-06; the composed slice is the next work item

package/docs/ROADMAP.md

@@ -1,5 +1,82 @@
 # Roadmap
 
+## Phase 765 — Dogfood Loop Release (v4.62.0) ✓ ready
+
+Ships the whole Phase 764 dogfood cycle as one npm version: the `flow-design` route (F-1), the trust & safety corpus file and worked example (F-3), the principled recall exclusion of `docs/` (F-2/F-2b), the `pack` UTF-8 byte-budget fix the walkthrough guard caught, and the Agent SDK walkthrough itself (en/ko).
+
+### Verified
+- All 8 audits passed.
+- `npm run release:check` (unit tests incl. flow-example guard and pack budget-sweep invariant, strict audits, whitespace, package contents, release metadata, release self-tests, packed-tarball smoke).
+- `npm run release:metadata`.
+- `git diff --check`.
+- Route eval checkpoint 6/6 and representative-brief routing unchanged; search eval 6/6.
+- Main-branch GitHub Actions (`Design-AI audit`, `Deploy doc site`) passed for the constituent commits.
+
+### Versions
+- `package.json` + `.claude-plugin/plugin.json`: 4.61.0 → 4.62.0.
+- `vscode-extension/package.json`: remains 0.4.1.
+
+### What this enables
+- npm users get the closed dogfood loop: flow briefs route to a purpose-built route with flow-appropriate checks, recall injection is design-knowledge-only, Korean community products get the trust & safety regulatory floor, `pack`'s byte budget is a hard guarantee, and the SDK has a verified end-to-end walkthrough.
+
+### What's still ahead
+- Next dogfood pass on a different task class (the loop is now cheap to rerun), or the next planning window per [NEXT-SURFACE-DECISION.md](NEXT-SURFACE-DECISION.md).
+
+## Phase 764 — SDK adoption + dogfood composed slice (implemented, unreleased)
+
+Executes the composed slice accepted in [NEXT-SURFACE-DECISION.md](NEXT-SURFACE-DECISION.md) (re-evaluation of 2026-07-06): a real design task driven end-to-end through the Agent SDK, recorded as both the SDK adoption walkthrough and a dogfood pass.
+
+### Delivered
+- [x] Dogfood run on a genuine brief (커뮤니티 앱 신고·차단 플로우) through `route` → `pack --withRecall` → author → `check` → `learn.captureFromCheck` with temp-profile isolation; SDK verdict: zero friction. Findings recorded in [DOGFOOD-SDK-FINDINGS.md](DOGFOOD-SDK-FINDINGS.md): F-1 flow-design route gap, F-2 recall pollution by repo-meta docs, F-3 trust & safety corpus gap.
+- [x] `docs/integrations/agent-sdk-walkthrough.md` + `.ko.md` — copy-pastable end-to-end consumer script with measured outputs (doc outputs verified against a live run of the embedded sample artifact), registered in the integration-completeness audit and mkdocs nav; README(+ko) SDK row links it; `docs/SDK.md` gains a walkthrough pointer.
+- [x] `cli/sdk/flow-example.test.mjs` — the walkthrough flow as a `node --test` regression guard (shape-based assertions; 583/583 total).
+
+### Backlog closed (2026-07-06)
+- [x] F-2 recall meta-doc exclusion (`isRecallExcludedDoc`, option renamed `excludeNonKnowledge`), then F-2b: the enumerated list proved whack-a-mole (the findings doc itself became the top recall hit at 3× the best knowledge score), resolved by the principled rule — recall injection excludes everything under `docs/`; the design corpus is `knowledge/`, `examples/`, `skills/`, `agents/`, `commands/`. Raw `search --ranked` unchanged.
+- [x] F-3 `knowledge/patterns/trust-safety-moderation.md` (corpus 95): report flow, status pipeline incl. 정보통신망법 제44조의2 임시조치, block semantics (non-notification), abuse prevention, accessibility floor. Post-landing probe: top `relatedKnowledge` hit for the dogfood brief.
+- [x] F-1 `flow-design` route (`command: null`, compound keywords to avoid hijacking, flow-specific check requirements, `examples/flow-design-report-block.md` at example-qa 12/12). Dogfood brief now routes `[high] flow-design score=4` (was `[low] design-from-brief score=1`); route eval 6/6 and representative briefs unchanged.
+- [x] Bonus: the walkthrough's regression guard (`cli/sdk/flow-example.test.mjs`) caught a real pre-existing `pack` bug — mid-UTF-8-character truncation could exceed `maxBytes` via U+FFFD replacement growth; fixed with a character-boundary trim (RED-verified: the guard fails on the unfixed code), plus a Korean-content budget-sweep invariant test.
+
+### Remaining
+- [ ] Release: bundle into the next npm version.
+
+## Phase 763 — Ranked-search Eval Checkpoint Release (v4.61.0) ✓ ready
+
+Ships the FU-3 ranked-search eval checkpoint (Phase 762) as an npm version: `search --eval-template` / `search --eval [--strict]` over the shipped BM25 path, with the Korean particle-form regression cases in the default template. Additive and backward-compatible; default `search` behavior is unchanged. With this release the AI-learning Phase A follow-ups (FU-1–FU-4) are all closed and published.
+
+### Verified
+- All 8 audits passed.
+- `npm run release:check` (unit tests incl. search-eval and search-command suites, strict audits, whitespace, package contents, release metadata, release self-tests, packed-tarball smoke).
+- `npm run release:metadata`.
+- `git diff --check`.
+- Main-branch GitHub Actions (`Design-AI audit`, `Deploy doc site`) passed for the constituent commits.
+
+### Versions
+- `package.json` + `.claude-plugin/plugin.json`: 4.60.0 → 4.61.0.
+- `vscode-extension/package.json`: remains 0.4.1.
+
+### What this enables
+- The `--ranked` default-promotion decision becomes evidence-backed for npm users too: the published CLI carries the checkpoint tooling, so the eval can be re-run against any installed version — including Korean agglutinative-query regressions — before and after such a change.
+
+### What's still ahead
+- ~~The `--ranked` default-promotion decision itself~~ — decided 2026-07-06: **opt-in stays for the 4.x line** across CLI/MCP/SDK; any future flip is a coordinated 5.0 major event. Full rationale recorded in [AI-LEARNING-PHASE2.md](AI-LEARNING-PHASE2.md) ("Ranked-default decision closure").
+- Next-surface re-evaluation per the updated decision record in [NEXT-SURFACE-DECISION.md](NEXT-SURFACE-DECISION.md).
+
+## Phase 762 — Ranked-search eval checkpoint (FU-3, implemented, unreleased)
+
+Closes the last open follow-up from the AI-learning Phase A review ([AI-LEARNING-PHASE2.md](AI-LEARNING-PHASE2.md), FU-3): `design-ai search` gains `--eval-template` / `--eval [--strict]` checkpoint modes mirroring the route/prompt/pack/learn eval pattern, run through the shipped ranked (BM25) search path. This is the standing evidence artifact for any future decision to promote `--ranked` to the default; with FU-1/FU-2/FU-4 already annotated done, all four Phase A follow-ups are now closed.
+
+### Delivered
+- [x] `cli/lib/search-eval.mjs` — `SEARCH_EVAL_VERSION = 1`, `buildSearchEvalTemplate()`, `searchEvalReport()` over `rankedSearchCorpus`; route-style payload normalization and error messages. Case schema: `id`, `query`, optional `dirs`/`limit`, assertions `expectRelPathIn` / `minHits` / `matchedTokenIncludes`.
+- [x] Default template includes the FU-1 Korean particle-form regression cases (`버튼`, `버튼을`, `접근성이`) plus three English cases — so the eval doubles as the retrieval-level Hangul-bigram regression. All six verified passing against the shipped corpus (`--strict` exit 0).
+- [x] CLI wiring in `cli/lib/search.mjs` / `cli/commands/search.mjs` (`--eval-template`, `--eval`, `--strict`, `--from-file`, `--stdin`, mutual-exclusivity validation), help topic usage line, and the shared `smoke_assertions.py` pins (4 spots — shared constants, so both package and registry smokes stay aligned).
+- [x] Tests: `search-eval.test.mjs` (template, pass/warn/fail reports, malformed payloads) and `search-command.test.mjs` (CLI-level, strict exit semantics). 578/578 total.
+- [x] `docs/AI-LEARNING-PHASE2.md` FU-3 and FU-4 done annotations.
+
+### Remaining
+- [ ] Release: bundle into the next npm version.
+- [ ] The `--ranked` default-promotion decision itself — a future, separate call that this checkpoint now makes evidence-backed.
+
 ## Phase 761 — Agent SDK types + Phase B Release (v4.60.0) ✓ ready
 
 Ships the Agent SDK TypeScript declarations (Phase 759) and the `learn.*` local-write namespace (Phase 760) together as one npm version. Both are additive and backward-compatible: the eight Phase A verbs stay read-only and unchanged, and TypeScript types resolve automatically for `@design-ai/cli/sdk` with no build step on either side.