frontend-harness 0.7.10 → 0.8.1

package/dist/runtime/knowledge/core.js

@@ -3,7 +3,16 @@ import path from "node:path";
 import { isDirectoryWithoutSymlink, isRegularFileWithoutSymlink, writeJson, writeText } from "../../storage/json.js";
 import { harnessPath, relativeHarnessPath } from "../../storage/paths.js";
 import { normalizeProjectRelativePath } from "../project-paths.js";
+import { showIngestRecord } from "../ingest.js";
 import { kindTypeMap, knowledgeKinds, knowledgeStabilities, knowledgeStatuses, knowledgeTypes, MAX_KNOWLEDGE_DIRECTORY_DEPTH, MAX_KNOWLEDGE_MARKDOWN_BYTES, MAX_KNOWLEDGE_MARKDOWN_FILES } from "./constants.js";
+export const MAX_KNOWLEDGE_LIST_CARDS = 20;
+export const MAX_KNOWLEDGE_SEARCH_RESULTS = 8;
+export const MAX_KNOWLEDGE_DRAFT_UPDATE_CANDIDATES = 8;
+export const MAX_KNOWLEDGE_OUTLINE_HEADINGS = 80;
+export const MAX_KNOWLEDGE_DRAFT_EXTRACTION_ITEMS = 40;
+export const MAX_KNOWLEDGE_INDEX_CARDS = 20;
+export const MAX_KNOWLEDGE_INDEX_DETAIL_ITEMS = 20;
+const MAX_KNOWLEDGE_REFERENCE_SUGGESTIONS = 20;
 export function promoteKnowledge(projectRoot, input) {
     const title = input.title?.trim();
     const body = input.body?.trim();
@@ -121,11 +130,13 @@ export function addKnowledge(projectRoot, input) {
     const contentFields = atomicContentFields(kind, input);
     const inputSummary = input.summary?.trim();
     const contentSummary = inputSummary || summarizeAtomicContent(kind, subject, contentFields);
+    const sourcePaths = parseKnowledgeSourcePaths(input.source, "knowledge add --source");
+    const type = typeForAtomicKnowledge(kind, sourcePaths);
     const rendered = renderAtomicKnowledge({
         id,
         title,
         summary: contentSummary,
-        type: kindTypeMap[kind],
+        type,
         kind,
         subject,
         status,
@@ -133,7 +144,7 @@ export function addKnowledge(projectRoot, input) {
         createdAt,
         scope: splitList(input.scope),
         tags: splitList(input.tags),
-        sourcePaths: parseKnowledgeSourcePaths(input.source, "knowledge add --source"),
+        sourcePaths,
         verification: splitList(input.verification),
         coverage: splitList(input.coverage),
         prdAnchors: splitList(input.anchor),
@@ -144,12 +155,435 @@ export function addKnowledge(projectRoot, input) {
         path: relativePath,
         id,
         title,
-        type: kindTypeMap[kind],
+        type,
         status,
         stability,
         createdAt
     };
 }
+export function outlineKnowledgeFromIngest(projectRoot, input) {
+    if (!input.ref?.trim()) {
+        throw new Error("knowledge outline requires --ref ingest://<kind>/<source-id>");
+    }
+    const record = showIngestRecord(projectRoot, input.ref);
+    const outlineSelection = buildKnowledgeOutline(projectRoot, record);
+    return {
+        contractVersion: 1,
+        ingestRef: record.ingestRef,
+        ingestKind: record.kind,
+        source: record.source.value,
+        sourceType: record.source.type,
+        outline: outlineSelection.headings,
+        limits: {
+            headings: outlineSelection.limits
+        }
+    };
+}
+export function draftKnowledgeFromIngest(projectRoot, input) {
+    if (!input.ref?.trim()) {
+        throw new Error("knowledge draft requires --ref ingest://<kind>/<source-id>");
+    }
+    const record = showIngestRecord(projectRoot, input.ref);
+    const recommendedKind = recommendedKnowledgeKind(record.kind);
+    const recommendedType = typeForAtomicKnowledge(recommendedKind, [record.ingestRef]);
+    const subject = draftSubject(record);
+    const id = slugify(`${subject}-${recommendedKind}`) || `${record.id}-${recommendedKind}`;
+    const defaults = {
+        id,
+        kind: recommendedKind,
+        subject,
+        summary: record.summary,
+        source: record.ingestRef,
+        coverage: draftCoveragePlaceholder(record.kind),
+        verification: draftVerificationPlaceholder(record.kind),
+        scope: draftScope(record),
+        tags: draftTags(record.kind)
+    };
+    const contentFlag = contentFlagForKind(recommendedKind);
+    const updateCandidateSelection = draftUpdateCandidates(projectRoot, record, defaults);
+    const updateCandidates = updateCandidateSelection.candidates;
+    const outlineSelection = buildKnowledgeOutline(projectRoot, record);
+    const extractionItemSelection = draftExtractionItems(record, outlineSelection.headings, updateCandidates);
+    const outlineLimits = outlineSelection.limits.total > 0 ? outlineSelection.limits : undefined;
+    const extractionLimits = extractionItemSelection.limits.total > 0 ? extractionItemSelection.limits : undefined;
+    const args = [
+        "knowledge",
+        "add",
+        "--json",
+        "--id",
+        defaults.id,
+        "--kind",
+        defaults.kind,
+        "--subject",
+        defaults.subject,
+        "--summary",
+        defaults.summary,
+        `--${contentFlag}`,
+        `<atomic ${contentFlag} distilled from ${record.ingestRef}>`,
+        "--source",
+        defaults.source,
+        "--coverage",
+        defaults.coverage,
+        "--verification",
+        defaults.verification,
+        "--scope",
+        defaults.scope,
+        "--tags",
+        defaults.tags
+    ];
+    return {
+        contractVersion: 1,
+        ingestRef: record.ingestRef,
+        ingestKind: record.kind,
+        source: record.source.value,
+        summary: record.summary,
+        recommendedKind,
+        recommendedType,
+        recommendedAction: updateCandidates.length > 0 ? "update" : "add",
+        command: "frontend-harness knowledge add --json",
+        args,
+        updateCandidates,
+        ...(outlineSelection.headings.length ? { outline: outlineSelection.headings } : {}),
+        ...(extractionItemSelection.items.length ? { extractionItems: extractionItemSelection.items } : {}),
+        limits: {
+            updateCandidates: updateCandidateSelection.limits,
+            ...(outlineLimits ? { outlineHeadings: outlineLimits } : {}),
+            ...(extractionLimits ? { extractionItems: extractionLimits } : {})
+        },
+        requiredEdits: [
+            ...(updateCandidateSelection.limits.total > 0
+                ? ["Prefer a matching update candidate before adding a new card for the same source."]
+                : []),
+            ...(extractionItemSelection.items.length
+                ? ["Use extractionItems as the source checklist; add, update, or explicitly skip each required source block."]
+                : []),
+            `Replace --${contentFlag} with one atomic durable fact; create separate cards for separate facts.`,
+            "Replace --coverage with the precise source section, endpoint, screen, or acceptance block.",
+            "Replace --verification with the concrete check or evidence that proves the fact still holds.",
+            "Narrow --scope and --tags so future context selection can find the card without broad matching."
+        ],
+        defaults
+    };
+}
+function draftUpdateCandidates(projectRoot, record, defaults) {
+    const producedIds = new Set(record.producedKnowledgeCardIds);
+    const cards = discoverKnowledgeCards(projectRoot);
+    const matches = cards
+        .filter((card) => producedIds.has(card.id) || card.sourcePaths.some((sourcePath) => sameKnowledgeSourceReference(sourcePath, record.ingestRef) || sameKnowledgeSourceReference(sourcePath, record.source.value)))
+        .sort((left, right) => left.id.localeCompare(right.id));
+    const selected = matches
+        .slice(0, MAX_KNOWLEDGE_DRAFT_UPDATE_CANDIDATES)
+        .map((card) => ({
+        id: card.id,
+        path: card.path,
+        title: card.title,
+        summary: card.summary,
+        sourcePaths: card.sourcePaths,
+        command: "frontend-harness knowledge update --json",
+        args: [
+            "knowledge",
+            "update",
+            "--json",
+            "--id",
+            card.id,
+            "--summary",
+            defaults.summary,
+            "--source",
+            defaults.source,
+            "--coverage",
+            defaults.coverage,
+            "--verification",
+            defaults.verification,
+            "--scope",
+            defaults.scope,
+            "--tags",
+            defaults.tags
+        ]
+    }));
+    return {
+        candidates: selected,
+        limits: {
+            selected: selected.length,
+            total: matches.length,
+            omitted: Math.max(0, matches.length - selected.length)
+        }
+    };
+}
+function buildKnowledgeOutline(projectRoot, record) {
+    if (record.kind !== "prd" || record.source.type !== "project-file" || !/\.md$/i.test(record.source.value)) {
+        return {
+            headings: [],
+            limits: { selected: 0, total: 0, omitted: 0 }
+        };
+    }
+    const fullPath = path.join(projectRoot, record.source.value);
+    const content = safeRead(fullPath);
+    if (content === null) {
+        return {
+            headings: [],
+            limits: { selected: 0, total: 0, omitted: 0 }
+        };
+    }
+    const headings = parseKnowledgeOutlineHeadings(content);
+    const selected = headings.slice(0, MAX_KNOWLEDGE_OUTLINE_HEADINGS);
+    return {
+        headings: selected,
+        limits: {
+            selected: selected.length,
+            total: headings.length,
+            omitted: Math.max(0, headings.length - selected.length)
+        }
+    };
+}
+function parseKnowledgeOutlineHeadings(content) {
+    const lines = content.split(/\r?\n/);
+    const rawHeadings = [];
+    const stack = [];
+    const idCounts = new Map();
+    lines.forEach((line, index) => {
+        const match = /^(#{1,6})\s+(.+?)\s*$/.exec(line);
+        if (!match?.[1] || !match[2]) {
+            return;
+        }
+        const level = match[1].length;
+        const title = match[2].replace(/\s+#+$/, "").trim();
+        if (!title) {
+            return;
+        }
+        while (stack.length && stack[stack.length - 1].level >= level) {
+            stack.pop();
+        }
+        const baseId = slugify(title) || `heading-${index + 1}`;
+        const count = idCounts.get(baseId) ?? 0;
+        idCounts.set(baseId, count + 1);
+        const id = count === 0 ? baseId : `${baseId}-${count + 1}`;
+        const parent = stack[stack.length - 1] ?? null;
+        const headingPath = [...(parent?.path ?? []), title];
+        rawHeadings.push({
+            id,
+            title,
+            level,
+            lineStart: index + 1,
+            parentId: parent?.id ?? null,
+            path: headingPath
+        });
+        stack.push({ id, level, title, path: headingPath });
+    });
+    return rawHeadings.map((heading, index) => {
+        const nextHeading = rawHeadings.slice(index + 1).find((candidate) => candidate.level <= heading.level);
+        const classification = classifyOutlineHeading(heading.title, heading.path);
+        return {
+            ...heading,
+            lineEnd: nextHeading ? nextHeading.lineStart - 1 : lines.length,
+            extractionRequired: classification.extractionRequired,
+            suggestedKind: classification.suggestedKind,
+            reason: classification.reason,
+            coverage: heading.path.join(" > ")
+        };
+    });
+}
+function classifyOutlineHeading(title, headingPath) {
+    const text = normalize([...headingPath, title].join(" "));
+    if (/(?:不做|不扩展|边界|风险|异常|歧义|pitfall|risk|out of scope|non goal|not doing)/i.test(text)) {
+        return {
+            extractionRequired: true,
+            suggestedKind: "pitfall",
+            reason: "source block describes boundary, exception, risk, ambiguity, or non-goal information"
+        };
+    }
+    if (/(?:权限|按钮|操作|可见|允许|禁止|permission|button|action|visibility)/i.test(text)) {
+        return {
+            extractionRequired: true,
+            suggestedKind: "permission",
+            reason: "source block describes action availability, visibility, or permission behavior"
+        };
+    }
+    if (/(?:流程|链路|流转|workflow|process|journey|flow|lifecycle|状态机)/i.test(text)) {
+        return {
+            extractionRequired: true,
+            suggestedKind: "workflow",
+            reason: "source block describes workflow, lifecycle, or state transition semantics"
+        };
+    }
+    if (/(?:字段|枚举|状态|术语|定义|field|enum|status|term|definition)/i.test(text)) {
+        return {
+            extractionRequired: true,
+            suggestedKind: "term",
+            reason: "source block defines fields, states, terms, or enumerations"
+        };
+    }
+    if (/(?:模块|页面结构|区域|信息层级|布局|module|section|layout|region)/i.test(text)) {
+        return {
+            extractionRequired: true,
+            suggestedKind: "module_summary",
+            reason: "source block describes module, page region, layout, or structure boundaries"
+        };
+    }
+    if (/(?:规则|校验|验收|条件|策略|计算|rule|validation|acceptance|criteria|condition|policy)/i.test(text)) {
+        return {
+            extractionRequired: true,
+            suggestedKind: "rule",
+            reason: "source block describes durable rule, validation, acceptance, condition, or policy"
+        };
+    }
+    return {
+        extractionRequired: false,
+        suggestedKind: "none",
+        reason: "source block appears descriptive; mark skip if it has no durable implementation knowledge"
+    };
+}
+function draftExtractionItems(record, headings, sourceUpdateCandidates) {
+    const requiredHeadings = headings.filter((heading) => heading.extractionRequired && heading.suggestedKind !== "none");
+    const items = requiredHeadings
+        .slice(0, MAX_KNOWLEDGE_DRAFT_EXTRACTION_ITEMS)
+        .map((heading) => draftExtractionItem(record, heading, sourceUpdateCandidates));
+    return {
+        items,
+        limits: {
+            selected: items.length,
+            total: requiredHeadings.length,
+            omitted: Math.max(0, requiredHeadings.length - items.length)
+        }
+    };
+}
+function draftExtractionItem(record, heading, sourceUpdateCandidates) {
+    if (heading.suggestedKind === "none") {
+        throw new Error(`cannot draft extraction item for non-required heading: ${heading.id}`);
+    }
+    const suggestedKind = heading.suggestedKind === "module_summary" ? "module_summary" : heading.suggestedKind;
+    const subject = titleCase(heading.title.replace(/^\d+(?:\.\d+)*\s*/, ""));
+    const scope = draftScope(record);
+    const tags = suggestedKind === "module_summary" ? `prd,module,${scope}` : `prd,${suggestedKind},${scope}`;
+    const itemId = slugify(`${record.id}-${heading.title}`) || `${record.id}-${heading.id}`;
+    const updateCandidates = sourceUpdateCandidates.filter((candidate) => candidate.title.includes(heading.title) || candidate.summary.includes(heading.title) || candidate.id.includes(slugify(heading.title)));
+    if (suggestedKind === "module_summary") {
+        return {
+            id: itemId,
+            headingId: heading.id,
+            title: heading.title,
+            coverage: heading.coverage,
+            suggestedKind,
+            extractionRequired: true,
+            reason: heading.reason,
+            command: "frontend-harness knowledge module --json",
+            args: [
+                "knowledge",
+                "module",
+                "--json",
+                "--id",
+                itemId,
+                "--title",
+                subject,
+                "--summary",
+                `<module summary distilled from ${heading.coverage}>`,
+                "--body",
+                `<structured module facts from ${heading.coverage}>`,
+                "--source",
+                record.ingestRef,
+                "--coverage",
+                heading.coverage,
+                "--verification",
+                "<specific check or evidence required>",
+                "--scope",
+                scope,
+                "--tags",
+                tags
+            ],
+            updateCandidates
+        };
+    }
+    const kind = suggestedKind;
+    const contentFlag = contentFlagForKind(kind);
+    return {
+        id: itemId,
+        headingId: heading.id,
+        title: heading.title,
+        coverage: heading.coverage,
+        suggestedKind: kind,
+        extractionRequired: true,
+        reason: heading.reason,
+        command: "frontend-harness knowledge add --json",
+        args: [
+            "knowledge",
+            "add",
+            "--json",
+            "--id",
+            itemId,
+            "--kind",
+            kind,
+            "--subject",
+            subject,
+            "--summary",
+            `<summary distilled from ${heading.coverage}>`,
+            `--${contentFlag}`,
+            `<atomic ${contentFlag} distilled from ${heading.coverage}>`,
+            "--source",
+            record.ingestRef,
+            "--coverage",
+            heading.coverage,
+            "--verification",
+            "<specific check or evidence required>",
+            "--scope",
+            scope,
+            "--tags",
+            tags
+        ],
+        updateCandidates
+    };
+}
+function recommendedKnowledgeKind(kind) {
+    if (kind === "openapi") {
+        return "workflow";
+    }
+    return "rule";
+}
+function typeForAtomicKnowledge(kind, sourcePaths) {
+    if (sourcePaths.some(isApiContractSourcePath)) {
+        return "api_contract";
+    }
+    return kindTypeMap[kind];
+}
+function isApiContractSourcePath(sourcePath) {
+    const normalized = sourcePath.replace(/\\/g, "/");
+    if (/^ingest:\/\/openapi\//i.test(normalized)) {
+        return isIngestReference(normalized);
+    }
+    if (/(^|\/)(openapi|swagger)(\/|[-_.])/i.test(normalized)) {
+        return true;
+    }
+    return /(^|\/)api\/[^/]+\.(?:json|ya?ml)$/i.test(normalized);
+}
+function draftSubject(record) {
+    const sourceName = path.basename(record.source.value).replace(/\.[^.]+$/, "");
+    const raw = sourceName || record.id;
+    return titleCase(raw.replace(/[-_.]+/g, " ")).trim() || record.id;
+}
+function draftScope(record) {
+    return record.id.replace(/[^a-z0-9-]+/gi, "-").toLowerCase();
+}
+function draftCoveragePlaceholder(kind) {
+    if (kind === "ui-package") {
+        return "<screen, component, state, or visual reference>";
+    }
+    if (kind === "openapi") {
+        return "<endpoint, schema, operation, or contract behavior>";
+    }
+    return "<precise section, endpoint, screen, or acceptance block>";
+}
+function draftVerificationPlaceholder(kind) {
+    if (kind === "ui-package") {
+        return "<visual, responsive, or interaction evidence required>";
+    }
+    if (kind === "openapi") {
+        return "<contract shape check or mocked integration evidence required>";
+    }
+    return "<specific check or evidence required>";
+}
+function draftTags(kind) {
+    return kind === "ui-package"
+        ? "ui-package,ui"
+        : kind.replace(/[^a-z0-9-]+/gi, "-").toLowerCase();
+}
 export function updateKnowledge(projectRoot, input) {
     const target = input.id?.trim() || input.path?.trim();
     if (!target) {
@@ -231,6 +665,7 @@ export function indexKnowledge(projectRoot) {
     const cards = discoverKnowledgeCards(projectRoot);
     const prdSources = summarizePrdSources(projectRoot, cards);
     const moduleSummaries = summarizeModules(cards);
+    const selectedCards = cards.slice(0, MAX_KNOWLEDGE_INDEX_CARDS);
     const result = {
         artifactPath: relativeHarnessPath("knowledge", "index.json"),
         cardCount: cards.length,
@@ -242,7 +677,14 @@ export function indexKnowledge(projectRoot) {
         byKind: countByKind(cards),
         moduleSummaries,
         prdSources,
-        cards: cards.map(stripSearchable)
+        cards: selectedCards.map(stripSearchable),
+        limits: {
+            cards: {
+                selected: selectedCards.length,
+                total: cards.length,
+                omitted: Math.max(0, cards.length - selectedCards.length)
+            }
+        }
     };
     writeJson(path.join(projectRoot, result.artifactPath), result);
     return result;
@@ -270,7 +712,7 @@ export function checkKnowledgeCoverage(projectRoot, options = {}) {
         .filter((source) => source.activeCardCount === 0)
         .map((source) => source.path);
     const missingSourcePaths = [...new Set(cards.flatMap((card) => card.sourcePaths)
-            .filter((sourcePath) => sourcePath && !isExternalReference(sourcePath) && !isKnowledgeSourceFile(projectRoot, sourcePath)))].sort();
+            .filter((sourcePath) => sourcePath && !isExternalReference(sourcePath) && !isResolvedKnowledgeSource(projectRoot, sourcePath)))].sort();
     const cardsWithoutSource = cards
         .filter((card) => card.status === "active" && card.type === "prd_semantics" && card.sourcePaths.length === 0)
         .map((card) => card.path);
@@ -320,15 +762,23 @@ export function listKnowledge(projectRoot, options = {}) {
     const cards = discoverKnowledgeCards(projectRoot)
         .filter((card) => options.includeDeprecated || card.status === "active")
         .map(stripSearchable);
-    return { cards };
+    const selected = cards.slice(0, MAX_KNOWLEDGE_LIST_CARDS);
+    return {
+        cards: selected,
+        limits: {
+            selected: selected.length,
+            total: cards.length,
+            omitted: Math.max(0, cards.length - selected.length)
+        }
+    };
 }
 export function searchKnowledge(projectRoot, query, options = {}) {
     const normalizedQuery = normalize(query ?? "");
     if (!normalizedQuery) {
         throw new Error("knowledge search requires --query");
     }
-    const limit = options.limit && options.limit > 0 ? options.limit : 8;
-    const cards = discoverKnowledgeCards(projectRoot)
+    const limit = options.limit && options.limit > 0 ? options.limit : MAX_KNOWLEDGE_SEARCH_RESULTS;
+    const matches = discoverKnowledgeCards(projectRoot)
         .filter((card) => options.includeDeprecated || card.status === "active")
         .map((card) => ({
         card,
@@ -340,13 +790,22 @@ export function searchKnowledge(projectRoot, query, options = {}) {
             return right.score - left.score;
         }
         return left.card.path.localeCompare(right.card.path);
-    })
+    });
+    const cards = matches
         .slice(0, limit)
         .map(({ card, score }) => ({
         ...stripSearchable(card),
         score
     }));
-    return { query: query ?? "", cards };
+    return {
+        query: query ?? "",
+        cards,
+        limits: {
+            selected: cards.length,
+            total: matches.length,
+            omitted: Math.max(0, matches.length - cards.length)
+        }
+    };
 }
 export function showKnowledge(projectRoot, idOrPath) {
     const target = idOrPath?.trim();
@@ -368,6 +827,9 @@ export function showKnowledge(projectRoot, idOrPath) {
         body: extractMarkdownBody(content)
     };
 }
+function sameKnowledgeSourceReference(left, right) {
+    return left.replace(/\\/g, "/").toLowerCase() === right.replace(/\\/g, "/").toLowerCase();
+}
 export function checkKnowledge(projectRoot) {
     const knowledgeRoot = harnessPath(projectRoot, "knowledge");
     const relativeRoot = path.relative(projectRoot, knowledgeRoot).split(path.sep).join(path.posix.sep);
@@ -431,6 +893,15 @@ export function checkKnowledge(projectRoot) {
             if (contentValue && normalize(contentValue) === normalize(parsed.metadata.summary ?? "")) {
                 warnings.push(`${relativePath} summary duplicates the primary atomic content; use summary for context and the primary field for the durable rule.`);
             }
+            if (parsed.metadata.status === "active" && parsed.metadata.sourcePaths.some((sourcePath) => sourcePath.toLowerCase().startsWith("ingest://"))) {
+                errors.push(...ingestLinkedAtomicMetadataErrors(relativePath, parsed.metadata));
+            }
+            for (const coverage of parsed.metadata.coverage.filter(isDraftPlaceholderCoverage)) {
+                errors.push(`${relativePath} coverage contains an unedited knowledge draft placeholder: ${coverage}.`);
+            }
+            for (const verification of parsed.metadata.verification.filter(isDraftPlaceholderVerification)) {
+                errors.push(`${relativePath} verification contains an unedited knowledge draft placeholder: ${verification}.`);
+            }
             if (parsed.metadata.sourcePaths.some(isPrdSourcePath) && parsed.metadata.coverage.length === 0) {
                 warnings.push(`${relativePath} should include coverage items for PRD block traceability.`);
             }
@@ -442,7 +913,7 @@ export function checkKnowledge(projectRoot) {
             warnings.push(`${relativePath} frontmatter coverage disagrees with body traceability.`);
         }
         for (const sourcePath of parsed.metadata.sourcePaths) {
-            if (sourcePath && !isExternalReference(sourcePath) && !isKnowledgeSourceFile(projectRoot, sourcePath)) {
+            if (sourcePath && !isExternalReference(sourcePath) && !isResolvedKnowledgeSource(projectRoot, sourcePath)) {
                 warnings.push(`${relativePath} source path is missing or unsafe: ${sourcePath}.`);
             }
         }
@@ -546,17 +1017,22 @@ function resolveKnowledgeCardReference(cards, target) {
         return idMatches[0] ?? null;
     }
     if (idMatches.length > 1) {
-        throw new Error(`knowledge card reference is ambiguous: ${target}. Use --path with one of: ${idMatches.map((item) => item.path).join(", ")}.`);
+        throw new Error(formatAmbiguousKnowledgeReference(target, idMatches));
     }
     const pathSuffixMatches = cards.filter((item) => item.path.endsWith(`/${target}`));
     if (pathSuffixMatches.length === 1) {
         return pathSuffixMatches[0] ?? null;
     }
     if (pathSuffixMatches.length > 1) {
-        throw new Error(`knowledge card reference is ambiguous: ${target}. Use --path with one of: ${pathSuffixMatches.map((item) => item.path).join(", ")}.`);
+        throw new Error(formatAmbiguousKnowledgeReference(target, pathSuffixMatches));
     }
     return null;
 }
+function formatAmbiguousKnowledgeReference(target, matches) {
+    const selected = matches.slice(0, MAX_KNOWLEDGE_REFERENCE_SUGGESTIONS).map((item) => item.path);
+    const omitted = Math.max(0, matches.length - selected.length);
+    return `knowledge card reference is ambiguous: ${target}. Use --path with one of (selected: ${selected.length}; total: ${matches.length}; omitted: ${omitted}): ${selected.join(", ")}.`;
+}
 function parseKnowledgeFrontmatter(content) {
     const metadata = {
         scope: [],
@@ -932,6 +1408,9 @@ function validateKnowledgeSourcePath(value) {
     if (!value.trim()) {
         return "empty";
     }
+    if (value.toLowerCase().startsWith("ingest://")) {
+        return isIngestReference(value) ? null : "unsafe";
+    }
     if (isExternalReference(value)) {
         return null;
     }
@@ -946,6 +1425,13 @@ function validateKnowledgeSourcePath(value) {
 function isKnowledgeSourceFile(projectRoot, sourcePath) {
     return isRegularFileWithoutSymlink(path.join(projectRoot, sourcePath));
 }
+function isResolvedKnowledgeSource(projectRoot, sourcePath) {
+    if (isIngestReference(sourcePath)) {
+        const parsed = parseIngestReference(sourcePath);
+        return parsed !== null && isRegularFileWithoutSymlink(harnessPath(projectRoot, "ingest", parsed.kind, `${parsed.id}.json`));
+    }
+    return isKnowledgeSourceFile(projectRoot, sourcePath);
+}
 function mergeList(existing, next) {
     if (next === undefined) {
         return existing;
@@ -1142,11 +1628,29 @@ function extractMarkdownBody(content) {
     return content.slice(endIndex).replace(/^\r?\n---\r?\n?/, "").trim();
 }
 function isExternalReference(value) {
+    if (value.toLowerCase().startsWith("ingest://")) {
+        return false;
+    }
     if (/^[A-Za-z]:/.test(value)) {
         return false;
     }
     return /^[a-z][a-z0-9+.-]*:/i.test(value);
 }
+function isIngestReference(value) {
+    return /^ingest:\/\/(?:prd|openapi|ui-package)\/[a-z0-9][a-z0-9._-]{1,80}$/i.test(value)
+        && !value.includes("..")
+        && !/[?#]/.test(value);
+}
+function parseIngestReference(value) {
+    const match = /^ingest:\/\/(prd|openapi|ui-package)\/([a-z0-9][a-z0-9._-]{1,80})$/i.exec(value);
+    if (!match?.[1] || !match[2]) {
+        return null;
+    }
+    return {
+        kind: match[1].toLowerCase(),
+        id: match[2]
+    };
+}
 function isBroadCoverageItem(value) {
     const normalized = value.trim().toLowerCase();
     if (!normalized) {
@@ -1167,6 +1671,35 @@ function hasCoverageBodyDrift(projectRoot, card) {
     const content = safeRead(path.join(projectRoot, card.path));
     return content !== null && /\bCoverage:\s*Not specified\./i.test(extractMarkdownBody(content));
 }
+function isDraftPlaceholderCoverage(value) {
+    const normalized = value.trim().toLowerCase();
+    return (normalized.startsWith("<") || normalized.endsWith(">"))
+        && (normalized.includes("precise section")
+            || normalized.includes("acceptance block")
+            || normalized === "<precise"
+            || normalized === "or acceptance block>");
+}
+function isDraftPlaceholderVerification(value) {
+    const normalized = value.trim().toLowerCase();
+    return /^<.*>$/.test(normalized)
+        && normalized.includes("specific")
+        && (normalized.includes("check") || normalized.includes("evidence"));
+}
+function ingestLinkedAtomicMetadataErrors(relativePath, metadata) {
+    const errors = [];
+    const requiredLists = [
+        ["scope", metadata.scope],
+        ["tags", metadata.tags],
+        ["coverage", metadata.coverage],
+        ["verification", metadata.verification]
+    ];
+    for (const [field, values] of requiredLists) {
+        if (values.length === 0) {
+            errors.push(`${relativePath} active ingest-linked atomic knowledge must include ${field}.`);
+        }
+    }
+    return errors;
+}
 function summarizePrdSources(projectRoot, cards, requiredSources = []) {
     const grouped = new Map();
     for (const sourcePath of discoverPrdSourceFiles(projectRoot)) {
@@ -1182,16 +1715,30 @@ function summarizePrdSources(projectRoot, cards, requiredSources = []) {
     }
     return [...grouped.entries()]
         .sort(([left], [right]) => left.localeCompare(right))
-        .map(([sourcePath, sourceCards]) => ({
-        path: sourcePath,
-        cardCount: sourceCards.length,
-        activeCardCount: sourceCards.filter((card) => card.status === "active").length,
-        cardIds: sourceCards.map((card) => card.id).sort(),
-        scopes: [...new Set(sourceCards.flatMap((card) => card.scope))].sort(),
-        tags: [...new Set(sourceCards.flatMap((card) => card.tags))].sort(),
-        coverage: [...new Set(sourceCards.flatMap((card) => card.coverage))].sort(),
-        prdAnchors: [...new Set(sourceCards.flatMap((card) => card.prdAnchors))].sort()
-    }));
+        .map(([sourcePath, sourceCards]) => {
+        const cardIds = sourceCards.map((card) => card.id).sort();
+        const scopes = [...new Set(sourceCards.flatMap((card) => card.scope))].sort();
+        const tags = [...new Set(sourceCards.flatMap((card) => card.tags))].sort();
+        const coverage = [...new Set(sourceCards.flatMap((card) => card.coverage))].sort();
+        const prdAnchors = [...new Set(sourceCards.flatMap((card) => card.prdAnchors))].sort();
+        return {
+            path: sourcePath,
+            cardCount: sourceCards.length,
+            activeCardCount: sourceCards.filter((card) => card.status === "active").length,
+            cardIds: selectedIndexDetails(cardIds),
+            scopes: selectedIndexDetails(scopes),
+            tags: selectedIndexDetails(tags),
+            coverage: selectedIndexDetails(coverage),
+            prdAnchors: selectedIndexDetails(prdAnchors),
+            omitted: {
+                cardIds: omittedIndexDetails(cardIds),
+                scopes: omittedIndexDetails(scopes),
+                tags: omittedIndexDetails(tags),
+                coverage: omittedIndexDetails(coverage),
+                prdAnchors: omittedIndexDetails(prdAnchors)
+            }
+        };
+    });
 }
 function summarizeModules(cards) {
     const atomicCards = cards.filter((card) => card.kind && card.status === "active");
@@ -1204,6 +1751,7 @@ function summarizeModules(cards) {
             card.related.includes(moduleCard.id) ||
             card.sourcePaths.some((sourcePath) => moduleSources.has(sourcePath)) ||
             card.scope.some((scope) => moduleCard.scope.includes(scope)));
+        const atomicCardIds = relatedAtomicCards.map((card) => card.id).sort();
         return {
             id: moduleCard.id,
             path: moduleCard.path,
@@ -1214,11 +1762,18 @@ function summarizeModules(cards) {
             tags: moduleCard.tags,
             related: moduleCard.related,
             atomicCardCount: relatedAtomicCards.length,
-            atomicCardIds: relatedAtomicCards.map((card) => card.id).sort()
+            atomicCardIds: selectedIndexDetails(atomicCardIds),
+            omittedAtomicCardIds: omittedIndexDetails(atomicCardIds)
         };
     })
         .sort((left, right) => left.path.localeCompare(right.path));
 }
+function selectedIndexDetails(values) {
+    return values.slice(0, MAX_KNOWLEDGE_INDEX_DETAIL_ITEMS);
+}
+function omittedIndexDetails(values) {
+    return Math.max(0, values.length - MAX_KNOWLEDGE_INDEX_DETAIL_ITEMS);
+}
 function discoverPrdSourceFiles(projectRoot) {
     const roots = ["docs/prd", "docs/requirements", "prd", "requirements"];
     const rootSources = roots.flatMap((root) => {
@@ -1237,6 +1792,9 @@ function discoverPrdSourceFiles(projectRoot) {
 }
 function isPrdSourcePath(sourcePath) {
     const normalized = sourcePath.replace(/\\/g, "/");
+    if (/^ingest:\/\/prd\//i.test(normalized)) {
+        return isIngestReference(normalized);
+    }
     if (/(^|\/)(prd|requirements?)(\/|[-_.])|(^|\/)docs\/(prd|requirements?)(\/|$)/i.test(normalized)) {
         return true;
     }