frontend-harness 0.8.3 → 0.8.5

package/dist/runtime/knowledge/core.js

@@ -13,6 +13,7 @@ export const MAX_KNOWLEDGE_DRAFT_EXTRACTION_ITEMS = 40;
 export const MAX_KNOWLEDGE_INDEX_CARDS = 20;
 export const MAX_KNOWLEDGE_INDEX_DETAIL_ITEMS = 20;
 const MAX_KNOWLEDGE_REFERENCE_SUGGESTIONS = 20;
+const MIN_SELF_CONTAINED_PRD_CONTENT_CHARS = 80;
 export function promoteKnowledge(projectRoot, input) {
     const title = input.title?.trim();
     const body = input.body?.trim();
@@ -29,6 +30,8 @@ export function promoteKnowledge(projectRoot, input) {
     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 coverage = splitList(input.coverage);
+    const sourcePaths = parseKnowledgeSourcePaths(projectRoot, input.source, "knowledge promote --source");
     const content = renderKnowledge({
         id,
         title,
@@ -40,9 +43,9 @@ export function promoteKnowledge(projectRoot, input) {
         scope: splitList(input.scope),
         tags: splitList(input.tags),
         verification: splitList(input.verification),
-        coverage: splitList(input.coverage),
+        coverage,
         prdAnchors: splitList(input.anchor),
-        sourcePaths: parseKnowledgeSourcePaths(input.source, "knowledge promote --source")
+        sourcePaths
     });
     writeText(path.join(projectRoot, relativePath), content);
     return {
@@ -75,6 +78,8 @@ export function createModuleKnowledge(projectRoot, input) {
     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 coverage = splitList(input.coverage);
+    const sourcePaths = parseKnowledgeSourcePaths(projectRoot, input.source, "knowledge module --source");
     const relativePath = relativeHarnessPath("knowledge", "modules", `${id}.md`);
     const fullPath = path.join(projectRoot, relativePath);
     if (fs.existsSync(fullPath)) {
@@ -91,9 +96,9 @@ export function createModuleKnowledge(projectRoot, input) {
         scope: splitList(input.scope),
         tags: splitList(input.tags),
         verification: splitList(input.verification),
-        coverage: splitList(input.coverage),
+        coverage,
         prdAnchors: splitList(input.anchor),
-        sourcePaths: parseKnowledgeSourcePaths(input.source, "knowledge module --source"),
+        sourcePaths,
         related: splitList(input.related)
     }, body);
     writeText(fullPath, content);
@@ -133,8 +138,9 @@ export function addKnowledge(projectRoot, input) {
     const contentFields = atomicContentFields(kind, input);
     const inputSummary = input.summary?.trim();
     const contentSummary = inputSummary || summarizeAtomicContent(kind, subject, contentFields);
-    const sourcePaths = parseKnowledgeSourcePaths(input.source, "knowledge add --source");
+    const sourcePaths = parseKnowledgeSourcePaths(projectRoot, input.source, "knowledge add --source");
     const type = typeForAtomicKnowledge(kind, sourcePaths);
+    const coverage = splitList(input.coverage);
     const rendered = renderAtomicKnowledge({
         id,
         title,
@@ -149,7 +155,7 @@ export function addKnowledge(projectRoot, input) {
         tags: splitList(input.tags),
         sourcePaths,
         verification: splitList(input.verification),
-        coverage: splitList(input.coverage),
+        coverage,
         prdAnchors: splitList(input.anchor),
         contentFields
     });
@@ -627,7 +633,7 @@ export function updateKnowledge(projectRoot, input) {
         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"),
+        sourcePaths: mergeKnowledgeSourcePaths(projectRoot, metadata.sourcePaths, input.source, "knowledge update --source"),
         related: mergeList(metadata.related, input.related)
     };
     for (const key of ["rule", "workflow", "permission", "term", "note"]) {
@@ -700,63 +706,46 @@ export function checkKnowledgeCoverage(projectRoot, options = {}) {
             prdSourceCount: 0,
             coveredPrdSourceCount: 0,
             uncoveredPrdSources: [],
-            prdSourcesWithoutCoverageItems: [],
             missingSourcePaths: [],
-            cardsWithoutSource: [],
-            cardsWithoutCoverage: [],
-            cardsWithBroadCoverage: [],
-            cardsWithTraceabilityDrift: [],
+            cardsWithThinContent: [],
+            cardsWithPlaceholderContent: [],
             warnings: ["Create .frontend-harness/knowledge before checking project knowledge coverage."],
             errors: []
         };
     }
     const prdSources = summarizePrdSources(projectRoot, cards, options.requiredPrdSources ?? []);
+    const activePrdKnowledgeCards = cards.filter((card) => card.status === "active" && isPrdKnowledgeQualityCard(card));
     const uncoveredPrdSources = prdSources
         .filter((source) => source.activeCardCount === 0)
         .map((source) => source.path);
+    const requiredPrdKnowledgeMissing = (options.requiredPrdSources?.length ?? 0) > 0 && activePrdKnowledgeCards.length === 0
+        ? (uncoveredPrdSources.length ? uncoveredPrdSources : options.requiredPrdSources ?? [])
+        : [];
     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)
+    const cardsWithThinContent = cards
+        .filter((card) => card.status === "active" && isPrdKnowledgeQualityCard(card) && isThinSelfContainedKnowledge(card))
         .map((card) => card.path);
-    const cardsWithBroadCoverage = cards
-        .filter((card) => card.status === "active" && isPrdTraceableCard(card) && card.coverage.some(isBroadCoverageItem))
+    const cardsWithPlaceholderContent = cards
+        .filter((card) => card.status === "active" && isPrdKnowledgeQualityCard(card) && hasPlaceholderKnowledgeContent(card))
         .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}`),
+        ...uncoveredPrdSources.map((sourcePath) => `PRD source has no active knowledge cards: ${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}`)
+        ...requiredPrdKnowledgeMissing.map((sourcePath) => `PRD input has no active self-contained knowledge cards: ${sourcePath}`),
+        ...cardsWithThinContent.map((cardPath) => `${cardPath} is too thin to replace deleted PRD source material; keep self-contained implementation constraints.`),
+        ...cardsWithPlaceholderContent.map((cardPath) => `${cardPath} still contains scaffold placeholder text instead of durable knowledge.`)
     ];
     return {
-        status: errors.length || cardsWithoutSource.length || cardsWithoutCoverage.length ? "failed" : "passed",
+        status: errors.length ? "failed" : "passed",
         prdSourceCount: prdSources.length,
         coveredPrdSourceCount: prdSources.filter((source) => source.activeCardCount > 0).length,
         uncoveredPrdSources,
-        prdSourcesWithoutCoverageItems,
         missingSourcePaths,
-        cardsWithoutSource,
-        cardsWithoutCoverage,
-        cardsWithBroadCoverage,
-        cardsWithTraceabilityDrift,
+        cardsWithThinContent,
+        cardsWithPlaceholderContent,
         warnings,
         errors
     };
@@ -908,15 +897,6 @@ export function checkKnowledge(projectRoot) {
             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)) {
@@ -1177,44 +1157,23 @@ function validateKnowledgeMetadata(relativePath, metadata) {
     return errors;
 }
 function renderKnowledgeFromMetadata(metadata, body) {
-    const renderedBody = renderBodyWithTraceability(body, metadata.coverage ?? [], metadata.prdAnchors ?? [], metadata.verification ?? []);
+    const renderedBody = renderBodyWithVerification(body, 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)}
+${renderOptionalScalar("subject", metadata.subject)}${renderOptionalScalar("rule", metadata.rule)}${renderOptionalScalar("workflow", metadata.workflow)}${renderOptionalScalar("permission", metadata.permission)}${renderOptionalScalar("term", metadata.term)}${renderOptionalList("scope", metadata.scope)}${renderOptionalList("tags", metadata.tags)}${renderOptionalList("verification", metadata.verification)}${renderOptionalList("coverage", metadata.coverage ?? [])}${renderOptionalList("prd_anchors", metadata.prdAnchors ?? [])}status: ${yamlScalar(metadata.status)}
 stability: ${yamlScalar(metadata.stability)}
 updated_at: ${yamlScalar(metadata.updatedAt)}
-source_paths:
-${renderList(metadata.sourcePaths)}
-related:
-${renderList(metadata.related)}
+${renderOptionalList("source_paths", metadata.sourcePaths)}${renderOptionalList("related", metadata.related)}
 ---
 
 ${renderedBody}
 `;
 }
-function renderBodyWithTraceability(body, coverage, prdAnchors, verification) {
+function renderBodyWithVerification(body, 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",
@@ -1232,33 +1191,24 @@ 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)}
+${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)}${renderOptionalList("scope", input.scope)}${renderOptionalList("tags", input.tags)}${renderOptionalList("verification", input.verification)}${renderOptionalList("coverage", input.coverage)}${renderOptionalList("prd_anchors", input.prdAnchors)}status: ${yamlScalar(input.status)}
 stability: ${yamlScalar(input.stability)}
 updated_at: ${yamlScalar(input.createdAt)}
-source_paths:
-${renderList(input.sourcePaths)}
-related: []
+${renderOptionalList("source_paths", input.sourcePaths)}
 ---
 
 # ${input.title}
 
-${renderAtomicBody(input.kind, input.subject, input.summary, input.contentFields, input.coverage, input.prdAnchors, input.verification)}
+${renderAtomicBody(input.kind, input.subject, input.summary, input.contentFields, input.verification)}
 `;
 }
 function renderOptionalScalar(key, value) {
     return value ? `${key}: ${yamlScalar(value)}\n` : "";
 }
-function renderAtomicBody(kind, subject, summary, contentFields, coverage, prdAnchors, verification) {
+function renderOptionalList(key, items) {
+    return items.length ? `${key}:\n${renderList(items)}\n` : "";
+}
+function renderAtomicBody(kind, subject, summary, contentFields, verification) {
     const contentEntries = Object.entries(contentFields).filter(([, value]) => Boolean(value?.trim()));
     const primaryLabel = titleCase(contentKeyForKind(kind));
     const primaryValue = contentFields[contentKeyForKind(kind)] ?? contentEntries[0]?.[1];
@@ -1277,36 +1227,25 @@ function renderAtomicBody(kind, subject, summary, contentFields, coverage, prdAn
     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."]));
+    if (verification.length) {
+        sections.push("", "## Verification", "", ...verification.map((item) => `- ${item}`));
+    }
     return [
         ...sections
     ].join("\n");
 }
 function renderKnowledge(input) {
     const summary = firstBodyLine(input.body) ?? input.title;
-    const body = renderBodyWithTraceability(input.body, input.coverage, input.prdAnchors, input.verification);
+    const body = renderBodyWithVerification(input.body, input.verification);
     return `---
 id: ${yamlScalar(input.id)}
 type: ${yamlScalar(input.type)}
 title: ${yamlScalar(input.title)}
 summary: ${yamlScalar(summary)}
-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)}
+${renderOptionalList("scope", input.scope)}${renderOptionalList("tags", input.tags)}${renderOptionalList("verification", input.verification)}${renderOptionalList("coverage", input.coverage)}${renderOptionalList("prd_anchors", input.prdAnchors)}status: ${yamlScalar(input.status)}
 stability: ${yamlScalar(input.stability)}
 updated_at: ${yamlScalar(input.createdAt)}
-source_paths:
-${renderList(input.sourcePaths)}
-related: []
+${renderOptionalList("source_paths", input.sourcePaths)}
 ---
 
 # ${input.title}
@@ -1398,25 +1337,35 @@ function splitList(value) {
         ? value.split(",").map((item) => item.trim()).filter(Boolean)
         : [];
 }
-function parseKnowledgeSourcePaths(value, label) {
-    const sourcePaths = splitList(value);
+function parseKnowledgeSourcePaths(projectRoot, value, label) {
+    const sourcePaths = canonicalKnowledgeInputSourcePaths(projectRoot, 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) {
+function mergeKnowledgeSourcePaths(projectRoot, existing, next, label) {
     if (next === undefined) {
         return existing;
     }
-    const merged = [...new Set([...existing, ...splitList(next)])];
+    const merged = [...new Set(canonicalKnowledgeInputSourcePaths(projectRoot, [...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 canonicalKnowledgeInputSourcePaths(projectRoot, sourcePaths) {
+    if (sourcePaths.length === 0) {
+        return [];
+    }
+    const records = listIngestRecords(projectRoot, undefined, { limit: "all" }).records;
+    return sourcePaths.map((sourcePath) => {
+        const record = records.find((item) => sameKnowledgeSourceReference(item.ingestRef, sourcePath) || sameKnowledgeSourceReference(item.source.value, sourcePath));
+        return record?.ingestRef ?? sourcePath;
+    });
+}
 function validateKnowledgeSourcePath(value) {
     if (!value.trim()) {
         return "empty";
@@ -1664,26 +1613,6 @@ function parseIngestReference(value) {
         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(">"))
@@ -1700,13 +1629,9 @@ function isDraftPlaceholderVerification(value) {
 }
 function ingestLinkedAtomicMetadataErrors(relativePath, metadata) {
     const errors = [];
-    const requiredLists = [
-        ["coverage", metadata.coverage]
-    ];
-    for (const [field, values] of requiredLists) {
-        if (values.length === 0) {
-            errors.push(`${relativePath} active ingest-linked atomic knowledge must include ${field}.`);
-        }
+    const primaryContent = primaryAtomicValue(metadata);
+    if (primaryContent && hasPlaceholderText(primaryContent)) {
+        errors.push(`${relativePath} active ingest-linked atomic knowledge must replace scaffold placeholder content.`);
     }
     return errors;
 }
@@ -1820,16 +1745,30 @@ function isPrdSourcePath(sourcePath) {
     }
     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 isPrdKnowledgeQualityCard(card) {
+    return card.type === "prd_semantics" || card.type === "module_summary";
+}
+function isThinSelfContainedKnowledge(card) {
+    return normalize(primaryCardContent(card)).length < MIN_SELF_CONTAINED_PRD_CONTENT_CHARS;
+}
+function hasPlaceholderKnowledgeContent(card) {
+    return hasPlaceholderText(primaryCardContent(card));
+}
+function primaryCardContent(card) {
+    return card.rule ?? card.workflow ?? card.permission ?? card.term ?? card.note ?? card.summary;
+}
+function hasPlaceholderText(value) {
+    const normalized = value.trim().toLowerCase();
+    return /^<.*>$/.test(normalized) || normalized.includes(" distilled from ") || normalized.includes("scaffold placeholder");
 }
 function prdSemanticMetadataErrors(relativePath, metadata) {
     const errors = [];
-    if (metadata.sourcePaths.length === 0) {
-        errors.push(`${relativePath} active PRD semantics must include source_paths.`);
+    const content = primaryAtomicValue(metadata) ?? metadata.summary ?? "";
+    if (normalize(content).length < MIN_SELF_CONTAINED_PRD_CONTENT_CHARS) {
+        errors.push(`${relativePath} active PRD semantics must be self-contained enough to replace deleted PRD source material.`);
     }
-    if (metadata.coverage.length === 0) {
-        errors.push(`${relativePath} active PRD semantics must include coverage.`);
+    if (hasPlaceholderText(content)) {
+        errors.push(`${relativePath} active PRD semantics must replace scaffold placeholder content.`);
     }
     return errors;
 }