frontend-harness 0.2.0 → 0.2.1

package/dist/runtime/knowledge.js

@@ -1,9 +1,10 @@
 import fs from "node:fs";
 import path from "node:path";
 import { harnessPath, relativeHarnessPath } from "../storage/paths.js";
-import { writeText } from "../storage/json.js";
+import { writeJson, writeText } from "../storage/json.js";
 const knowledgeTypes = new Set([
     "prd_semantics",
+    "module_summary",
     "project_convention",
     "decision_record",
     "pitfall",
@@ -11,6 +12,16 @@ const knowledgeTypes = new Set([
 ]);
 const knowledgeStatuses = new Set(["active", "deprecated"]);
 const knowledgeStabilities = new Set(["stable", "evolving"]);
+const knowledgeKinds = new Set(["rule", "workflow", "permission", "term", "pitfall", "decision", "convention"]);
+const kindTypeMap = {
+    rule: "prd_semantics",
+    workflow: "prd_semantics",
+    permission: "prd_semantics",
+    term: "glossary",
+    pitfall: "pitfall",
+    decision: "decision_record",
+    convention: "project_convention"
+};
 export function promoteKnowledge(projectRoot, input) {
     const title = input.title?.trim();
     const body = input.body?.trim();
@@ -36,6 +47,7 @@ export function promoteKnowledge(projectRoot, input) {
         stability,
         createdAt,
         scope: splitList(input.scope),
+        tags: splitList(input.tags),
         sourcePaths: splitList(input.source)
     });
     writeText(path.join(projectRoot, relativePath), content);
@@ -49,6 +61,178 @@ export function promoteKnowledge(projectRoot, input) {
         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: [],
+        coverage: [],
+        prdAnchors: [],
+        sourcePaths: splitList(input.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 rendered = renderAtomicKnowledge({
+        id,
+        title,
+        summary: contentSummary,
+        type: kindTypeMap[kind],
+        kind,
+        subject,
+        status,
+        stability,
+        createdAt,
+        scope: splitList(input.scope),
+        tags: splitList(input.tags),
+        sourcePaths: splitList(input.source),
+        verification: splitList(input.verification),
+        coverage: splitList(input.coverage),
+        prdAnchors: splitList(input.anchor),
+        contentFields
+    });
+    writeText(fullPath, rendered);
+    return {
+        path: relativePath,
+        id,
+        title,
+        type: kindTypeMap[kind],
+        status,
+        stability,
+        createdAt
+    };
+}
+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 = cards.find((item) => item.id === target || item.path === target || item.path.endsWith(`/${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: mergeList(metadata.sourcePaths, input.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)) {
@@ -61,6 +245,133 @@ export function discoverKnowledgeCards(projectRoot) {
     })
         .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 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: cards.map(stripSearchable)
+    };
+    writeJson(path.join(projectRoot, result.artifactPath), result);
+    return result;
+}
+export function checkKnowledgeCoverage(projectRoot) {
+    const cards = discoverKnowledgeCards(projectRoot);
+    if (!isReadableDirectory(harnessPath(projectRoot, "knowledge"))) {
+        return {
+            status: "not_configured",
+            prdSourceCount: 0,
+            coveredPrdSourceCount: 0,
+            uncoveredPrdSources: [],
+            prdSourcesWithoutCoverageItems: [],
+            missingSourcePaths: [],
+            cardsWithoutSource: [],
+            cardsWithoutCoverage: [],
+            warnings: ["Create .frontend-harness/knowledge before checking project knowledge coverage."],
+            errors: []
+        };
+    }
+    const prdSources = summarizePrdSources(projectRoot, cards);
+    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) && !fs.existsSync(path.join(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 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.`),
+        ...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}`),
+        ...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,
+        warnings,
+        errors
+    };
+}
+export function listKnowledge(projectRoot, options = {}) {
+    const cards = discoverKnowledgeCards(projectRoot)
+        .filter((card) => options.includeDeprecated || card.status === "active")
+        .map(stripSearchable);
+    return { cards };
+}
+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)
+        .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);
+    })
+        .slice(0, limit)
+        .map(({ card, score }) => ({
+        ...stripSearchable(card),
+        score
+    }));
+    return { query: query ?? "", cards };
+}
+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 = cards.find((item) => item.id === target || item.path === target || item.path.endsWith(`/${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)
+    };
+}
 export function checkKnowledge(projectRoot) {
     const knowledgeRoot = harnessPath(projectRoot, "knowledge");
     const relativeRoot = path.relative(projectRoot, knowledgeRoot).split(path.sep).join(path.posix.sep);
@@ -115,6 +426,23 @@ export function checkKnowledge(projectRoot) {
                 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.sourcePaths.some(isPrdSourcePath) && parsed.metadata.coverage.length === 0) {
+                warnings.push(`${relativePath} should include coverage items for PRD block traceability.`);
+            }
+        }
+        for (const sourcePath of parsed.metadata.sourcePaths) {
+            if (sourcePath && !isExternalReference(sourcePath) && !fs.existsSync(path.join(projectRoot, sourcePath))) {
+                warnings.push(`${relativePath} source path does not exist: ${sourcePath}.`);
+            }
+        }
     }
     for (const duplicateId of duplicateIds) {
         errors.push(`Duplicate knowledge id: ${duplicateId}.`);
@@ -140,9 +468,11 @@ function describeKnowledgeCard(projectRoot, fullPath) {
         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;
@@ -156,6 +486,16 @@ function describeKnowledgeCard(projectRoot, fullPath) {
         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,
@@ -169,18 +509,37 @@ function describeKnowledgeCard(projectRoot, fullPath) {
             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
+            ...related,
+            body
         ].join(" "))
     };
 }
