frontend-harness 0.7.9 → 0.8.0

package/dist/runtime/knowledge/core.js

@@ -0,0 +1,1569 @@
+import fs from "node:fs";
+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_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();
+    if (!title) {
+        throw new Error("knowledge promote requires --title");
+    }
+    if (!body) {
+        throw new Error("knowledge promote requires --body");
+    }
+    const type = parseKnowledgeType(input.type ?? "prd_semantics", "knowledge promote --type");
+    const status = parseKnowledgeStatus(input.status ?? "active", "knowledge promote --status");
+    const stability = parseKnowledgeStability(input.stability ?? "stable", "knowledge promote --stability");
+    const createdAt = new Date().toISOString();
+    const id = slugify(title) || `knowledge-${formatKnowledgeStamp(createdAt).toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "")}`;
+    const fileName = `${formatKnowledgeStamp(createdAt)}-${id}.md`;
+    const relativePath = relativeHarnessPath("knowledge", fileName);
+    const content = renderKnowledge({
+        id,
+        title,
+        body,
+        type,
+        status,
+        stability,
+        createdAt,
+        scope: splitList(input.scope),
+        tags: splitList(input.tags),
+        sourcePaths: parseKnowledgeSourcePaths(input.source, "knowledge promote --source")
+    });
+    writeText(path.join(projectRoot, relativePath), content);
+    return {
+        path: relativePath,
+        id,
+        title,
+        type,
+        status,
+        stability,
+        createdAt
+    };
+}
+export function createModuleKnowledge(projectRoot, input) {
+    const title = input.title?.trim();
+    const summary = input.summary?.trim();
+    const body = input.body?.trim();
+    if (!title) {
+        throw new Error("knowledge module requires --title");
+    }
+    if (!summary) {
+        throw new Error("knowledge module requires --summary");
+    }
+    if (!body) {
+        throw new Error("knowledge module requires --body");
+    }
+    const status = parseKnowledgeStatus(input.status ?? "active", "knowledge module --status");
+    const stability = parseKnowledgeStability(input.stability ?? "stable", "knowledge module --stability");
+    const createdAt = new Date().toISOString();
+    const id = input.id?.trim() || slugify(title);
+    if (!id || !/^[a-z0-9][a-z0-9-]{2,80}$/.test(id)) {
+        throw new Error("knowledge module --id must be kebab-case when provided");
+    }
+    const relativePath = relativeHarnessPath("knowledge", "modules", `${id}.md`);
+    const fullPath = path.join(projectRoot, relativePath);
+    if (fs.existsSync(fullPath)) {
+        throw new Error(`knowledge module already exists: ${relativePath}`);
+    }
+    const content = renderKnowledgeFromMetadata({
+        id,
+        title,
+        summary,
+        type: "module_summary",
+        status,
+        stability,
+        updatedAt: createdAt,
+        scope: splitList(input.scope),
+        tags: splitList(input.tags),
+        verification: splitList(input.verification),
+        coverage: splitList(input.coverage),
+        prdAnchors: splitList(input.anchor),
+        sourcePaths: parseKnowledgeSourcePaths(input.source, "knowledge module --source"),
+        related: splitList(input.related)
+    }, body);
+    writeText(fullPath, content);
+    return {
+        path: relativePath,
+        id,
+        title,
+        type: "module_summary",
+        status,
+        stability,
+        createdAt
+    };
+}
+export function addKnowledge(projectRoot, input) {
+    const kind = parseKnowledgeKind(input.kind ?? "", "knowledge add --kind");
+    const subject = input.subject?.trim();
+    if (!subject) {
+        throw new Error("knowledge add requires --subject");
+    }
+    const content = atomicContent(kind, input);
+    if (!content) {
+        throw new Error(`knowledge add requires --${contentFlagForKind(kind)} or --note`);
+    }
+    const status = parseKnowledgeStatus(input.status ?? "active", "knowledge add --status");
+    const stability = parseKnowledgeStability(input.stability ?? "stable", "knowledge add --stability");
+    const createdAt = new Date().toISOString();
+    const id = input.id?.trim() || slugify(`${subject}-${kind}-${content}`);
+    if (!id || !/^[a-z0-9][a-z0-9-]{2,80}$/.test(id)) {
+        throw new Error("knowledge add --id must be kebab-case when provided");
+    }
+    const relativePath = relativeHarnessPath("knowledge", kind, `${id}.md`);
+    const fullPath = path.join(projectRoot, relativePath);
+    if (fs.existsSync(fullPath)) {
+        throw new Error(`knowledge card already exists: ${relativePath}`);
+    }
+    const title = `${subject} ${titleCase(kind)}`;
+    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,
+        kind,
+        subject,
+        status,
+        stability,
+        createdAt,
+        scope: splitList(input.scope),
+        tags: splitList(input.tags),
+        sourcePaths,
+        verification: splitList(input.verification),
+        coverage: splitList(input.coverage),
+        prdAnchors: splitList(input.anchor),
+        contentFields
+    });
+    writeText(fullPath, rendered);
+    return {
+        path: relativePath,
+        id,
+        title,
+        type,
+        status,
+        stability,
+        createdAt
+    };
+}
+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 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,
+        limits: {
+            updateCandidates: updateCandidateSelection.limits
+        },
+        requiredEdits: [
+            ...(updateCandidateSelection.limits.total > 0
+                ? ["Prefer a matching update candidate before adding a new card for the same source."]
+                : []),
+            `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 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) {
+        throw new Error("knowledge update requires --id or --path");
+    }
+    const cards = discoverKnowledgeCards(projectRoot);
+    const card = resolveKnowledgeCardReference(cards, target);
+    if (!card) {
+        throw new Error(`knowledge card not found: ${target}`);
+    }
+    const fullPath = path.join(projectRoot, card.path);
+    const content = safeRead(fullPath);
+    if (content === null) {
+        throw new Error(`knowledge card cannot be read: ${card.path}`);
+    }
+    const parsed = parseKnowledgeFrontmatter(content);
+    if (!parsed.hasFrontmatter) {
+        throw new Error(`${card.path} must include YAML frontmatter.`);
+    }
+    const metadata = parsed.metadata;
+    if (!metadata.id || !metadata.title || !metadata.summary || !metadata.type || !metadata.status || !metadata.stability) {
+        throw new Error(`${card.path} has incomplete knowledge metadata.`);
+    }
+    const nextStatus = input.status ? parseKnowledgeStatus(input.status, "knowledge update --status") : metadata.status;
+    const nextStability = input.stability ? parseKnowledgeStability(input.stability, "knowledge update --stability") : metadata.stability;
+    const updatedAt = new Date().toISOString();
+    const nextMetadata = {
+        ...metadata,
+        id: metadata.id,
+        title: input.title?.trim() || metadata.title,
+        summary: input.summary?.trim() || metadata.summary,
+        type: metadata.type,
+        status: nextStatus,
+        stability: nextStability,
+        updatedAt,
+        scope: mergeList(metadata.scope, input.scope),
+        tags: mergeList(metadata.tags, input.tags),
+        verification: mergeList(metadata.verification, input.verification),
+        coverage: mergeList(metadata.coverage, input.coverage),
+        prdAnchors: mergeList(metadata.prdAnchors, input.anchor),
+        sourcePaths: mergeKnowledgeSourcePaths(metadata.sourcePaths, input.source, "knowledge update --source"),
+        related: mergeList(metadata.related, input.related)
+    };
+    for (const key of ["rule", "workflow", "permission", "term", "note"]) {
+        const value = input[key]?.trim();
+        if (value) {
+            nextMetadata[key] = value;
+        }
+    }
+    const body = input.body?.trim() || extractMarkdownBody(content);
+    const errors = validateKnowledgeMetadata(card.path, nextMetadata);
+    if (errors.length) {
+        throw new Error(errors.join(" "));
+    }
+    writeText(fullPath, renderKnowledgeFromMetadata(nextMetadata, body));
+    return {
+        path: card.path,
+        id: nextMetadata.id,
+        title: nextMetadata.title,
+        type: nextMetadata.type,
+        status: nextStatus,
+        stability: nextStability,
+        createdAt: updatedAt
+    };
+}
+export function discoverKnowledgeCards(projectRoot) {
+    const knowledgeRoot = harnessPath(projectRoot, "knowledge");
+    if (!isReadableDirectory(knowledgeRoot)) {
+        return [];
+    }
+    return listMarkdownFiles(knowledgeRoot)
+        .flatMap((fullPath) => {
+        const card = describeKnowledgeCard(projectRoot, fullPath);
+        return card ? [card] : [];
+    })
+        .sort((left, right) => left.path.localeCompare(right.path));
+}
+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,
+        activeCardCount: cards.filter((card) => card.status === "active").length,
+        deprecatedCardCount: cards.filter((card) => card.status === "deprecated").length,
+        prdSourceCount: prdSources.length,
+        uncoveredPrdSourceCount: prdSources.filter((source) => source.activeCardCount === 0).length,
+        byType: countByType(cards),
+        byKind: countByKind(cards),
+        moduleSummaries,
+        prdSources,
+        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;
+}
+export function checkKnowledgeCoverage(projectRoot, options = {}) {
+    const cards = discoverKnowledgeCards(projectRoot);
+    if (!isReadableDirectory(harnessPath(projectRoot, "knowledge"))) {
+        return {
+            status: "not_configured",
+            prdSourceCount: 0,
+            coveredPrdSourceCount: 0,
+            uncoveredPrdSources: [],
+            prdSourcesWithoutCoverageItems: [],
+            missingSourcePaths: [],
+            cardsWithoutSource: [],
+            cardsWithoutCoverage: [],
+            cardsWithBroadCoverage: [],
+            cardsWithTraceabilityDrift: [],
+            warnings: ["Create .frontend-harness/knowledge before checking project knowledge coverage."],
+            errors: []
+        };
+    }
+    const prdSources = summarizePrdSources(projectRoot, cards, options.requiredPrdSources ?? []);
+    const uncoveredPrdSources = prdSources
+        .filter((source) => source.activeCardCount === 0)
+        .map((source) => source.path);
+    const missingSourcePaths = [...new Set(cards.flatMap((card) => card.sourcePaths)
+            .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);
+    const cardsWithoutCoverage = cards
+        .filter((card) => card.status === "active" && isPrdTraceableCard(card) && card.coverage.length === 0)
+        .map((card) => card.path);
+    const cardsWithBroadCoverage = cards
+        .filter((card) => card.status === "active" && isPrdTraceableCard(card) && card.coverage.some(isBroadCoverageItem))
+        .map((card) => card.path);
+    const cardsWithTraceabilityDrift = cards
+        .filter((card) => card.status === "active" && isPrdTraceableCard(card) && hasCoverageBodyDrift(projectRoot, card))
+        .map((card) => card.path);
+    const prdSourcesWithoutCoverageItems = prdSources
+        .filter((source) => source.activeCardCount > 0 && source.coverage.length === 0)
+        .map((source) => source.path);
+    const warnings = [
+        ...cardsWithoutSource.map((cardPath) => `${cardPath} has no source_paths for PRD traceability.`),
+        ...cardsWithoutCoverage.map((cardPath) => `${cardPath} has no coverage items for PRD block traceability.`),
+        ...cardsWithBroadCoverage.map((cardPath) => `${cardPath} uses broad PRD coverage; split PRD semantics into atomic cards with precise section, table, rule, or acceptance-block coverage.`),
+        ...cardsWithTraceabilityDrift.map((cardPath) => `${cardPath} frontmatter coverage disagrees with body traceability.`),
+        ...prdSourcesWithoutCoverageItems.map((sourcePath) => `PRD source has cards but no coverage items: ${sourcePath}`),
+        ...missingSourcePaths.map((sourcePath) => `source path does not exist: ${sourcePath}`)
+    ];
+    const errors = [
+        ...uncoveredPrdSources.map((sourcePath) => `PRD source has no active knowledge cards: ${sourcePath}`),
+        ...prdSourcesWithoutCoverageItems.map((sourcePath) => `PRD source has no coverage items: ${sourcePath}`),
+        ...cardsWithBroadCoverage.map((cardPath) => `${cardPath} uses broad PRD coverage instead of atomic traceability.`),
+        ...cardsWithTraceabilityDrift.map((cardPath) => `${cardPath} has frontmatter coverage but body traceability says coverage is not specified.`),
+        ...missingSourcePaths.map((sourcePath) => `source path does not exist: ${sourcePath}`)
+    ];
+    return {
+        status: errors.length || cardsWithoutSource.length || cardsWithoutCoverage.length ? "failed" : "passed",
+        prdSourceCount: prdSources.length,
+        coveredPrdSourceCount: prdSources.filter((source) => source.activeCardCount > 0).length,
+        uncoveredPrdSources,
+        prdSourcesWithoutCoverageItems,
+        missingSourcePaths,
+        cardsWithoutSource,
+        cardsWithoutCoverage,
+        cardsWithBroadCoverage,
+        cardsWithTraceabilityDrift,
+        warnings,
+        errors
+    };
+}
+export function listKnowledge(projectRoot, options = {}) {
+    const cards = discoverKnowledgeCards(projectRoot)
+        .filter((card) => options.includeDeprecated || card.status === "active")
+        .map(stripSearchable);
+    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 : MAX_KNOWLEDGE_SEARCH_RESULTS;
+    const matches = discoverKnowledgeCards(projectRoot)
+        .filter((card) => options.includeDeprecated || card.status === "active")
+        .map((card) => ({
+        card,
+        score: scoreCardSearch(card, normalizedQuery)
+    }))
+        .filter((item) => item.score > 0)
+        .sort((left, right) => {
+        if (right.score !== left.score) {
+            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,
+        limits: {
+            selected: cards.length,
+            total: matches.length,
+            omitted: Math.max(0, matches.length - cards.length)
+        }
+    };
+}
+export function showKnowledge(projectRoot, idOrPath) {
+    const target = idOrPath?.trim();
+    if (!target) {
+        throw new Error("knowledge show requires --id or --path");
+    }
+    const cards = discoverKnowledgeCards(projectRoot);
+    const card = resolveKnowledgeCardReference(cards, target);
+    if (!card) {
+        throw new Error(`knowledge card not found: ${target}`);
+    }
+    const fullPath = path.join(projectRoot, card.path);
+    const content = safeRead(fullPath);
+    if (content === null) {
+        throw new Error(`knowledge card cannot be read: ${card.path}`);
+    }
+    return {
+        card: stripSearchable(card),
+        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);
+    if (!fs.existsSync(knowledgeRoot)) {
+        return {
+            status: "not_configured",
+            knowledgeRoot: relativeRoot,
+            cardCount: 0,
+            activeCardCount: 0,
+            deprecatedCardCount: 0,
+            errors: [],
+            warnings: ["Create .frontend-harness/knowledge before checking project knowledge."]
+        };
+    }
+    const errors = [];
+    const warnings = [];
+    if (!isReadableDirectory(knowledgeRoot)) {
+        errors.push(".frontend-harness/knowledge must be a readable directory.");
+    }
+    const files = isReadableDirectory(knowledgeRoot) ? listMarkdownFiles(knowledgeRoot, errors) : [];
+    const ids = new Set();
+    const duplicateIds = new Set();
+    let activeCardCount = 0;
+    let deprecatedCardCount = 0;
+    for (const fullPath of files) {
+        const relativePath = path.relative(projectRoot, fullPath).split(path.sep).join(path.posix.sep);
+        const content = safeRead(fullPath);
+        if (content === null) {
+            errors.push(`${relativePath} cannot be read.`);
+            continue;
+        }
+        const parsed = parseKnowledgeFrontmatter(content);
+        if (!parsed.hasFrontmatter) {
+            errors.push(`${relativePath} must include YAML frontmatter.`);
+            continue;
+        }
+        const cardErrors = validateKnowledgeMetadata(relativePath, parsed.metadata);
+        errors.push(...parsed.syntaxErrors.map((error) => `${relativePath} ${error}.`));
+        errors.push(...cardErrors);
+        const id = parsed.metadata.id;
+        if (id) {
+            if (ids.has(id)) {
+                duplicateIds.add(id);
+            }
+            ids.add(id);
+        }
+        if (parsed.metadata.status === "active") {
+            activeCardCount += 1;
+        }
+        if (parsed.metadata.status === "deprecated") {
+            deprecatedCardCount += 1;
+            if (!parsed.metadata.related.length) {
+                warnings.push(`${relativePath} is deprecated without a related replacement or explanation.`);
+            }
+        }
+        if ((parsed.metadata.summary?.length ?? 0) > 180) {
+            warnings.push(`${relativePath} summary should stay concise for context display.`);
+        }
+        if (parsed.metadata.kind) {
+            const contentValue = primaryAtomicValue(parsed.metadata);
+            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.`);
+            }
+            if (parsed.metadata.sourcePaths.some(isPrdSourcePath) && parsed.metadata.coverage.some(isBroadCoverageItem)) {
+                warnings.push(`${relativePath} uses broad PRD coverage; split PRD semantics into smaller atomic cards with precise section, table, rule, or acceptance-block coverage.`);
+            }
+        }
+        if (parsed.metadata.coverage.length > 0 && /\bCoverage:\s*Not specified\./i.test(extractMarkdownBody(content))) {
+            warnings.push(`${relativePath} frontmatter coverage disagrees with body traceability.`);
+        }
+        for (const sourcePath of parsed.metadata.sourcePaths) {
+            if (sourcePath && !isExternalReference(sourcePath) && !isResolvedKnowledgeSource(projectRoot, sourcePath)) {
+                warnings.push(`${relativePath} source path is missing or unsafe: ${sourcePath}.`);
+            }
+        }
+    }
+    for (const duplicateId of duplicateIds) {
+        errors.push(`Duplicate knowledge id: ${duplicateId}.`);
+    }
+    return {
+        status: errors.length ? "failed" : "passed",
+        knowledgeRoot: relativeRoot,
+        cardCount: files.length,
+        activeCardCount,
+        deprecatedCardCount,
+        errors,
+        warnings
+    };
+}
+function describeKnowledgeCard(projectRoot, fullPath) {
+    const relativePath = path.relative(projectRoot, fullPath).split(path.sep).join(path.posix.sep);
+    const content = safeRead(fullPath);
+    if (content === null) {
+        return null;
+    }
+    const parsed = parseKnowledgeFrontmatter(content);
+    if (!parsed.hasFrontmatter || parsed.syntaxErrors.length || validateKnowledgeMetadata(relativePath, parsed.metadata).length) {
+        return null;
+    }
+    const metadata = parsed.metadata;
+    const body = extractMarkdownBody(content);
+    const title = metadata.title;
+    const summary = metadata.summary;
+    const type = metadata.type;
+    const kind = metadata.kind;
+    const status = metadata.status;
+    const stability = metadata.stability;
+    const scope = metadata.scope;
+    const tags = metadata.tags;
+    const sourcePaths = metadata.sourcePaths;
+    const related = metadata.related;
+    const updatedAt = metadata.updatedAt;
+    return {
+        id: metadata.id,
+        path: relativePath,
+        title,
+        summary,
+        type,
+        ...(kind ? { kind } : {}),
+        ...(metadata.subject ? { subject: metadata.subject } : {}),
+        ...(metadata.rule ? { rule: metadata.rule } : {}),
+        ...(metadata.workflow ? { workflow: metadata.workflow } : {}),
+        ...(metadata.permission ? { permission: metadata.permission } : {}),
+        ...(metadata.term ? { term: metadata.term } : {}),
+        ...(metadata.note ? { note: metadata.note } : {}),
+        verification: metadata.verification,
+        coverage: metadata.coverage,
+        prdAnchors: metadata.prdAnchors,
+        status,
+        stability,
+        scope,
+        tags,
+        sourcePaths,
+        related,
+        updatedAt,
+        searchable: normalize([
+            relativePath,
+            metadata.id,
+            title,
+            summary,
+            type,
+            kind ?? "",
+            stability,
+            metadata.subject ?? "",
+            metadata.rule ?? "",
+            metadata.workflow ?? "",
+            metadata.permission ?? "",
+            metadata.term ?? "",
+            metadata.note ?? "",
+            ...metadata.verification,
+            ...metadata.coverage,
+            ...metadata.prdAnchors,
+            ...scope,
+            ...tags,
+            ...sourcePaths,
+            ...related,
+            body
+        ].join(" "))
+    };
+}
+function stripSearchable(card) {
+    const { searchable, ...publicCard } = card;
+    void searchable;
+    return publicCard;
+}
+function resolveKnowledgeCardReference(cards, target) {
+    const exactPath = cards.find((item) => item.path === target);
+    if (exactPath) {
+        return exactPath;
+    }
+    const idMatches = cards.filter((item) => item.id === target);
+    if (idMatches.length === 1) {
+        return idMatches[0] ?? null;
+    }
+    if (idMatches.length > 1) {
+        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(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: [],
+        tags: [],
+        verification: [],
+        coverage: [],
+        prdAnchors: [],
+        sourcePaths: [],
+        related: []
+    };
+    const syntaxErrors = [];
+    if (!content.startsWith("---\n") && !content.startsWith("---\r\n")) {
+        return { hasFrontmatter: false, syntaxErrors, metadata };
+    }
+    const endIndex = content.search(/\r?\n---(?:\r?\n|$)/);
+    if (endIndex < 0) {
+        syntaxErrors.push("frontmatter must be closed with ---");
+        return { hasFrontmatter: true, syntaxErrors, metadata };
+    }
+    const listKeys = new Set(["scope", "tags", "verification", "coverage", "prd_anchors", "source_paths", "related"]);
+    let currentList = null;
+    const startIndex = content.startsWith("---\r\n") ? 5 : 4;
+    for (const [lineIndex, line] of content.slice(startIndex, endIndex).split(/\r?\n/).entries()) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith("#")) {
+            continue;
+        }
+        const leadingWhitespace = line.match(/^\s*/)?.[0] ?? "";
+        if (leadingWhitespace.length > 0 && !trimmed.startsWith("-") && /^[A-Za-z][A-Za-z0-9_-]*:\s*/.test(trimmed)) {
+            syntaxErrors.push(`frontmatter line ${lineIndex + 2} has an indented mapping key: ${trimmed}`);
+        }
+        if (trimmed === "[]" && currentList) {
+            currentList = null;
+            continue;
+        }
+        const listItem = trimmed.match(/^-\s+(.+)$/);
+        if (listItem) {
+            if (!currentList) {
+                syntaxErrors.push(`frontmatter line ${lineIndex + 2} has a list item without a list key`);
+                continue;
+            }
+            const value = listItem[1];
+            if (value) {
+                metadata[currentList].push(unquoteScalar(value));
+            }
+            continue;
+        }
+        const pair = trimmed.match(/^([A-Za-z][A-Za-z0-9_-]*):\s*(.*)$/);
+        if (!pair) {
+            currentList = null;
+            syntaxErrors.push(`frontmatter line ${lineIndex + 2} must be a key/value pair or list item`);
+            continue;
+        }
+        const key = pair[1] ?? "";
+        const value = (pair[2] ?? "").trim();
+        if (isKnowledgeScalarKey(key)) {
+            metadata[key] = unquoteScalar(value);
+            currentList = null;
+            continue;
+        }
+        if (key === "updated_at") {
+            metadata.updatedAt = unquoteScalar(value);
+            currentList = null;
+            continue;
+        }
+        if (listKeys.has(key)) {
+            const mappedKey = key === "source_paths"
+                ? "sourcePaths"
+                : key === "prd_anchors"
+                    ? "prdAnchors"
+                    : key;
+            metadata[mappedKey] = parseListValue(value);
+            currentList = value ? null : mappedKey;
+            continue;
+        }
+        currentList = null;
+        syntaxErrors.push(`frontmatter line ${lineIndex + 2} uses unsupported field: ${key}`);
+    }
+    return { hasFrontmatter: true, syntaxErrors, metadata };
+}
+function isKnowledgeScalarKey(key) {
+    return key === "id"
+        || key === "title"
+        || key === "summary"
+        || key === "type"
+        || key === "kind"
+        || key === "subject"
+        || key === "rule"
+        || key === "workflow"
+        || key === "permission"
+        || key === "term"
+        || key === "note"
+        || key === "status"
+        || key === "stability";
+}
+function validateKnowledgeMetadata(relativePath, metadata) {
+    const errors = [];
+    if (!metadata.id || !/^[a-z0-9][a-z0-9-]{2,80}$/.test(metadata.id)) {
+        errors.push(`${relativePath} must include a kebab-case id.`);
+    }
+    if (!metadata.title) {
+        errors.push(`${relativePath} must include a non-empty title.`);
+    }
+    if (!metadata.summary) {
+        errors.push(`${relativePath} must include a non-empty summary.`);
+    }
+    if (!metadata.type || !knowledgeTypes.has(metadata.type)) {
+        errors.push(`${relativePath} type must be one of: ${[...knowledgeTypes].join(", ")}.`);
+    }
+    if (metadata.kind) {
+        if (!knowledgeKinds.has(metadata.kind)) {
+            errors.push(`${relativePath} kind must be one of: ${[...knowledgeKinds].join(", ")}.`);
+        }
+        if (!metadata.subject) {
+            errors.push(`${relativePath} atomic knowledge must include subject.`);
+        }
+        if (!metadata.rule && !metadata.workflow && !metadata.permission && !metadata.term && !metadata.note) {
+            errors.push(`${relativePath} atomic knowledge must include rule, workflow, permission, term, or note.`);
+        }
+    }
+    if (!metadata.status || !knowledgeStatuses.has(metadata.status)) {
+        errors.push(`${relativePath} status must be one of: ${[...knowledgeStatuses].join(", ")}.`);
+    }
+    if (!metadata.stability || !knowledgeStabilities.has(metadata.stability)) {
+        errors.push(`${relativePath} stability must be one of: ${[...knowledgeStabilities].join(", ")}.`);
+    }
+    if (!metadata.updatedAt || !/^\d{4}-\d{2}-\d{2}([T ][0-9:.+-Z]+)?$/.test(metadata.updatedAt)) {
+        errors.push(`${relativePath} must include updated_at as YYYY-MM-DD or ISO timestamp.`);
+    }
+    for (const sourcePath of metadata.sourcePaths) {
+        const sourceError = validateKnowledgeSourcePath(sourcePath);
+        if (sourceError) {
+            errors.push(`${relativePath} source_paths must contain safe project-relative paths or external references: ${sourcePath}.`);
+        }
+    }
+    return errors;
+}
+function renderKnowledgeFromMetadata(metadata, body) {
+    const renderedBody = renderBodyWithTraceability(body, metadata.coverage ?? [], metadata.prdAnchors ?? [], metadata.verification ?? []);
+    return `---
+id: ${yamlScalar(metadata.id)}
+type: ${yamlScalar(metadata.type)}
+${renderOptionalScalar("kind", metadata.kind)}title: ${yamlScalar(metadata.title)}
+summary: ${yamlScalar(metadata.summary)}
+${renderOptionalScalar("subject", metadata.subject)}${renderOptionalScalar("rule", metadata.rule)}${renderOptionalScalar("workflow", metadata.workflow)}${renderOptionalScalar("permission", metadata.permission)}${renderOptionalScalar("term", metadata.term)}${renderOptionalScalar("note", metadata.note)}scope:
+${renderList(metadata.scope)}
+tags:
+${renderList(metadata.tags)}
+verification:
+${renderList(metadata.verification)}
+coverage:
+${renderList(metadata.coverage ?? [])}
+prd_anchors:
+${renderList(metadata.prdAnchors ?? [])}
+status: ${yamlScalar(metadata.status)}
+stability: ${yamlScalar(metadata.stability)}
+updated_at: ${yamlScalar(metadata.updatedAt)}
+source_paths:
+${renderList(metadata.sourcePaths)}
+related:
+${renderList(metadata.related)}
+---
+
+${renderedBody}
+`;
+}
+function renderBodyWithTraceability(body, coverage, prdAnchors, verification) {
+    const sections = [body.trim()];
+    if ((coverage.length || prdAnchors.length) && !/^## Traceability\b/m.test(body)) {
+        sections.push([
+            "## Traceability",
+            "",
+            ...(coverage.length ? coverage.map((item) => `- Coverage: ${item}`) : ["- Coverage: Not specified."]),
+            ...(prdAnchors.length ? prdAnchors.map((item) => `- Anchor: ${item}`) : [])
+        ].join("\n"));
+    }
+    if (verification.length && !/^## Verification\b/m.test(body)) {
+        sections.push([
+            "## Verification",
+            "",
+            ...verification.map((item) => `- ${item}`)
+        ].join("\n"));
+    }
+    return sections.join("\n\n");
+}
+function renderAtomicKnowledge(input) {
+    return `---
+id: ${yamlScalar(input.id)}
+type: ${yamlScalar(input.type)}
+kind: ${yamlScalar(input.kind)}
+title: ${yamlScalar(input.title)}
+summary: ${yamlScalar(input.summary)}
+subject: ${yamlScalar(input.subject)}
+${renderOptionalScalar("rule", input.contentFields.rule)}${renderOptionalScalar("workflow", input.contentFields.workflow)}${renderOptionalScalar("permission", input.contentFields.permission)}${renderOptionalScalar("term", input.contentFields.term)}${renderOptionalScalar("note", input.contentFields.note)}scope:
+${renderList(input.scope)}
+tags:
+${renderList(input.tags)}
+verification:
+${renderList(input.verification)}
+coverage:
+${renderList(input.coverage)}
+prd_anchors:
+${renderList(input.prdAnchors)}
+status: ${yamlScalar(input.status)}
+stability: ${yamlScalar(input.stability)}
+updated_at: ${yamlScalar(input.createdAt)}
+source_paths:
+${renderList(input.sourcePaths)}
+related: []
+---
+
+# ${input.title}
+
+${renderAtomicBody(input.kind, input.subject, input.summary, input.contentFields, input.coverage, input.prdAnchors, input.verification)}
+`;
+}
+function renderOptionalScalar(key, value) {
+    return value ? `${key}: ${yamlScalar(value)}\n` : "";
+}
+function renderAtomicBody(kind, subject, summary, contentFields, coverage, prdAnchors, verification) {
+    const contentEntries = Object.entries(contentFields).filter(([, value]) => Boolean(value?.trim()));
+    const primaryLabel = titleCase(contentKeyForKind(kind));
+    const primaryValue = contentFields[contentKeyForKind(kind)] ?? contentEntries[0]?.[1];
+    const sections = [
+        "# " + titleCase(kind) + ": " + subject,
+        "",
+        "## Context",
+        "",
+        summary,
+        "",
+        "## Durable Knowledge",
+        "",
+        ...(primaryValue ? [`**${primaryLabel}**`, "", primaryValue] : [subject])
+    ];
+    const note = contentFields.note;
+    if (note && contentKeyForKind(kind) !== "note") {
+        sections.push("", "## Notes", "", note);
+    }
+    sections.push("", "## Traceability", "", ...(coverage.length ? coverage.map((item) => `- Coverage: ${item}`) : ["- Coverage: Not specified."]), ...(prdAnchors.length ? prdAnchors.map((item) => `- Anchor: ${item}`) : []));
+    sections.push("", "## Verification", "", ...(verification.length ? verification.map((item) => `- ${item}`) : ["- Not specified."]));
+    return [
+        ...sections
+    ].join("\n");
+}
+function renderKnowledge(input) {
+    const summary = firstBodyLine(input.body) ?? input.title;
+    return `---
+id: ${yamlScalar(input.id)}
+type: ${yamlScalar(input.type)}
+title: ${yamlScalar(input.title)}
+summary: ${yamlScalar(summary)}
+scope:
+${renderList(input.scope)}
+tags:
+${renderList(input.tags)}
+status: ${yamlScalar(input.status)}
+stability: ${yamlScalar(input.stability)}
+updated_at: ${yamlScalar(input.createdAt)}
+source_paths:
+${renderList(input.sourcePaths)}
+related: []
+---
+
+# ${input.title}
+
+${input.body}
+`;
+}
+function renderList(items) {
+    return items.length ? items.map((item) => `  - ${yamlScalar(item)}`).join("\n") : "  []";
+}
+function firstBodyLine(body) {
+    return body
+        .split("\n")
+        .map((line) => line.trim())
+        .find((line) => line && !line.startsWith("#") && !line.startsWith("- ")) ?? null;
+}
+function parseKnowledgeType(value, label) {
+    if (knowledgeTypes.has(value)) {
+        return value;
+    }
+    throw new Error(`${label} must be one of: ${[...knowledgeTypes].join(", ")}`);
+}
+function parseKnowledgeStatus(value, label) {
+    if (knowledgeStatuses.has(value)) {
+        return value;
+    }
+    throw new Error(`${label} must be one of: ${[...knowledgeStatuses].join(", ")}`);
+}
+function parseKnowledgeStability(value, label) {
+    if (knowledgeStabilities.has(value)) {
+        return value;
+    }
+    throw new Error(`${label} must be one of: ${[...knowledgeStabilities].join(", ")}`);
+}
+function parseKnowledgeKind(value, label) {
+    if (knowledgeKinds.has(value)) {
+        return value;
+    }
+    throw new Error(`${label} must be one of: ${[...knowledgeKinds].join(", ")}`);
+}
+function atomicContent(kind, input) {
+    return atomicContentFields(kind, input)[contentKeyForKind(kind)] ?? input.note?.trim() ?? null;
+}
+function atomicContentFields(kind, input) {
+    const fields = {};
+    const preferredKey = contentKeyForKind(kind);
+    const preferredValue = input[preferredKey]?.trim();
+    if (preferredValue) {
+        fields[preferredKey] = preferredValue;
+    }
+    const note = input.note?.trim();
+    if (note && preferredKey !== "note") {
+        fields.note = note;
+    }
+    return fields;
+}
+function summarizeAtomicContent(kind, subject, contentFields) {
+    const primary = contentFields[contentKeyForKind(kind)] ?? contentFields.note ?? subject;
+    const concise = primary.length > 140 ? `${primary.slice(0, 137)}...` : primary;
+    return `${subject}: ${concise}`;
+}
+function contentKeyForKind(kind) {
+    if (kind === "workflow") {
+        return "workflow";
+    }
+    if (kind === "permission") {
+        return "permission";
+    }
+    if (kind === "term") {
+        return "term";
+    }
+    if (kind === "pitfall" || kind === "decision" || kind === "convention") {
+        return "note";
+    }
+    return "rule";
+}
+function primaryAtomicValue(metadata) {
+    const kind = metadata.kind;
+    if (!kind || !knowledgeKinds.has(kind)) {
+        return undefined;
+    }
+    return metadata[contentKeyForKind(kind)] ?? metadata.note;
+}
+function contentFlagForKind(kind) {
+    return contentKeyForKind(kind);
+}
+function splitList(value) {
+    return value
+        ? value.split(",").map((item) => item.trim()).filter(Boolean)
+        : [];
+}
+function parseKnowledgeSourcePaths(value, label) {
+    const sourcePaths = splitList(value);
+    const invalid = sourcePaths.find(validateKnowledgeSourcePath);
+    if (invalid) {
+        throw new Error(`${label} must contain safe project-relative paths or external references: ${invalid}`);
+    }
+    return sourcePaths;
+}
+function mergeKnowledgeSourcePaths(existing, next, label) {
+    if (next === undefined) {
+        return existing;
+    }
+    const merged = [...new Set([...existing, ...splitList(next)])];
+    const invalid = merged.find(validateKnowledgeSourcePath);
+    if (invalid) {
+        throw new Error(`${label} must contain safe project-relative paths or external references: ${invalid}`);
+    }
+    return merged;
+}
+function validateKnowledgeSourcePath(value) {
+    if (!value.trim()) {
+        return "empty";
+    }
+    if (value.toLowerCase().startsWith("ingest://")) {
+        return isIngestReference(value) ? null : "unsafe";
+    }
+    if (isExternalReference(value)) {
+        return null;
+    }
+    try {
+        normalizeProjectRelativePath(value, "knowledge source path");
+        return null;
+    }
+    catch {
+        return "unsafe";
+    }
+}
+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;
+    }
+    return [...new Set([...existing, ...splitList(next)])];
+}
+function parseListValue(value) {
+    if (!value || value === "[]") {
+        return [];
+    }
+    const inline = value.match(/^\[(.*)\]$/);
+    if (!inline) {
+        return [unquoteScalar(value)];
+    }
+    return splitInlineListItems(inline[1] ?? "")
+        .map((item) => unquoteScalar(item.trim()))
+        .filter(Boolean);
+}
+function splitInlineListItems(value) {
+    const items = [];
+    let current = "";
+    let quote = null;
+    let escaped = false;
+    for (const char of value) {
+        if (escaped) {
+            current += char;
+            escaped = false;
+            continue;
+        }
+        if (char === "\\" && quote === "\"") {
+            current += char;
+            escaped = true;
+            continue;
+        }
+        if (quote) {
+            current += char;
+            if (char === quote) {
+                quote = null;
+            }
+            continue;
+        }
+        if (char === "\"" || char === "'") {
+            current += char;
+            quote = char;
+            continue;
+        }
+        if (char === ",") {
+            items.push(current);
+            current = "";
+            continue;
+        }
+        current += char;
+    }
+    items.push(current);
+    return items;
+}
+function unquoteScalar(value) {
+    const trimmed = value.trim();
+    if (trimmed.startsWith("\"") && trimmed.endsWith("\"")) {
+        try {
+            const parsed = JSON.parse(trimmed);
+            return typeof parsed === "string" ? parsed : trimmed.slice(1, -1);
+        }
+        catch {
+            return trimmed.slice(1, -1);
+        }
+    }
+    if (trimmed.startsWith("'") && trimmed.endsWith("'")) {
+        return trimmed.slice(1, -1).replace(/''/g, "'");
+    }
+    return trimmed;
+}
+function slugify(value) {
+    return value
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 80);
+}
+function titleCase(value) {
+    return value.slice(0, 1).toUpperCase() + value.slice(1);
+}
+function formatKnowledgeStamp(createdAt) {
+    return createdAt
+        .replace(/[-:]/g, "")
+        .replace(/\.(\d{3})Z$/, "$1Z");
+}
+function yamlScalar(value) {
+    return JSON.stringify(value);
+}
+function safeRead(filePath) {
+    if (!isRegularFileWithoutSymlink(filePath)) {
+        return null;
+    }
+    try {
+        const stat = fs.statSync(filePath);
+        if (stat.size > MAX_KNOWLEDGE_MARKDOWN_BYTES) {
+            return null;
+        }
+        return fs.readFileSync(filePath, "utf8");
+    }
+    catch {
+        return null;
+    }
+}
+function isReadableDirectory(directory) {
+    return isDirectoryWithoutSymlink(directory);
+}
+function listMarkdownFiles(directory, errors, depth = 0, state = { count: 0, stopped: false }) {
+    if (state.stopped) {
+        return [];
+    }
+    if (depth > MAX_KNOWLEDGE_DIRECTORY_DEPTH) {
+        errors?.push(`Knowledge markdown scan exceeded maximum directory depth at ${displayScanPath(directory)}.`);
+        return [];
+    }
+    try {
+        return fs.readdirSync(directory, { withFileTypes: true }).flatMap((entry) => {
+            const fullPath = path.join(directory, entry.name);
+            if (entry.isSymbolicLink()) {
+                return [];
+            }
+            if (entry.isDirectory()) {
+                if (entry.name.startsWith(".")) {
+                    return [];
+                }
+                return listMarkdownFiles(fullPath, errors, depth + 1, state);
+            }
+            if (!entry.name.endsWith(".md") || !isRegularFileWithoutSymlink(fullPath)) {
+                return [];
+            }
+            state.count += 1;
+            if (state.count > MAX_KNOWLEDGE_MARKDOWN_FILES) {
+                if (!state.stopped) {
+                    errors?.push(`Knowledge markdown scan exceeded ${MAX_KNOWLEDGE_MARKDOWN_FILES} files.`);
+                }
+                state.stopped = true;
+                return [];
+            }
+            const stat = fs.statSync(fullPath, { throwIfNoEntry: false });
+            if (stat && stat.size > MAX_KNOWLEDGE_MARKDOWN_BYTES) {
+                errors?.push(`${displayScanPath(fullPath)} exceeds ${MAX_KNOWLEDGE_MARKDOWN_BYTES} bytes.`);
+                return [];
+            }
+            return [fullPath];
+        });
+    }
+    catch (error) {
+        if (errors) {
+            const message = error instanceof Error ? error.message : String(error);
+            errors.push(`Cannot read .frontend-harness/knowledge: ${message}`);
+        }
+        return [];
+    }
+}
+function displayScanPath(filePath) {
+    const relativePath = path.relative(process.cwd(), filePath);
+    if (!relativePath.startsWith("..") && !path.isAbsolute(relativePath)) {
+        return relativePath.split(path.sep).join(path.posix.sep);
+    }
+    return filePath;
+}
+function normalize(value) {
+    return value.toLowerCase().replace(/[^\p{L}\p{N}-]+/gu, " ").trim();
+}
+function scoreCardSearch(card, normalizedQuery) {
+    const queryTokens = tokens(normalizedQuery);
+    if (!queryTokens.length) {
+        return card.searchable.includes(normalizedQuery) ? 1 : 0;
+    }
+    const searchableTokens = new Set(tokens(card.searchable));
+    let score = 0;
+    for (const token of queryTokens) {
+        if (searchableTokens.has(token)) {
+            score += 2;
+        }
+        else if (card.searchable.includes(token)) {
+            score += 1;
+        }
+    }
+    if (card.id === normalizedQuery || normalize(card.title) === normalizedQuery) {
+        score += 4;
+    }
+    return score;
+}
+function tokens(value) {
+    return value.split(/\s+/).filter((token) => token.length >= 2);
+}
+function extractMarkdownBody(content) {
+    const endIndex = content.search(/\r?\n---(?:\r?\n|$)/);
+    if (!content.startsWith("---") || endIndex < 0) {
+        return content.trim();
+    }
+    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) {
+        return false;
+    }
+    if (/\bsections?\s+\d+(?:\.\d+)?\s*[-–—~]\s*\d+(?:\.\d+)?\b/.test(normalized)) {
+        return true;
+    }
+    if (/(?:^|[#\s/])\d+(?:\.\d+)?\s*[-–—~至到]\s*\d+(?:\.\d+)?(?:\D|$)/.test(normalized)) {
+        return true;
+    }
+    return /\b(chapter|section)\b.*\b(full|entire|whole|all)\b/.test(normalized);
+}
+function hasCoverageBodyDrift(projectRoot, card) {
+    if (card.coverage.length === 0) {
+        return false;
+    }
+    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)) {
+        grouped.set(sourcePath, []);
+    }
+    for (const sourcePath of requiredSources.filter(isPrdSourcePath)) {
+        grouped.set(sourcePath, grouped.get(sourcePath) ?? []);
+    }
+    for (const card of cards) {
+        for (const sourcePath of card.sourcePaths.filter(isPrdSourcePath)) {
+            grouped.set(sourcePath, [...(grouped.get(sourcePath) ?? []), card]);
+        }
+    }
+    return [...grouped.entries()]
+        .sort(([left], [right]) => left.localeCompare(right))
+        .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");
+    return cards
+        .filter((card) => card.type === "module_summary" && card.status === "active")
+        .map((moduleCard) => {
+        const moduleSources = new Set(moduleCard.sourcePaths);
+        const relatedIds = new Set(moduleCard.related);
+        const relatedAtomicCards = atomicCards.filter((card) => relatedIds.has(card.id) ||
+            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,
+            title: moduleCard.title,
+            summary: moduleCard.summary,
+            sourcePaths: moduleCard.sourcePaths,
+            scopes: moduleCard.scope,
+            tags: moduleCard.tags,
+            related: moduleCard.related,
+            atomicCardCount: relatedAtomicCards.length,
+            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) => {
+        const fullPath = path.join(projectRoot, root);
+        return isReadableDirectory(fullPath)
+            ? listMarkdownFiles(fullPath).map((filePath) => path.relative(projectRoot, filePath).replace(/\\/g, "/"))
+            : [];
+    });
+    const docsRoot = path.join(projectRoot, "docs");
+    const docsNamedSources = isReadableDirectory(docsRoot)
+        ? listMarkdownFiles(docsRoot)
+            .map((filePath) => path.relative(projectRoot, filePath).replace(/\\/g, "/"))
+            .filter(isPrdSourcePath)
+        : [];
+    return [...new Set([...rootSources, ...docsNamedSources])].sort();
+}
+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;
+    }
+    return /(^|\/)docs\/[^/]*(?:prd|requirement|需求)[^/]*\.md$/i.test(normalized);
+}
+function isPrdTraceableCard(card) {
+    return card.type === "prd_semantics" || card.type === "module_summary" || card.type === "pitfall" || card.type === "glossary";
+}
+function countByType(cards) {
+    const counts = Object.fromEntries([...knowledgeTypes].map((type) => [type, 0]));
+    for (const card of cards) {
+        counts[card.type] += 1;
+    }
+    return counts;
+}
+function countByKind(cards) {
+    const counts = {};
+    for (const card of cards) {
+        if (card.kind) {
+            counts[card.kind] = (counts[card.kind] ?? 0) + 1;
+        }
+    }
+    return counts;
+}
+//# sourceMappingURL=core.js.map