@slowcook-ai/cli 0.19.1 → 0.19.3

package/dist/commands/refine/spec-validate.js

@@ -62,6 +62,227 @@ function pruneTokenList(items, pathPrefix, findings) {
     }
     return out;
 }
+/**
+ * 0.19.x+ — catch hallucinated entity.field references in the spec.
+ *
+ * Refine sometimes invents fields that don't exist on the consumer's
+ * actual entities (e.g. story-005 in delgoosh referenced
+ * `user.timezone.label` but Timezone has only `name`/`offset`/`offsetStr`).
+ * Brew + testgen downstream silently grounded against the wrong field,
+ * leading to a runtime error that took a human to spot.
+ *
+ * This lint parses `.brewing/repo-knowledge/auto/backend-entities.md`,
+ * walks every string-typed field of the spec, and for each
+ * `lowercaseName.fieldName` pair where `lowercaseName` matches a known
+ * entity, checks whether `fieldName` is in that entity's field set.
+ * Misses are flagged as `"flagged"` (kept as-is — the spec text isn't
+ * auto-repairable since we don't know what the author meant).
+ *
+ * Chained references like `user.timezone.label` are decomposed into
+ * pairs (`user.timezone`, `timezone.label`); each pair is checked
+ * independently. Relation traversal works because relation field
+ * values are themselves listed in the entity catalog with the
+ * other-entity name as their type.
+ *
+ * Exported for testing.
+ */
+export function parseEntityCatalog(md) {
+    const out = new Map();
+    let current = null;
+    let currentFields = null;
+    for (const line of md.split(/\r?\n/)) {
+        const headerMatch = line.match(/^##\s+([A-Z]\w+)\b/);
+        if (headerMatch) {
+            if (current && currentFields)
+                out.set(current, currentFields);
+            // Map by LOWERCASED entity name so spec text like `user.firstName`
+            // resolves to the User entity.
+            current = headerMatch[1].toLowerCase();
+            currentFields = new Set();
+            continue;
+        }
+        if (!currentFields)
+            continue;
+        const fieldMatch = line.match(/^-\s+(\w+)\??:/);
+        if (fieldMatch)
+            currentFields.add(fieldMatch[1]);
+    }
+    if (current && currentFields)
+        out.set(current, currentFields);
+    return out;
+}
+/**
+ * Walk every string in a value (recursing into arrays/objects).
+ * Yields each string with a dotted path for diagnostic context.
+ */
+function* walkStrings(value, path = "") {
+    if (typeof value === "string") {
+        yield { path, text: value };
+        return;
+    }
+    if (Array.isArray(value)) {
+        for (let i = 0; i < value.length; i++) {
+            yield* walkStrings(value[i], `${path}[${i}]`);
+        }
+        return;
+    }
+    if (value && typeof value === "object") {
+        for (const [k, v] of Object.entries(value)) {
+            yield* walkStrings(v, path ? `${path}.${k}` : k);
+        }
+    }
+}
+export function validateEntityFieldReferences(spec, entityCatalogMd) {
+    const findings = [];
+    const catalog = parseEntityCatalog(entityCatalogMd);
+    if (catalog.size === 0)
+        return findings; // No catalog → can't lint.
+    // Sections worth walking. We deliberately skip free-form metadata
+    // (title, notes, rationale text under proposals) to keep false-
+    // positives low — only fields where field references are LOAD-BEARING.
+    const sections = [
+        { key: "invariants", value: spec.invariants },
+        { key: "preconditions", value: spec.preconditions },
+        { key: "acceptance_scenarios", value: spec.acceptance_scenarios },
+        { key: "api_contract", value: spec.api_contract },
+        { key: "ui_behavior", value: spec.ui_behavior },
+    ];
+    // Per pair, only flag the FIRST occurrence so a single typo
+    // doesn't generate noise across 20 invariants.
+    const seen = new Set();
+    for (const section of sections) {
+        if (section.value == null)
+            continue;
+        for (const { path, text } of walkStrings(section.value, String(section.key))) {
+            // Match every dotted chain (>=2 segments) and split into adjacent
+            // pairs. `regex.exec` with /g advances past each full match, so we
+            // can't catch overlapping pairs (`user.timezone` and
+            // `timezone.label` inside `user.timezone.label`) with a single
+            // pair-regex — extract the whole chain and decompose.
+            const chainRe = /\b([a-z][a-zA-Z0-9_]*(?:\.[a-zA-Z][a-zA-Z0-9_]*)+)\b/g;
+            let m;
+            while ((m = chainRe.exec(text)) !== null) {
+                const segments = m[1].split(".");
+                for (let i = 0; i < segments.length - 1; i++) {
+                    const lhs = segments[i].toLowerCase();
+                    const rhs = segments[i + 1];
+                    const fields = catalog.get(lhs);
+                    if (!fields)
+                        continue; // LHS isn't a known entity — skip.
+                    if (fields.has(rhs))
+                        continue; // Field exists.
+                    const key = `${lhs}.${rhs}`;
+                    if (seen.has(key))
+                        continue;
+                    seen.add(key);
+                    findings.push({
+                        path,
+                        message: `Spec references \`${segments[i]}.${rhs}\` but the ${lhs} entity has no \`${rhs}\` field. Known fields: ${[...fields].sort().join(", ") || "(none)"}.`,
+                        action: "flagged",
+                    });
+                }
+            }
+        }
+    }
+    return findings;
+}
+/**
+ * 0.19.x+ — check whether the mock files refine listed in
+ * `components_to_reuse` actually render the spec's data fields.
+ *
+ * Refine derives `components_to_reuse` from spec prose mentions of
+ * `src/components/...` paths (proposals-synth.ts:198). It doesn't
+ * verify the mock at that path actually mentions the fields the
+ * spec cares about. A reuse listing of the WRONG mock misleads
+ * brew into lifting unrelated UI.
+ *
+ * Concrete repro (delgoosh story-005):
+ *   spec.invariants reference user.firstName / user.lastName /
+ *   user.email / userLocation.city / userLocation.country / etc.
+ *   refine's components_to_reuse listed mock/src/app/patient/profile/page.tsx
+ *   which actually renders therapy PREFERENCES (topics/approach/gender/belief)
+ *   — none of the spec's fields appear in that mock at all.
+ *
+ * Heuristic: extract the set of unique field names mentioned in the
+ * spec's load-bearing sections (RHS of every dotted reference like
+ * `user.firstName`). For each `components_to_reuse` entry that names
+ * a real path, count how many of those field names appear in the
+ * file body. If overlap is < 25% of the spec's field set AND the
+ * file body is non-trivial (>500 chars — empty mocks aren't false
+ * positives), flag the entry.
+ *
+ * Action is "flagged" — the spec text isn't auto-repairable; the
+ * author needs to either drop the reuse listing or rebuild the
+ * mock at that path. Surfaced in run logs alongside other findings.
+ *
+ * Exported for testing.
+ */
+export function validateComponentReuseShape(spec, mockReader) {
+    const findings = [];
+    const reuse = spec.proposals?.ui_layout?.components_to_reuse;
+    if (!reuse || reuse.length === 0)
+        return findings;
+    // Extract every field-name (RHS-and-after of dotted refs) from
+    // load-bearing sections — same chain shape as
+    // validateEntityFieldReferences.
+    const sections = [
+        spec.invariants,
+        spec.preconditions,
+        spec.acceptance_scenarios,
+        spec.api_contract,
+        spec.ui_behavior,
+    ];
+    const specFields = new Set();
+    const chainRe = /\b[a-z][a-zA-Z0-9_]*(?:\.[a-zA-Z][a-zA-Z0-9_]*)+\b/g;
+    for (const section of sections) {
+        if (section == null)
+            continue;
+        for (const { text } of walkStrings(section)) {
+            let m;
+            while ((m = chainRe.exec(text)) !== null) {
+                const segments = m[0].split(".");
+                for (let i = 1; i < segments.length; i++) {
+                    specFields.add(segments[i]);
+                }
+            }
+        }
+    }
+    if (specFields.size === 0)
+        return findings;
+    for (let i = 0; i < reuse.length; i++) {
+        const entry = reuse[i];
+        // Skip backtick-name entries (`Component-name (path TBD)`) — no path to read.
+        const pathMatch = entry.match(/^(src\/[^\s(]+|mock\/[^\s(]+|apps\/[^\s(]+)/);
+        if (!pathMatch)
+            continue;
+        const body = mockReader(pathMatch[1]);
+        if (body == null) {
+            findings.push({
+                path: `proposals.ui_layout.components_to_reuse[${i}]`,
+                message: `Reuse target ${JSON.stringify(pathMatch[1])} does not exist on disk — path is wrong, or the mock hasn't been authored yet.`,
+                action: "flagged",
+            });
+            continue;
+        }
+        if (body.length < 500)
+            continue; // Empty / placeholder mock — not a false positive.
+        let hits = 0;
+        for (const f of specFields) {
+            const re = new RegExp(`\\b${f.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\b`);
+            if (re.test(body))
+                hits++;
+        }
+        const ratio = hits / specFields.size;
+        if (ratio < 0.25) {
+            findings.push({
+                path: `proposals.ui_layout.components_to_reuse[${i}]`,
+                message: `Reuse target ${JSON.stringify(pathMatch[1])} mentions only ${hits}/${specFields.size} of the spec's data fields (${Math.round(ratio * 100)}%). The mock likely renders a different surface — verify the listing or update the mock before brew lifts it.`,
+                action: "flagged",
+            });
+        }
+    }
+    return findings;
+}
 function pruneStringList(items, pathPrefix, findings) {
     const out = [];
     for (let i = 0; i < items.length; i++) {

package/dist/commands/refine/spec-validate.js.map

@@ -1 +1 @@
-{"version":3,"file":"spec-validate.js","sourceRoot":"","sources":["../../../src/commands/refine/spec-validate.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"spec-validate.js","sourceRoot":"","sources":["../../../src/commands/refine/spec-validate.ts"],"names":[],"mappings":"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"}

package/dist/commands/refresh-knowledge.d.ts

@@ -38,6 +38,7 @@
  *     ├── frontend-contexts.md  (mock/src/contexts/*-context.tsx hooks)
  *     ├── tokens.md             (Tailwind brand-token vocabulary)
  *     ├── config.md             (tsconfig paths + workspace + scripts)
+ *     ├── aliases.md            (every tsconfig + vite/vitest path alias)
  *     ├── migrations.md         (migration file timestamps + table names)
  *     └── routes-inventory.md   (filesystem-derived route URLs)
  *
@@ -102,6 +103,49 @@ export declare function buildConfigDigest(repoRoot: string): {
     body: string;
     built: boolean;
 };
+/**
+ * Parse a tsconfig.json body's `compilerOptions.paths` map.
+ * Strips JSON-with-comments before parsing (tsconfig allows
+ * `//` and `/* … *​/` per spec). Returns `{}` on parse failure.
+ *
+ * Exported for testing.
+ */
+export declare function parseTsconfigPaths(body: string): Record<string, string[]>;
+/**
+ * Regex-extract `resolve.alias` keys + (best-effort) target hints from
+ * a vite / vitest config body. The config is TS code and not safely
+ * parseable here; we capture the common literal-object form:
+ *
+ *   resolve: { alias: { "@": path.join(root, "src"), … } }
+ *
+ * Returns `Array<{ alias: string; targetHint: string }>` where
+ * `targetHint` is the raw RHS text (e.g., `path.join(root, "src")`).
+ * Agents reading the digest can interpret the hint contextually.
+ *
+ * Exported for testing.
+ */
+export declare function parseViteAliases(body: string): Array<{
+    alias: string;
+    targetHint: string;
+}>;
+/**
+ * Walks the workspace for tsconfig + vite/vitest configs and emits a
+ * single `aliases.md` listing every `@whatever`-style alias and what
+ * it resolves to in EACH context.
+ *
+ * Motivation: in a monorepo the same alias (e.g. `@/`) often means
+ * different things in different directories — root vitest config may
+ * map `@/` to root `src/`, mock workspace's tsconfig may map `@/` to
+ * `mock/src/`, and each Next.js app's tsconfig maps `@/` to its own
+ * `apps/<role>/src/`. Without a digest, agents see `@/foo/bar` in a
+ * file and can't tell which root it resolves against — they read the
+ * config file by hand on every cold start. (Surfaced in
+ * delgoosh/monorepo as a brew-vs-testgen path divergence.)
+ */
+export declare function buildAliasesDigest(repoRoot: string): {
+    body: string;
+    built: boolean;
+};
 export declare function buildMigrationsDigest(repoRoot: string): {
     body: string;
     built: boolean;

package/dist/commands/refresh-knowledge.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"refresh-knowledge.d.ts","sourceRoot":"","sources":["../../src/commands/refresh-knowledge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AA+CH;;GAEG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE;IAChC,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,MAAM,CAAC;CACrC,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,CAMnC;AAiID,wBAAgB,0BAA0B,CAAC,QAAQ,EAAE,MAAM;UAvI/C,MAAM;WAAS,OAAO;EA6JjC;AAED,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,MAAM;UA/J7C,MAAM;WAAS,OAAO;EAsLjC;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE,CAS1D;AAED,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,MAAM;UA/M5C,MAAM;WAAS,OAAO;EAyOjC;AAED,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,MAAM;UA3O7C,MAAM;WAAS,OAAO;EA0QjC;AAED,wBAAgB,6BAA6B,CAAC,QAAQ,EAAE,MAAM;UA5QlD,MAAM;WAAS,OAAO;EA2SjC;AAED,wBAAgB,2BAA2B,CAAC,QAAQ,EAAE,MAAM;UA7ShD,MAAM;WAAS,OAAO;EAiUjC;AAED,wBAAgB,yBAAyB,CAAC,QAAQ,EAAE,MAAM;UAnU9C,MAAM;WAAS,OAAO;EA8VjC;AAED,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM;UAhWtC,MAAM;WAAS,OAAO;EA4ZjC;AAED,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,MAAM;UA9Z1C,MAAM;WAAS,OAAO;EA+bjC;AAED,wBAAgB,0BAA0B,CAAC,QAAQ,EAAE,MAAM;UAjc/C,MAAM;WAAS,OAAO;EA4djC;AAID,MAAM,WAAW,sBAAsB;IACrC,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,GAAE;IAAE,IAAI,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,sBAAsB,CAuB3G;AAED;;;;;;GAMG;AACH,wBAAsB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAuBpE;AAuTD,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,gBAAgB,EAAE,MAAM,CAAC;IACzB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7B;AAED,wBAAgB,2BAA2B,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,GAAE;IAAE,UAAU,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,OAAO,CAAA;CAAO,GAAG,iBAAiB,CAsCnI"}
+{"version":3,"file":"refresh-knowledge.d.ts","sourceRoot":"","sources":["../../src/commands/refresh-knowledge.ts"],"names":[],"mappings":"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"}

package/dist/commands/refresh-knowledge.js

@@ -38,6 +38,7 @@
  *     ├── frontend-contexts.md  (mock/src/contexts/*-context.tsx hooks)
  *     ├── tokens.md             (Tailwind brand-token vocabulary)
  *     ├── config.md             (tsconfig paths + workspace + scripts)
+ *     ├── aliases.md            (every tsconfig + vite/vitest path alias)
  *     ├── migrations.md         (migration file timestamps + table names)
  *     └── routes-inventory.md   (filesystem-derived route URLs)
  *
@@ -547,6 +548,194 @@ export function buildConfigDigest(repoRoot) {
         },
     });
 }
+/**
+ * Parse a tsconfig.json body's `compilerOptions.paths` map.
+ * Strips JSON-with-comments before parsing (tsconfig allows
+ * `//` and `/* … *​/` per spec). Returns `{}` on parse failure.
+ *
+ * Exported for testing.
+ */
+export function parseTsconfigPaths(body) {
+    try {
+        const json = JSON.parse(body.replace(/\/\*[\s\S]*?\*\//g, "").replace(/\/\/.*$/gm, ""));
+        return json.compilerOptions?.paths ?? {};
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * Regex-extract `resolve.alias` keys + (best-effort) target hints from
+ * a vite / vitest config body. The config is TS code and not safely
+ * parseable here; we capture the common literal-object form:
+ *
+ *   resolve: { alias: { "@": path.join(root, "src"), … } }
+ *
+ * Returns `Array<{ alias: string; targetHint: string }>` where
+ * `targetHint` is the raw RHS text (e.g., `path.join(root, "src")`).
+ * Agents reading the digest can interpret the hint contextually.
+ *
+ * Exported for testing.
+ */
+export function parseViteAliases(body) {
+    // Find the `alias: {` opener, then walk char-by-char to find its
+    // matching close brace (brace-balanced — naive regex can't do this
+    // because the values may themselves contain `{}`).
+    const opener = body.match(/\balias\s*:\s*\{/);
+    if (!opener || opener.index === undefined)
+        return [];
+    let start = opener.index + opener[0].length;
+    let depth = 1;
+    let end = start;
+    let qChar2 = null;
+    while (end < body.length && depth > 0) {
+        const c = body[end];
+        if (qChar2) {
+            if (c === qChar2 && body[end - 1] !== "\\")
+                qChar2 = null;
+        }
+        else if (c === '"' || c === "'" || c === "`") {
+            qChar2 = c;
+        }
+        else if (c === "{")
+            depth++;
+        else if (c === "}")
+            depth--;
+        if (depth === 0)
+            break;
+        end++;
+    }
+    const block = body.slice(start, end);
+    const out = [];
+    // Walk character-by-character so the value's parens / quotes don't
+    // confuse a naive regex (e.g., `path.join(root, "src")` contains a
+    // comma but is one value).
+    let i = 0;
+    while (i < block.length) {
+        // Skip whitespace + commas.
+        while (i < block.length && /[\s,]/.test(block[i]))
+            i++;
+        if (i >= block.length)
+            break;
+        // Expect a quote for the alias key.
+        const q = block[i];
+        if (q !== '"' && q !== "'") {
+            // Not at a key — advance to next char.
+            i++;
+            continue;
+        }
+        i++; // past opening quote
+        const keyStart = i;
+        while (i < block.length && block[i] !== q)
+            i++;
+        const alias = block.slice(keyStart, i);
+        i++; // past closing quote
+        // Skip to colon.
+        while (i < block.length && /\s/.test(block[i]))
+            i++;
+        if (block[i] !== ":")
+            continue;
+        i++; // past colon
+        while (i < block.length && /\s/.test(block[i]))
+            i++;
+        // Capture value until top-level comma or newline (paren-aware).
+        const valStart = i;
+        let depth = 0;
+        let qChar = null;
+        while (i < block.length) {
+            const c = block[i];
+            if (qChar) {
+                if (c === qChar && block[i - 1] !== "\\")
+                    qChar = null;
+                i++;
+                continue;
+            }
+            if (c === '"' || c === "'" || c === "`") {
+                qChar = c;
+                i++;
+                continue;
+            }
+            if (c === "(" || c === "[" || c === "{")
+                depth++;
+            else if (c === ")" || c === "]" || c === "}")
+                depth--;
+            else if (depth === 0 && (c === "," || c === "\n"))
+                break;
+            i++;
+        }
+        const targetHint = block.slice(valStart, i).trim();
+        if (alias && targetHint)
+            out.push({ alias, targetHint });
+    }
+    return out;
+}
+/**
+ * Walks the workspace for tsconfig + vite/vitest configs and emits a
+ * single `aliases.md` listing every `@whatever`-style alias and what
+ * it resolves to in EACH context.
+ *
+ * Motivation: in a monorepo the same alias (e.g. `@/`) often means
+ * different things in different directories — root vitest config may
+ * map `@/` to root `src/`, mock workspace's tsconfig may map `@/` to
+ * `mock/src/`, and each Next.js app's tsconfig maps `@/` to its own
+ * `apps/<role>/src/`. Without a digest, agents see `@/foo/bar` in a
+ * file and can't tell which root it resolves against — they read the
+ * config file by hand on every cold start. (Surfaced in
+ * delgoosh/monorepo as a brew-vs-testgen path divergence.)
+ */
+export function buildAliasesDigest(repoRoot) {
+    // Walk for tsconfigs (at root + per-workspace).
+    const tsconfigs = findFilesByGlob(repoRoot, /(?:^|\/)tsconfig\.json$/, {
+        maxDepth: 5,
+    });
+    // Walk for vite + vitest configs (TS/JS/MJS).
+    const viteConfigs = findFilesByGlob(repoRoot, /(?:^|\/)vite(?:st)?\.config\.(?:ts|js|mjs)$/, { maxDepth: 5 });
+    return buildDigest({
+        repoRoot,
+        name: "aliases",
+        inputFiles: [...tsconfigs, ...viteConfigs],
+        build: (inputs) => {
+            const rows = [];
+            for (const rel of inputs) {
+                const body = safeRead(repoRoot, rel);
+                if (!body)
+                    continue;
+                if (rel.endsWith("tsconfig.json")) {
+                    const paths = parseTsconfigPaths(body);
+                    for (const [alias, targets] of Object.entries(paths)) {
+                        rows.push({
+                            alias,
+                            source: rel,
+                            target: targets.join(" | "),
+                        });
+                    }
+                }
+                else {
+                    for (const e of parseViteAliases(body)) {
+                        rows.push({
+                            alias: e.alias,
+                            source: rel,
+                            target: e.targetHint,
+                        });
+                    }
+                }
+            }
+            const lines = [];
+            lines.push("# Path aliases\n");
+            lines.push("Auto-extracted from every `tsconfig.json` + `vite(st).config.{ts,js,mjs}` in the workspace. In a monorepo the SAME alias (e.g. `@/`) often resolves differently from different directories — agents should consult this digest before assuming where an `@/foo/bar` import lands.\n");
+            if (rows.length === 0) {
+                lines.push("_(No path aliases detected.)_");
+                return lines.join("\n");
+            }
+            lines.push("| Alias | Source | Target |");
+            lines.push("|---|---|---|");
+            for (const r of rows) {
+                lines.push(`| \`${r.alias}\` | \`${r.source}\` | \`${r.target}\` |`);
+            }
+            return lines.join("\n");
+        },
+    });
+}
 export function buildMigrationsDigest(repoRoot) {
     const files = findFilesByGlob(repoRoot, /\/migrations\/\d+[^/]*\.ts$/);
     return buildDigest({
@@ -624,6 +813,7 @@ export function refreshKnowledgeAuto(repoRoot, opts = {}) {
         { name: "frontend-contexts", fn: () => buildFrontendContextsDigest(repoRoot) },
         { name: "tokens", fn: () => buildTailwindTokensDigest(repoRoot) },
         { name: "config", fn: () => buildConfigDigest(repoRoot) },
+        { name: "aliases", fn: () => buildAliasesDigest(repoRoot) },
         { name: "migrations", fn: () => buildMigrationsDigest(repoRoot) },
         { name: "routes-inventory", fn: () => buildRoutesInventoryDigest(repoRoot) },
     ];