+function stripSearchable(card) {
+    const { searchable, ...publicCard } = card;
+    void searchable;
+    return publicCard;
+}
 function parseKnowledgeFrontmatter(content) {
     const metadata = {
         scope: [],
         tags: [],
+        verification: [],
+        coverage: [],
+        prdAnchors: [],
         sourcePaths: [],
         related: []
     };
@@ -191,7 +550,7 @@ function parseKnowledgeFrontmatter(content) {
     if (endIndex < 0) {
         return { hasFrontmatter: false, metadata };
     }
-    const listKeys = new Set(["scope", "tags", "source_paths", "related"]);
+    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 line of content.slice(startIndex, endIndex).split(/\r?\n/)) {
@@ -214,7 +573,7 @@ function parseKnowledgeFrontmatter(content) {
         }
         const key = pair[1] ?? "";
         const value = (pair[2] ?? "").trim();
-        if (key === "id" || key === "title" || key === "summary" || key === "type" || key === "status" || key === "stability") {
+        if (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") {
             metadata[key] = unquoteScalar(value);
             currentList = null;
             continue;
@@ -225,7 +584,11 @@ function parseKnowledgeFrontmatter(content) {
             continue;
         }
         if (listKeys.has(key)) {
-            const mappedKey = key === "source_paths" ? "sourcePaths" : key;
+            const mappedKey = key === "source_paths"
+                ? "sourcePaths"
+                : key === "prd_anchors"
+                    ? "prdAnchors"
+                    : key;
             metadata[mappedKey] = parseListValue(value);
             currentList = value ? null : mappedKey;
             continue;
@@ -248,6 +611,17 @@ function validateKnowledgeMetadata(relativePath, metadata) {
     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(", ")}.`);
     }
@@ -259,6 +633,93 @@ function validateKnowledgeMetadata(relativePath, metadata) {
     }
     return errors;
 }
+function renderKnowledgeFromMetadata(metadata, body) {
+    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)}
+---
+
+${body.trim()}
+`;
+}
+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 `---
@@ -268,6 +729,8 @@ 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)}
@@ -308,11 +771,69 @@ function parseKnowledgeStability(value, label) {
     }
     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 mergeList(existing, next) {
+    if (next === undefined) {
+        return existing;
+    }
+    return [...new Set([...existing, ...splitList(next)])];
+}
 function parseListValue(value) {
     if (!value || value === "[]") {
         return [];
@@ -336,6 +857,9 @@ function slugify(value) {
         .replace(/^-+|-+$/g, "")
         .slice(0, 80);
 }
+function titleCase(value) {
+    return value.slice(0, 1).toUpperCase() + value.slice(1);
+}
 function formatKnowledgeStamp(createdAt) {
     return createdAt
         .replace(/[-:]/g, "")
@@ -384,4 +908,117 @@ function listMarkdownFiles(directory, errors) {
 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) {
+    return /^[a-z][a-z0-9+.-]*:/i.test(value);
+}
+function summarizePrdSources(projectRoot, cards) {
+    const grouped = new Map();
+    for (const sourcePath of discoverPrdSourceFiles(projectRoot)) {
+        grouped.set(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]) => ({
+        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()
+    }));
+}
+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)));
+        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: relatedAtomicCards.map((card) => card.id).sort()
+        };
+    })
+        .sort((left, right) => left.path.localeCompare(right.path));
+}
+function discoverPrdSourceFiles(projectRoot) {
+    const roots = ["docs/prd", "docs/requirements", "prd", "requirements"];
+    return [...new Set(roots.flatMap((root) => {
+            const fullPath = path.join(projectRoot, root);
+            return isReadableDirectory(fullPath)
+                ? listMarkdownFiles(fullPath).map((filePath) => path.relative(projectRoot, filePath).replace(/\\/g, "/"))
+                : [];
+        }))].sort();
+}
+function isPrdSourcePath(sourcePath) {
+    return /(^|\/)(prd|requirements?)(\/|[-_.])|(^|\/)docs\/(prd|requirements?)(\/|$)/i.test(sourcePath);
+}
+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=knowledge.js.map