frontend-harness 0.7.9 → 0.8.0

package/dist/runtime/task-context.js

@@ -0,0 +1,1322 @@
+import fs from "node:fs";
+import path from "node:path";
+import { relativeHarnessPath } from "../storage/paths.js";
+import { writeJson } from "../storage/json.js";
+import { isRegularFileWithoutSymlink } from "../storage/json.js";
+import { discoverKnowledgeCards } from "./knowledge.js";
+import { listIngestRecords } from "./ingest.js";
+import { inferFrontendWorkflow, inferWorkflowPlan, verificationForWorkflow } from "./plan/workflow.js";
+import { resolveProjectRelativePath } from "./project-paths.js";
+import { discoverProjectSurface } from "./project-discovery.js";
+import { externalDesignReference, inferLocalUiSourceKind, isGeneratedMarkupExtension, isVisualArtifactExtension, unsupportedDesignSourceUrlMessage } from "./ui-source.js";
+const DEFAULT_CONTEXT_CARD_LIMIT = 8;
+const MAX_CONTEXT_CARD_LIMIT = 20;
+const PROJECT_FILE_LIMIT = 8;
+const MAX_PROJECT_FILES_SCANNED = 300;
+const SOURCE_HINT_LIMIT = 8;
+const INGEST_SOURCE_LIMIT = 8;
+const MAX_API_SOURCE_HINT_BYTES = 256 * 1024;
+const MAX_PRD_SOURCE_HINT_BYTES = 128 * 1024;
+const MAX_PRD_HEADINGS_SCANNED = 40;
+const KNOWLEDGE_CARD_FIELD_VALUE_LIMIT = 8;
+const INGEST_PRODUCED_CARD_ID_LIMIT = 8;
+const MAX_PROMPT_FIELD_CHARS = 240;
+const PROJECT_FILE_EXTENSIONS = new Set([".vue", ".tsx", ".jsx", ".ts", ".js", ".mjs", ".cjs", ".css", ".scss", ".sass", ".less"]);
+const PROJECT_FILE_EXTRA_ROOTS = [
+    "api",
+    "apis",
+    "client",
+    "clients",
+    "service",
+    "services",
+    "tests",
+    "test",
+    "e2e",
+    "playwright",
+    "cypress"
+];
+const IGNORED_DIRECTORIES = new Set([".frontend-harness", ".git", "build", "coverage", "dist", "node_modules", ".cache", ".turbo"]);
+const SEPARATED_TOKEN_STOP_WORDS = new Set(["center", "docs", "prd", "spec", "md", "json", "yaml", "yml"]);
+export function buildCompactTaskContext(projectRoot, options) {
+    const task = options.taskText.trim();
+    if (!task) {
+        throw new Error("context task requires <task>");
+    }
+    const limit = normalizeLimit(options.limit);
+    const inputs = {
+        ...(options.prd ? { prd: normalizeTaskPrdReference(projectRoot, options.prd) } : {}),
+        ...(options.apiSource ? { apiSource: normalizeTaskApiSourceReference(projectRoot, options.apiSource) } : {}),
+        ...(options.uiSource ? { uiSource: normalizeTaskUiSourceReference(projectRoot, options.uiSource) } : {})
+    };
+    const workflow = inferFrontendWorkflow(task, inputs, null);
+    const workflowPlan = inferWorkflowPlan(workflow, task, inputs, null);
+    const selectedKnowledge = selectKnowledge(projectRoot, task, limit, inputs);
+    const compactKnowledge = compactKnowledgeCards(selectedKnowledge.cards);
+    const selectedIngest = selectIngestSources(projectRoot, task, selectedKnowledge.cards, inputs);
+    const compactIngest = compactIngestSources(selectedIngest.records);
+    const selectedProjectFiles = selectProjectFiles(projectRoot, task, inputs, selectedKnowledge.cards);
+    const sourceHints = buildSourceHints(projectRoot, task, inputs, selectedKnowledge.cards, selectedIngest.records);
+    const limits = compactTaskContextLimits(limit, selectedKnowledge.omitted, compactKnowledge.omittedSourcePaths, compactKnowledge.omittedCoverage, compactKnowledge.omittedVerification, selectedIngest.omitted, compactIngest.omittedProducedKnowledgeCardIds, selectedProjectFiles.omitted, sourceHints.omitted, sourceHints.omittedPrdCoverageHintCoverage, sourceHints.omittedPrdCoverageHintAnchors, sourceHints.omittedPrdCoverageHintSourcePaths, selectedProjectFiles.scanned, selectedProjectFiles.scanLimitReached, sourceHints.skippedPrdSourceHintSources, sourceHints.skippedApiSourceHintSources);
+    const context = {
+        contractVersion: 1,
+        task,
+        inputs,
+        workflow: {
+            kind: workflow.kind,
+            summary: workflow.summary,
+            verificationFocus: verificationForWorkflow(workflow.kind)
+        },
+        selectedKnowledge: compactKnowledge.cards,
+        selectedIngestSources: compactIngest.records,
+        selectedProjectFiles: selectedProjectFiles.files,
+        sourceHints: sourceHints.hints,
+        limits,
+        prompt: renderPrompt(task, inputs, workflow.kind, workflow.summary, workflowPlan.stages.map((stage) => stage.kind), selectedKnowledge.cards, selectedIngest.records, selectedProjectFiles.files, sourceHints.hints, limits),
+        artifactPath: relativeHarnessPath("context", "task-latest.json")
+    };
+    writeJson(path.join(projectRoot, context.artifactPath), context);
+    return context;
+}
+function selectKnowledge(projectRoot, task, limit, inputs) {
+    const tokens = taskTokens(task);
+    const sourceReferences = taskInputSourceReferences(projectRoot, inputs);
+    const matches = discoverKnowledgeCards(projectRoot)
+        .filter((card) => card.status === "active")
+        .map((card) => ({
+        card,
+        score: scoreKnowledgeCard(card, tokens, sourceReferences)
+    }))
+        .filter((item) => item.score > 0)
+        .sort((left, right) => right.score - left.score || left.card.path.localeCompare(right.card.path));
+    const cards = matches.slice(0, limit).map((item) => item.card);
+    return {
+        cards,
+        omitted: Math.max(0, matches.length - cards.length)
+    };
+}
+function taskInputSourceReferences(projectRoot, inputs) {
+    const references = {
+        prd: new Set(inputs.prd ? [normalizeSourcePath(inputs.prd)] : []),
+        api: new Set(inputs.apiSource ? [normalizeSourcePath(inputs.apiSource)] : []),
+        ui: new Set(inputs.uiSource ? [normalizeSourcePath(inputs.uiSource.value)] : [])
+    };
+    const records = listIngestRecords(projectRoot, undefined, { limit: "all" }).records;
+    addMatchingIngestSourceReferences(references.prd, records, "prd", inputs.prd);
+    addMatchingIngestSourceReferences(references.api, records, "openapi", inputs.apiSource);
+    addMatchingIngestSourceReferences(references.ui, records, "ui-package", inputs.uiSource?.value);
+    return references;
+}
+function addMatchingIngestSourceReferences(references, records, kind, source) {
+    if (!source) {
+        return;
+    }
+    for (const record of records) {
+        if (record.kind === kind && sameSourceReference(record.source.value, source)) {
+            references.add(normalizeSourcePath(record.ingestRef));
+        }
+    }
+}
+function selectIngestSources(projectRoot, task, cards, inputs) {
+    const tokens = taskTokens(task);
+    const sourceRefs = new Set(cards.flatMap((card) => card.sourcePaths).map(ingestRefKey).filter((sourcePath) => sourcePath !== null));
+    const inputSources = [inputs.prd, inputs.apiSource, inputs.uiSource?.value].filter((source) => Boolean(source));
+    const matches = listIngestRecords(projectRoot, undefined, { limit: "all" }).records
+        .map((record) => ({
+        record,
+        score: (sourceRefs.has(ingestRefKey(record.ingestRef) ?? record.ingestRef) ? 100 : 0)
+            + (inputSources.some((source) => sameSourceReference(record.source.value, source)) ? 100 : 0)
+            + scoreText(`${record.ingestRef} ${record.summary} ${record.source.value}`, tokens)
+    }))
+        .filter((item) => item.score > 0)
+        .sort((left, right) => right.score - left.score || left.record.ingestRef.localeCompare(right.record.ingestRef));
+    const records = matches.slice(0, INGEST_SOURCE_LIMIT).map((item) => item.record);
+    return {
+        records,
+        omitted: Math.max(0, matches.length - records.length)
+    };
+}
+function selectProjectFiles(projectRoot, task, inputs, cards) {
+    const baseTokens = taskTokens([task, inputs.prd ?? "", inputs.apiSource ?? "", inputs.uiSource?.value ?? ""].join(" "));
+    const knowledgeTokens = taskTokens(projectFileKnowledgeSignals(cards));
+    const surface = discoverProjectSurface(projectRoot);
+    const candidates = scanProjectFiles(projectRoot, candidateProjectFileRoots(projectRoot, surface.sourceRoots));
+    const matches = candidates
+        .map((file) => {
+        const baseScore = scoreText(file, baseTokens);
+        const knowledgeScore = scoreText(file, knowledgeTokens);
+        return {
+            path: file,
+            score: baseScore + knowledgeScore,
+            reason: projectFileMatchReason(baseScore, knowledgeScore)
+        };
+    })
+        .filter((item) => item.score > 0)
+        .sort((left, right) => right.score - left.score || left.path.localeCompare(right.path));
+    const files = matches.slice(0, PROJECT_FILE_LIMIT).map((item) => ({
+        path: item.path,
+        reason: item.reason
+    }));
+    return {
+        files,
+        omitted: Math.max(0, matches.length - files.length),
+        scanned: candidates.length,
+        scanLimitReached: candidates.length >= MAX_PROJECT_FILES_SCANNED
+    };
+}
+function candidateProjectFileRoots(projectRoot, sourceRoots) {
+    return minimizeProjectFileRoots([...new Set([
+            ...sourceRoots,
+            ...PROJECT_FILE_EXTRA_ROOTS.filter((root) => {
+                const stat = fs.lstatSync(path.join(projectRoot, root), { throwIfNoEntry: false });
+                return stat?.isDirectory() && !stat.isSymbolicLink();
+            })
+        ])]);
+}
+function minimizeProjectFileRoots(roots) {
+    return roots.filter((root) => !roots.some((candidate) => candidate !== root && isProjectRootParent(candidate, root)));
+}
+function isProjectRootParent(parent, child) {
+    const normalizedParent = parent.replace(/\\/g, "/").replace(/\/+$/, "");
+    const normalizedChild = child.replace(/\\/g, "/").replace(/\/+$/, "");
+    return normalizedChild.startsWith(`${normalizedParent}/`);
+}
+function projectFileKnowledgeSignals(cards) {
+    return cards.map((card) => [
+        card.id,
+        card.title,
+        card.subject ?? "",
+        ...card.scope,
+        ...card.tags,
+        ...card.sourcePaths
+    ].join(" ")).join(" ");
+}
+function projectFileMatchReason(baseScore, knowledgeScore) {
+    if (baseScore > 0 && knowledgeScore > 0) {
+        return "matched task and selected knowledge terms in project file path";
+    }
+    if (knowledgeScore > 0) {
+        return "matched selected knowledge terms in project file path";
+    }
+    return "matched task terms in project file path";
+}
+function scanProjectFiles(projectRoot, sourceRoots) {
+    const files = [];
+    for (const root of sourceRoots) {
+        collectProjectFiles(projectRoot, root, files, 0);
+        if (files.length >= MAX_PROJECT_FILES_SCANNED) {
+            break;
+        }
+    }
+    return [...new Set(files)].slice(0, MAX_PROJECT_FILES_SCANNED);
+}
+function collectProjectFiles(projectRoot, relativeDir, files, depth) {
+    if (files.length >= MAX_PROJECT_FILES_SCANNED || depth > 5) {
+        return;
+    }
+    const fullDir = path.join(projectRoot, relativeDir);
+    const stat = fs.lstatSync(fullDir, { throwIfNoEntry: false });
+    if (!stat?.isDirectory() || stat.isSymbolicLink()) {
+        return;
+    }
+    for (const entry of fs.readdirSync(fullDir, { withFileTypes: true })) {
+        if (files.length >= MAX_PROJECT_FILES_SCANNED) {
+            return;
+        }
+        const relativePath = path.posix.join(relativeDir.replace(/\\/g, "/"), entry.name);
+        if (entry.isDirectory()) {
+            if (!IGNORED_DIRECTORIES.has(entry.name)) {
+                collectProjectFiles(projectRoot, relativePath, files, depth + 1);
+            }
+            continue;
+        }
+        if (entry.isFile() && PROJECT_FILE_EXTENSIONS.has(path.extname(entry.name).toLowerCase())) {
+            files.push(relativePath);
+        }
+    }
+}
+function compactKnowledgeCards(cards) {
+    return cards.reduce((result, card) => {
+        result.cards.push(compactKnowledgeCard(card));
+        result.omittedSourcePaths += omittedFieldValues(card.sourcePaths);
+        result.omittedCoverage += omittedFieldValues(card.coverage);
+        result.omittedVerification += omittedFieldValues(card.verification);
+        return result;
+    }, {
+        cards: [],
+        omittedSourcePaths: 0,
+        omittedCoverage: 0,
+        omittedVerification: 0
+    });
+}
+function compactKnowledgeCard(card) {
+    return {
+        id: card.id,
+        title: card.title,
+        summary: card.summary,
+        type: card.type,
+        kind: card.kind ?? null,
+        path: card.path,
+        sourcePaths: limitFieldValues(card.sourcePaths),
+        coverage: limitFieldValues(card.coverage),
+        verification: limitFieldValues(card.verification)
+    };
+}
+function limitFieldValues(values) {
+    return values.slice(0, KNOWLEDGE_CARD_FIELD_VALUE_LIMIT);
+}
+function omittedFieldValues(values) {
+    return Math.max(0, values.length - KNOWLEDGE_CARD_FIELD_VALUE_LIMIT);
+}
+function compactIngestSources(records) {
+    return records.reduce((result, record) => {
+        result.records.push(compactIngestSource(record));
+        result.omittedProducedKnowledgeCardIds += Math.max(0, record.producedKnowledgeCardIds.length - INGEST_PRODUCED_CARD_ID_LIMIT);
+        return result;
+    }, {
+        records: [],
+        omittedProducedKnowledgeCardIds: 0
+    });
+}
+function compactIngestSource(record) {
+    return {
+        ingestRef: record.ingestRef,
+        kind: record.kind,
+        summary: record.summary,
+        source: record.source.value,
+        sourceType: record.source.type,
+        sha256: record.source.sha256,
+        sizeBytes: record.source.sizeBytes,
+        producedKnowledgeCardIds: record.producedKnowledgeCardIds.slice(0, INGEST_PRODUCED_CARD_ID_LIMIT),
+        artifactPath: record.artifactPath
+    };
+}
+function buildSourceHints(projectRoot, task, inputs, cards, ingestSources) {
+    const prdCoverageCandidates = selectPrdCoverageHints(projectRoot, task, inputs, cards, ingestSources);
+    const uiArtifactSelection = selectUiArtifactHints(task, inputs, ingestSources, cards);
+    const uiArtifactCandidates = uiArtifactSelection.hints;
+    const apiImplementationSelection = selectApiImplementationHints(projectRoot, task, inputs, cards, ingestSources);
+    const apiImplementationCandidates = apiImplementationSelection.hints;
+    const endpointCandidates = selectEndpointHints(projectRoot, task, inputs, cards, ingestSources);
+    const endpoints = endpointCandidates.slice(0, sourceHintSliceLimit([], [prdCoverageCandidates, uiArtifactCandidates, apiImplementationCandidates]));
+    const prdCoverageSelections = prdCoverageCandidates.slice(0, sourceHintSliceLimit([endpoints], [uiArtifactCandidates, apiImplementationCandidates]));
+    const prdCoverage = prdCoverageSelections.map((selection) => selection.hint);
+    const uiArtifacts = uiArtifactCandidates.slice(0, sourceHintSliceLimit([endpoints, prdCoverage], [apiImplementationCandidates]));
+    const apiImplementations = apiImplementationCandidates.slice(0, remainingSourceHintBudget(endpoints, prdCoverage, uiArtifacts));
+    return {
+        hints: {
+            endpoints,
+            prdCoverage,
+            uiArtifacts,
+            apiImplementations
+        },
+        omitted: Math.max(0, endpointCandidates.length - endpoints.length)
+            + Math.max(0, prdCoverageCandidates.length - prdCoverage.length)
+            + Math.max(0, uiArtifactCandidates.length - uiArtifacts.length)
+            + uiArtifactSelection.omitted
+            + Math.max(0, apiImplementationCandidates.length - apiImplementations.length)
+            + apiImplementationSelection.omitted,
+        omittedPrdCoverageHintCoverage: prdCoverageSelections.reduce((total, selection) => total + selection.omittedCoverage, 0),
+        omittedPrdCoverageHintAnchors: prdCoverageSelections.reduce((total, selection) => total + selection.omittedAnchors, 0),
+        omittedPrdCoverageHintSourcePaths: prdCoverageSelections.reduce((total, selection) => total + selection.omittedSourcePaths, 0),
+        skippedPrdSourceHintSources: countSkippedPrdSourceHintSources(projectRoot, inputs),
+        skippedApiSourceHintSources: countSkippedApiSourceHintSources(projectRoot, inputs, cards, ingestSources)
+    };
+}
+function remainingSourceHintBudget(...groups) {
+    const used = groups.reduce((total, group) => total + group.length, 0);
+    return Math.max(0, SOURCE_HINT_LIMIT - used);
+}
+function sourceHintSliceLimit(selectedGroups, followingCandidateGroups) {
+    const used = selectedGroups.reduce((total, group) => total + group.length, 0);
+    const reserved = followingCandidateGroups.filter((group) => group.length > 0).length;
+    return Math.max(0, SOURCE_HINT_LIMIT - used - reserved);
+}
+function countSkippedApiSourceHintSources(projectRoot, inputs, cards, ingestSources) {
+    const sources = [
+        ...(inputs.apiSource ? [inputs.apiSource] : []),
+        ...selectedApiContractSourceCandidates(cards, ingestSources).map((source) => source.apiSource)
+    ];
+    const seen = new Set();
+    let skipped = 0;
+    for (const source of sources) {
+        const normalized = source.replace(/\\/g, "/").toLowerCase();
+        if (seen.has(normalized)) {
+            continue;
+        }
+        seen.add(normalized);
+        if (/^https?:\/\//i.test(source)) {
+            continue;
+        }
+        const stat = fs.statSync(path.join(projectRoot, source), { throwIfNoEntry: false });
+        if (stat?.isFile() && stat.size > MAX_API_SOURCE_HINT_BYTES) {
+            skipped += 1;
+        }
+    }
+    return skipped;
+}
+function countSkippedPrdSourceHintSources(projectRoot, inputs) {
+    if (!inputs.prd || /^https?:\/\//i.test(inputs.prd)) {
+        return 0;
+    }
+    const stat = fs.statSync(path.join(projectRoot, inputs.prd), { throwIfNoEntry: false });
+    return stat?.isFile() && stat.size > MAX_PRD_SOURCE_HINT_BYTES ? 1 : 0;
+}
+function compactTaskContextLimits(selectedKnowledge, omittedSelectedKnowledge, omittedSelectedKnowledgeSourcePaths, omittedSelectedKnowledgeCoverage, omittedSelectedKnowledgeVerification, omittedSelectedIngestSources, omittedSelectedIngestProducedKnowledgeCardIds, omittedSelectedProjectFiles, omittedSourceHints, omittedPrdCoverageHintCoverage, omittedPrdCoverageHintAnchors, omittedPrdCoverageHintSourcePaths, totalScannedProjectFiles, projectFileScanLimitReached, skippedPrdSourceHintSources, skippedApiSourceHintSources) {
+    return {
+        selectedKnowledge,
+        selectedIngestSources: INGEST_SOURCE_LIMIT,
+        selectedProjectFiles: PROJECT_FILE_LIMIT,
+        sourceHints: SOURCE_HINT_LIMIT,
+        selectedKnowledgeFieldValues: KNOWLEDGE_CARD_FIELD_VALUE_LIMIT,
+        selectedIngestProducedKnowledgeCardIds: INGEST_PRODUCED_CARD_ID_LIMIT,
+        omittedSelectedKnowledge,
+        omittedSelectedKnowledgeSourcePaths,
+        omittedSelectedKnowledgeCoverage,
+        omittedSelectedKnowledgeVerification,
+        omittedSelectedIngestSources,
+        omittedSelectedIngestProducedKnowledgeCardIds,
+        omittedSelectedProjectFiles,
+        omittedSourceHints,
+        omittedPrdCoverageHintCoverage,
+        omittedPrdCoverageHintAnchors,
+        omittedPrdCoverageHintSourcePaths,
+        totalScannedProjectFiles,
+        projectFileScanLimitReached,
+        skippedPrdSourceHintSources,
+        skippedApiSourceHintSources,
+        scannedProjectFiles: MAX_PROJECT_FILES_SCANNED,
+        prdSourceHintBytes: MAX_PRD_SOURCE_HINT_BYTES,
+        apiSourceHintBytes: MAX_API_SOURCE_HINT_BYTES
+    };
+}
+function selectEndpointHints(projectRoot, task, inputs, cards, ingestSources) {
+    const hints = [];
+    const hintByKey = new Map();
+    for (const card of cards) {
+        const text = [
+            card.summary,
+            card.rule ?? "",
+            card.workflow ?? "",
+            card.permission ?? "",
+            card.note ?? "",
+            ...card.coverage,
+            ...card.tags
+        ].join(" ");
+        for (const endpoint of extractEndpointReferences(text)) {
+            const key = `${endpoint.method} ${endpoint.path}`;
+            if (hintByKey.has(key)) {
+                continue;
+            }
+            const hint = {
+                ...endpoint,
+                source: card.path,
+                cardId: card.id,
+                reason: "selected knowledge card"
+            };
+            hintByKey.set(key, hint);
+            hints.push(hint);
+        }
+    }
+    const explicitApiIngest = matchingIngestSourceByValue(ingestSources, "openapi", inputs.apiSource);
+    for (const endpoint of selectApiSourceEndpointHints(projectRoot, task, inputs.apiSource, explicitApiIngest ? `explicit OpenAPI source metadata; selected ingest provenance ${explicitApiIngest.ingestRef}` : "explicit OpenAPI source metadata", inputs.apiSource, explicitApiIngest?.ingestRef, explicitApiIngest?.artifactPath)) {
+        const key = `${endpoint.method} ${endpoint.path}`;
+        if (hintByKey.has(key)) {
+            const existing = hintByKey.get(key);
+            if (existing && endpointHintMatchesAnySource(existing, cards, [inputs.apiSource, explicitApiIngest?.ingestRef])) {
+                mergeEndpointHintProvenance(existing, endpoint);
+            }
+            continue;
+        }
+        hintByKey.set(key, endpoint);
+        hints.push(endpoint);
+    }
+    for (const source of selectedApiContractSourceCandidates(cards, ingestSources)) {
+        for (const endpoint of selectApiSourceEndpointHints(projectRoot, task, source.apiSource, "selected API contract knowledge source", source.displaySource, source.ingestRef, source.artifactPath)) {
+            const key = `${endpoint.method} ${endpoint.path}`;
+            const existing = hintByKey.get(key);
+            if (existing) {
+                if (endpointHintMatchesAnySource(existing, cards, [source.apiSource, source.displaySource, source.ingestRef])) {
+                    mergeEndpointHintProvenance(existing, endpoint);
+                }
+                continue;
+            }
+            hintByKey.set(key, endpoint);
+            hints.push(endpoint);
+        }
+    }
+    return hints;
+}
+function endpointHintMatchesAnySource(hint, cards, sources) {
+    const sourceValues = sources.filter((source) => Boolean(source));
+    if (sourceValues.some((source) => sameSourceReference(hint.source, source))) {
+        return true;
+    }
+    const card = hint.cardId ? cards.find((candidate) => candidate.id === hint.cardId) : undefined;
+    return Boolean(card?.sourcePaths.some((sourcePath) => sourceValues.some((source) => sameSourceReference(sourcePath, source))));
+}
+function mergeEndpointHintProvenance(existing, next) {
+    if (!existing.ingestRef && next.ingestRef) {
+        existing.ingestRef = next.ingestRef;
+    }
+    if (!existing.artifactPath && next.artifactPath) {
+        existing.artifactPath = next.artifactPath;
+    }
+    if (!existing.reason.includes(next.reason)) {
+        existing.reason = `${existing.reason}; ${next.reason}`;
+    }
+}
+function sameSourceReference(left, right) {
+    return left.replace(/\\/g, "/").toLowerCase() === right.replace(/\\/g, "/").toLowerCase();
+}
+function extractEndpointReferences(text) {
+    const endpoints = [];
+    const matches = text.matchAll(/\b(GET|POST|PUT|PATCH|DELETE|HEAD|OPTIONS)\s+((?:\/[A-Za-z0-9._~:@!$&'()*+,;=%{}-]+)+)/gi);
+    for (const match of matches) {
+        const method = match[1]?.toUpperCase();
+        const endpointPath = match[2];
+        if (method && endpointPath) {
+            endpoints.push({ method, path: endpointPath });
+        }
+    }
+    return endpoints;
+}
+function selectApiSourceEndpointHints(projectRoot, task, apiSource, reason = "explicit OpenAPI source metadata", displaySource = apiSource, ingestRef, artifactPath) {
+    if (!apiSource || /^https?:\/\//i.test(apiSource)) {
+        return [];
+    }
+    const fullPath = path.join(projectRoot, apiSource);
+    const stat = fs.statSync(fullPath, { throwIfNoEntry: false });
+    if (!stat?.isFile() || stat.size > MAX_API_SOURCE_HINT_BYTES) {
+        return [];
+    }
+    const sourceText = fs.readFileSync(fullPath, "utf8");
+    const endpoints = extractOpenApiEndpointReferences(sourceText);
+    const tokens = taskTokens(task);
+    const scored = endpoints.map((endpoint, index) => ({
+        endpoint,
+        index,
+        score: scoreText(endpoint.searchText, tokens)
+    }));
+    return scored
+        .sort((left, right) => right.score - left.score || left.index - right.index)
+        .map(({ endpoint: { method, path: endpointPath } }) => ({
+        method,
+        path: endpointPath,
+        source: displaySource ?? apiSource,
+        cardId: null,
+        reason,
+        ...(ingestRef ? { ingestRef } : {}),
+        ...(artifactPath ? { artifactPath } : {})
+    }));
+}
+function extractOpenApiEndpointReferences(sourceText) {
+    const jsonEndpoints = extractOpenApiJsonEndpointReferences(sourceText);
+    if (jsonEndpoints.length) {
+        return jsonEndpoints;
+    }
+    const yamlEndpoints = extractOpenApiYamlEndpointReferences(sourceText);
+    return yamlEndpoints.length ? yamlEndpoints : extractSwaggerMarkdownEndpointReferences(sourceText);
+}
+function extractOpenApiJsonEndpointReferences(sourceText) {
+    try {
+        const parsed = JSON.parse(sourceText);
+        if (!parsed.paths || typeof parsed.paths !== "object" || Array.isArray(parsed.paths)) {
+            return [];
+        }
+        const endpoints = [];
+        for (const [endpointPath, pathItem] of Object.entries(parsed.paths)) {
+            if (!isOpenApiPath(endpointPath) || !pathItem || typeof pathItem !== "object" || Array.isArray(pathItem)) {
+                continue;
+            }
+            for (const [method, operation] of Object.entries(pathItem)) {
+                if (isHttpMethod(method)) {
+                    endpoints.push({
+                        method: method.toUpperCase(),
+                        path: endpointPath,
+                        searchText: openApiEndpointSearchText(endpointPath, method, operation)
+                    });
+                }
+            }
+        }
+        return endpoints;
+    }
+    catch {
+        return [];
+    }
+}
+function extractOpenApiYamlEndpointReferences(sourceText) {
+    const endpoints = [];
+    let currentPath = null;
+    let inPaths = false;
+    let pathsIndent = -1;
+    let pathIndent = -1;
+    const lines = sourceText.split(/\r?\n/);
+    for (let index = 0; index < lines.length; index += 1) {
+        const rawLine = lines[index] ?? "";
+        const line = rawLine.replace(/#.*/, "");
+        if (!line.trim()) {
+            continue;
+        }
+        const indent = line.match(/^ */)?.[0].length ?? 0;
+        const trimmed = line.trim();
+        if (/^paths\s*:\s*$/.test(trimmed)) {
+            inPaths = true;
+            pathsIndent = indent;
+            pathIndent = -1;
+            currentPath = null;
+            continue;
+        }
+        if (!inPaths) {
+            continue;
+        }
+        if (indent <= pathsIndent) {
+            inPaths = false;
+            currentPath = null;
+            continue;
+        }
+        const pathMatch = /^["']?(\/[^"':]+(?:\/[^"':]+)*)["']?\s*:\s*$/.exec(trimmed);
+        if (pathMatch?.[1]) {
+            currentPath = pathMatch[1];
+            pathIndent = indent;
+            continue;
+        }
+        const methodMatch = /^([a-zA-Z]+)\s*:\s*$/.exec(trimmed);
+        if (currentPath && indent > pathIndent && methodMatch?.[1] && isHttpMethod(methodMatch[1])) {
+            endpoints.push({
+                method: methodMatch[1].toUpperCase(),
+                path: currentPath,
+                searchText: openApiYamlEndpointSearchText(lines, index + 1, indent, currentPath, methodMatch[1])
+            });
+        }
+    }
+    return endpoints;
+}
+function extractSwaggerMarkdownEndpointReferences(sourceText) {
+    const endpoints = [];
+    const seen = new Set();
+    const endpointBlocks = sourceText.split(/\n\s*\n(?=#{1,6}\s+|##\s*)/);
+    const addressPattern = /(?:接口地址|request\s*(?:url|path)|endpoint|path)\s*(?:\*\*)?\s*[:：]\s*`?((?:\/[A-Za-z0-9._~:@!$&'()*+,;=%{}-]+)+)`?/i;
+    const methodPattern = /(?:请求方式|request\s*method|method)\s*(?:\*\*)?\s*[:：]\s*`?\b(GET|POST|PUT|PATCH|DELETE|HEAD|OPTIONS)\b`?/i;
+    for (const block of endpointBlocks) {
+        const pathMatch = addressPattern.exec(block);
+        const methodMatch = methodPattern.exec(block);
+        const endpointPath = pathMatch?.[1];
+        const method = methodMatch?.[1]?.toUpperCase();
+        if (!endpointPath || !method) {
+            continue;
+        }
+        const key = `${method} ${endpointPath}`;
+        if (seen.has(key)) {
+            continue;
+        }
+        seen.add(key);
+        endpoints.push({
+            method,
+            path: endpointPath,
+            searchText: `${method} ${endpointPath} ${block.slice(0, 2000)}`
+        });
+    }
+    return endpoints;
+}
+function openApiYamlEndpointSearchText(lines, startIndex, methodIndent, endpointPath, method) {
+    const values = [method, endpointPath];
+    let tagsIndent = -1;
+    for (let index = startIndex; index < lines.length; index += 1) {
+        const line = (lines[index] ?? "").replace(/#.*/, "");
+        if (!line.trim()) {
+            continue;
+        }
+        const indent = line.match(/^ */)?.[0].length ?? 0;
+        if (indent <= methodIndent) {
+            break;
+        }
+        const trimmed = line.trim();
+        const scalarMatch = /^(operationId|summary|description)\s*:\s*(.+?)\s*$/.exec(trimmed);
+        if (scalarMatch?.[2]) {
+            values.push(unquoteYamlScalar(scalarMatch[2]));
+            tagsIndent = -1;
+            continue;
+        }
+        const inlineTagsMatch = /^tags\s*:\s*\[(.*)\]\s*$/.exec(trimmed);
+        if (inlineTagsMatch?.[1]) {
+            values.push(...parseYamlInlineList(inlineTagsMatch[1]));
+            tagsIndent = -1;
+            continue;
+        }
+        if (/^tags\s*:\s*$/.test(trimmed)) {
+            tagsIndent = indent;
+            continue;
+        }
+        if (tagsIndent >= 0) {
+            if (indent <= tagsIndent) {
+                tagsIndent = -1;
+                continue;
+            }
+            const tagMatch = /^-\s*(.+?)\s*$/.exec(trimmed);
+            if (tagMatch?.[1]) {
+                values.push(unquoteYamlScalar(tagMatch[1]));
+            }
+        }
+    }
+    return values.join(" ");
+}
+function parseYamlInlineList(value) {
+    return value
+        .split(",")
+        .map((item) => unquoteYamlScalar(item))
+        .filter((item) => item.length > 0);
+}
+function unquoteYamlScalar(value) {
+    const trimmed = value.trim();
+    const quoted = /^(['"])(.*)\1$/.exec(trimmed);
+    return quoted?.[2] ?? trimmed;
+}
+function openApiEndpointSearchText(endpointPath, method, operation) {
+    if (!operation || typeof operation !== "object" || Array.isArray(operation)) {
+        return `${method} ${endpointPath}`;
+    }
+    const values = [method, endpointPath];
+    for (const field of ["operationId", "summary", "description"]) {
+        const value = operation[field];
+        if (typeof value === "string") {
+            values.push(value);
+        }
+    }
+    const tags = operation["tags"];
+    if (Array.isArray(tags)) {
+        values.push(...tags.filter((tag) => typeof tag === "string"));
+    }
+    return values.join(" ");
+}
+function isOpenApiPath(value) {
+    return value.startsWith("/") && value.length > 1;
+}
+function isHttpMethod(value) {
+    return /^(get|post|put|patch|delete|head|options|trace)$/i.test(value);
+}
+function selectPrdCoverageHints(projectRoot, task, inputs, cards, ingestSources) {
+    const seen = new Set();
+    const selectedHints = prdCoverageHintCards(cards)
+        .map((card) => {
+        seen.add(card.id);
+        return card;
+    });
+    const explicitPrdHints = selectExplicitPrdCoverageHintCards(projectRoot, task, inputs.prd, ingestSources, seen);
+    const cardHints = [...selectedHints, ...explicitPrdHints]
+        .slice(0, SOURCE_HINT_LIMIT)
+        .map((card) => compactPrdCoverageHint(card, inputs.prd, ingestSources));
+    if (cardHints.some((selection) => inputs.prd && selection.hint.sourcePaths.some((sourcePath) => sameSourceReference(sourcePath, inputs.prd ?? "")))) {
+        return cardHints;
+    }
+    return [
+        ...cardHints,
+        ...selectExplicitPrdSourceHints(projectRoot, task, inputs.prd, ingestSources)
+    ].slice(0, SOURCE_HINT_LIMIT);
+}
+function prdCoverageHintCards(cards) {
+    return cards
+        .filter((card) => card.coverage.length > 0 && card.sourcePaths.some(isPrdContextSource))
+        .slice(0, SOURCE_HINT_LIMIT);
+}
+function selectExplicitPrdCoverageHintCards(projectRoot, task, prd, ingestSources, excludedCardIds) {
+    if (!prd) {
+        return [];
+    }
+    const tokens = taskTokens(task);
+    const prdReferences = prdSourceReferences(prd, ingestSources);
+    return discoverKnowledgeCards(projectRoot)
+        .filter((card) => card.status === "active")
+        .filter((card) => !excludedCardIds.has(card.id))
+        .filter((card) => card.coverage.length > 0)
+        .filter((card) => card.sourcePaths.some((sourcePath) => sourceReferencesInclude(prdReferences, sourcePath)))
+        .map((card) => ({
+        card,
+        score: scoreText([
+            card.id,
+            card.title,
+            card.summary,
+            card.subject ?? "",
+            card.rule ?? "",
+            card.workflow ?? "",
+            card.permission ?? "",
+            card.term ?? "",
+            card.note ?? "",
+            card.searchable,
+            ...card.coverage,
+            ...card.prdAnchors,
+            ...card.scope,
+            ...card.tags
+        ].join(" "), tokens)
+    }))
+        .filter((item) => item.score > 0)
+        .sort((left, right) => right.score - left.score || left.card.path.localeCompare(right.card.path))
+        .slice(0, SOURCE_HINT_LIMIT)
+        .map((item) => item.card);
+}
+function prdSourceReferences(prd, ingestSources) {
+    const references = new Set([normalizeSourcePath(prd)]);
+    addMatchingIngestSourceReferences(references, ingestSources, "prd", prd);
+    return references;
+}
+function sourceReferencesInclude(references, sourcePath) {
+    for (const reference of references) {
+        if (sameSourceReference(sourcePath, reference)) {
+            return true;
+        }
+    }
+    return false;
+}
+function compactPrdCoverageHint(card, explicitPrd, ingestSources) {
+    const allSourcePaths = Array.from(new Set([
+        ...card.sourcePaths.filter((sourcePath) => explicitPrd && sameSourceReference(sourcePath, explicitPrd)),
+        ...card.sourcePaths.filter(isPrdContextSource)
+    ]));
+    const coverage = card.coverage.slice(0, SOURCE_HINT_LIMIT);
+    const anchors = card.prdAnchors.slice(0, SOURCE_HINT_LIMIT);
+    const sourcePaths = allSourcePaths.slice(0, SOURCE_HINT_LIMIT);
+    const ingest = matchingPrdIngestSource(card, explicitPrd, ingestSources);
+    return {
+        hint: {
+            cardId: card.id,
+            coverage,
+            anchors,
+            sourcePaths,
+            ...(ingest ? { ingestRef: ingest.ingestRef, artifactPath: ingest.artifactPath } : {})
+        },
+        omittedCoverage: Math.max(0, card.coverage.length - coverage.length),
+        omittedAnchors: Math.max(0, card.prdAnchors.length - anchors.length),
+        omittedSourcePaths: Math.max(0, allSourcePaths.length - SOURCE_HINT_LIMIT)
+    };
+}
+function matchingPrdIngestSource(card, explicitPrd, ingestSources) {
+    const explicitSource = explicitPrd ? normalizeSourcePath(explicitPrd) : null;
+    return ingestSources.find((record) => record.kind === "prd"
+        && (card.sourcePaths.some((sourcePath) => sameSourceReference(sourcePath, record.ingestRef))
+            || (explicitSource !== null && sameSourceReference(record.source.value, explicitSource) && card.sourcePaths.some((sourcePath) => sameSourceReference(sourcePath, explicitSource))))) ?? null;
+}
+function selectExplicitPrdSourceHints(projectRoot, task, prd, ingestSources) {
+    if (!prd || /^https?:\/\//i.test(prd)) {
+        return [];
+    }
+    const fullPath = path.join(projectRoot, prd);
+    const stat = fs.statSync(fullPath, { throwIfNoEntry: false });
+    if (!stat?.isFile() || stat.size > MAX_PRD_SOURCE_HINT_BYTES) {
+        return [];
+    }
+    const sourceText = fs.readFileSync(fullPath, "utf8");
+    const headingSelection = selectMarkdownHeadingsForTask(sourceText, task);
+    const ingest = matchingIngestSourceByValue(ingestSources, "prd", prd);
+    return [{
+            hint: {
+                cardId: null,
+                coverage: headingSelection.headings.length ? headingSelection.headings : ["explicit PRD source"],
+                anchors: [],
+                sourcePaths: [prd],
+                ...(ingest ? { ingestRef: ingest.ingestRef, artifactPath: ingest.artifactPath } : {})
+            },
+            omittedCoverage: headingSelection.omitted,
+            omittedAnchors: 0,
+            omittedSourcePaths: 0
+        }];
+}
+function selectMarkdownHeadingsForTask(sourceText, task) {
+    const headings = extractMarkdownHeadings(sourceText);
+    const tokens = taskTokens(task);
+    const scored = headings.map((heading, index) => ({
+        heading,
+        index,
+        score: scoreText(heading, tokens)
+    }));
+    const hasRelevantHeading = scored.some((item) => item.score > 0);
+    const selected = scored
+        .sort((left, right) => hasRelevantHeading
+        ? right.score - left.score || left.index - right.index
+        : left.index - right.index)
+        .slice(0, SOURCE_HINT_LIMIT)
+        .map((item) => item.heading);
+    return {
+        headings: selected,
+        omitted: Math.max(0, headings.length - selected.length)
+    };
+}
+function extractMarkdownHeadings(sourceText) {
+    const headings = [];
+    for (const rawLine of sourceText.split(/\r?\n/)) {
+        const match = /^(#{1,6})\s+(.+?)\s*#*\s*$/.exec(rawLine.trim());
+        if (!match?.[2]) {
+            continue;
+        }
+        headings.push(match[2].replace(/\s+/g, " ").trim());
+        if (headings.length >= MAX_PRD_HEADINGS_SCANNED) {
+            break;
+        }
+    }
+    return headings;
+}
+function selectUiArtifactHints(task, inputs, ingestSources, cards) {
+    const hints = [];
+    const seen = new Set();
+    if (inputs.uiSource) {
+        pushUiArtifactHint(hints, seen, {
+            kind: inputs.uiSource.kind,
+            source: inputs.uiSource.value,
+            reason: "explicit UI source input"
+        });
+    }
+    for (const source of ingestSources) {
+        if (source.kind !== "ui-package") {
+            continue;
+        }
+        pushUiArtifactHint(hints, seen, {
+            kind: "ui-package",
+            source: source.source.value,
+            ingestRef: source.ingestRef,
+            artifactPath: source.artifactPath,
+            reason: `selected ingest provenance ${source.ingestRef}`
+        });
+    }
+    const cardHints = [];
+    const cardSeen = new Set();
+    for (const card of cards) {
+        for (const sourcePath of card.sourcePaths) {
+            const kind = classifyUiArtifactSource(sourcePath);
+            if (!kind) {
+                continue;
+            }
+            pushUiArtifactHint(cardHints, cardSeen, {
+                kind,
+                source: sourcePath,
+                reason: `selected knowledge card ${card.id}`
+            });
+        }
+    }
+    const rankedCardHints = cardHints.length > remainingSourceHintBudget(hints)
+        ? rankUiArtifactHintsForTask(cardHints, task)
+        : cardHints;
+    for (const hint of rankedCardHints) {
+        pushUiArtifactHint(hints, seen, hint);
+    }
+    const selectedHints = hints.slice(0, SOURCE_HINT_LIMIT);
+    return {
+        hints: selectedHints,
+        omitted: Math.max(0, hints.length - selectedHints.length)
+    };
+}
+function rankUiArtifactHintsForTask(hints, task) {
+    const tokens = taskTokens(task);
+    const scored = hints.map((hint, index) => ({
+        hint,
+        index,
+        score: scoreText(`${hint.source} ${hint.reason}`, tokens)
+    }));
+    if (!scored.some((item) => item.score > 0)) {
+        return hints;
+    }
+    return scored
+        .sort((left, right) => right.score - left.score || left.index - right.index)
+        .map((item) => item.hint);
+}
+function selectApiImplementationHints(projectRoot, task, inputs, cards, ingestSources) {
+    const apiSources = apiImplementationSourceCandidates(inputs, cards, ingestSources);
+    if (apiSources.length === 0) {
+        return { hints: [], omitted: 0 };
+    }
+    const surface = discoverProjectSurface(projectRoot);
+    const files = scanProjectFiles(projectRoot, candidateProjectFileRoots(projectRoot, surface.sourceRoots));
+    const hints = [];
+    const hintByKey = new Map();
+    const seenKeys = new Set();
+    let totalHints = 0;
+    for (const source of apiSources) {
+        const apiTokens = [...new Set([
+                ...apiSourceTokens(source.apiSource),
+                ...apiSourceTokens(source.displaySource),
+                ...apiSourceEndpointTokens(projectRoot, source.apiSource, task)
+            ])];
+        if (apiTokens.length === 0) {
+            continue;
+        }
+        const tokens = [...new Set([...taskTokens(task), ...apiTokens])];
+        for (const item of files
+            .map((file) => ({
+            file,
+            score: scoreApiImplementationFile(file, tokens, apiTokens)
+        }))
+            .filter((candidate) => candidate.score > 0)
+            .sort((left, right) => right.score - left.score || left.file.localeCompare(right.file))) {
+            const key = `${item.file}\0${source.apiSource.replace(/\\/g, "/").toLowerCase()}`;
+            const existing = hintByKey.get(key);
+            if (existing) {
+                if (existing.apiSource.startsWith("ingest://") && !source.displaySource.startsWith("ingest://")) {
+                    existing.apiSource = source.displaySource;
+                }
+                if (!existing.reason.includes(source.reason)) {
+                    existing.reason = `${existing.reason}; ${source.reason}`;
+                }
+                if (!existing.ingestRef && source.ingestRef) {
+                    existing.ingestRef = source.ingestRef;
+                }
+                if (!existing.artifactPath && source.artifactPath) {
+                    existing.artifactPath = source.artifactPath;
+                }
+                continue;
+            }
+            if (seenKeys.has(key)) {
+                continue;
+            }
+            seenKeys.add(key);
+            totalHints += 1;
+            if (hints.length >= SOURCE_HINT_LIMIT) {
+                continue;
+            }
+            const hint = {
+                path: item.file,
+                apiSource: source.displaySource,
+                reason: source.reason,
+                ...(source.ingestRef ? { ingestRef: source.ingestRef } : {}),
+                ...(source.artifactPath ? { artifactPath: source.artifactPath } : {})
+            };
+            hintByKey.set(key, hint);
+            hints.push(hint);
+        }
+    }
+    return {
+        hints,
+        omitted: Math.max(0, totalHints - hints.length)
+    };
+}
+function apiSourceEndpointTokens(projectRoot, apiSource, task) {
+    if (/^https?:\/\//i.test(apiSource)) {
+        return [];
+    }
+    const fullPath = path.join(projectRoot, apiSource);
+    const stat = fs.statSync(fullPath, { throwIfNoEntry: false });
+    if (!stat?.isFile() || stat.size > MAX_API_SOURCE_HINT_BYTES) {
+        return [];
+    }
+    const sourceText = fs.readFileSync(fullPath, "utf8");
+    const taskTokenSet = taskTokens(task);
+    const endpoints = extractOpenApiEndpointReferences(sourceText);
+    const relevantEndpoints = endpoints.length === 1
+        ? endpoints
+        : endpoints.filter((endpoint) => scoreText(endpoint.searchText, taskTokenSet) > 0);
+    return relevantEndpoints
+        .flatMap((endpoint) => taskTokens(`${endpoint.path} ${endpoint.searchText}`))
+        .filter((token) => !["api", "get", "post", "put", "patch", "delete", "head", "options"].includes(token));
+}
+function apiImplementationSourceCandidates(inputs, cards, ingestSources) {
+    const candidates = [];
+    if (inputs.apiSource && !/^https?:\/\//i.test(inputs.apiSource)) {
+        const explicitApiIngest = matchingIngestSourceByValue(ingestSources, "openapi", inputs.apiSource);
+        candidates.push({
+            apiSource: inputs.apiSource,
+            displaySource: inputs.apiSource,
+            reason: explicitApiIngest
+                ? `matched explicit API source terms in API/client/service file path; selected ingest provenance ${explicitApiIngest.ingestRef}`
+                : "matched explicit API source terms in API/client/service file path",
+            ...(explicitApiIngest ? { ingestRef: explicitApiIngest.ingestRef, artifactPath: explicitApiIngest.artifactPath } : {})
+        });
+    }
+    for (const source of selectedApiContractSourceCandidates(cards, ingestSources)) {
+        candidates.push({
+            apiSource: source.apiSource,
+            displaySource: source.displaySource,
+            reason: "matched selected API contract source terms in API/client/service file path",
+            ...(source.ingestRef ? { ingestRef: source.ingestRef } : {}),
+            ...(source.artifactPath ? { artifactPath: source.artifactPath } : {})
+        });
+    }
+    const seen = new Set();
+    return candidates.filter((candidate) => {
+        if (seen.has(candidate.displaySource)) {
+            return false;
+        }
+        seen.add(candidate.displaySource);
+        return true;
+    });
+}
+function matchingIngestSourceByValue(ingestSources, kind, source) {
+    if (!source) {
+        return null;
+    }
+    return ingestSources.find((record) => record.kind === kind && sameSourceReference(record.source.value, source)) ?? null;
+}
+function selectedApiContractSourcePaths(cards) {
+    return [...new Set(cards
+            .filter((card) => card.type === "api_contract")
+            .flatMap((card) => card.sourcePaths)
+            .filter((sourcePath) => sourcePath && !/^https?:\/\//i.test(sourcePath))
+            .map(normalizeSourcePath))];
+}
+function selectedApiContractSourceCandidates(cards, ingestSources) {
+    const ingestByRef = new Map(ingestSources.map((record) => [ingestRefKey(record.ingestRef) ?? record.ingestRef, record]));
+    return selectedApiContractSourcePaths(cards).flatMap((sourcePath) => {
+        const refKey = ingestRefKey(sourcePath);
+        if (!refKey) {
+            return [{ apiSource: sourcePath, displaySource: sourcePath }];
+        }
+        const record = ingestByRef.get(refKey);
+        if (record?.kind !== "openapi" || record.source.type !== "project-file") {
+            return [];
+        }
+        return [{ apiSource: record.source.value, displaySource: record.ingestRef, ingestRef: record.ingestRef, artifactPath: record.artifactPath }];
+    });
+}
+function apiSourceTokens(apiSource) {
+    const basename = path.basename(apiSource, path.extname(apiSource)).replace(/[-_.]+/g, " ");
+    return taskTokens(basename)
+        .filter((token) => !["api", "openapi", "swagger", "spec", "schema", "json", "yaml", "yml"].includes(token));
+}
+function scoreApiImplementationFile(filePath, tokens, apiTokens) {
+    const normalized = filePath.toLowerCase();
+    if (!/(^|\/)(api|apis|client|clients|service|services|request|requests|http)(\/|[-_.])/i.test(normalized)) {
+        return 0;
+    }
+    const apiTokenScore = scoreText(normalized, apiTokens);
+    if (apiTokenScore === 0) {
+        return 0;
+    }
+    return apiTokenScore + scoreText(normalized, tokens);
+}
+function pushUiArtifactHint(hints, seen, hint) {
+    const sourceKey = `source\0${hint.source.replace(/\\/g, "/").toLowerCase()}`;
+    const existing = hints.find((item) => `source\0${item.source.replace(/\\/g, "/").toLowerCase()}` === sourceKey);
+    if (existing) {
+        if (hint.kind === "ui-package") {
+            existing.kind = "ui-package";
+        }
+        if (!existing.ingestRef && hint.ingestRef) {
+            existing.ingestRef = hint.ingestRef;
+        }
+        if (!existing.artifactPath && hint.artifactPath) {
+            existing.artifactPath = hint.artifactPath;
+        }
+        if (!existing.reason.includes(hint.reason)) {
+            existing.reason = `${existing.reason}; ${hint.reason}`;
+        }
+        if (hint.ingestRef) {
+            seen.add(`${hint.kind}\0${ingestRefKey(hint.ingestRef) ?? hint.ingestRef}`);
+        }
+        return;
+    }
+    const sourceKeyValue = ingestRefKey(hint.source) ?? hint.source;
+    const key = `${hint.kind}\0${sourceKeyValue}`;
+    const ingestKey = hint.ingestRef ? `${hint.kind}\0${ingestRefKey(hint.ingestRef) ?? hint.ingestRef}` : null;
+    if (seen.has(key)) {
+        return;
+    }
+    if (ingestKey && seen.has(ingestKey)) {
+        return;
+    }
+    seen.add(key);
+    seen.add(sourceKey);
+    if (ingestKey) {
+        seen.add(ingestKey);
+    }
+    hints.push(hint);
+}
+function classifyUiArtifactSource(sourcePath) {
+    const normalized = sourcePath.toLowerCase();
+    if (normalized.startsWith("ingest://ui-package/")) {
+        return "ui-package";
+    }
+    if (isDesignToolUrl(normalized)) {
+        return "design_url";
+    }
+    if (/^https?:\/\//.test(normalized)) {
+        return null;
+    }
+    const extension = path.extname(normalized);
+    if (isGeneratedMarkupExtension(extension)) {
+        return "generated_markup";
+    }
+    if (isVisualArtifactExtension(extension)) {
+        return "visual_artifact";
+    }
+    if (isDesignArtifactPath(normalized, extension)) {
+        return "design_artifact";
+    }
+    return null;
+}
+function isDesignToolUrl(value) {
+    return externalDesignReference(value) !== null;
+}
+function isDesignArtifactPath(value, extension) {
+    if (![".json", ".fig", ".sketch"].includes(extension)) {
+        return false;
+    }
+    return /(^|[\\/._-])(design|ui|mockup|wireframe|prototype|screen|screenshot|figma|pixso|mastergo|stitch)([\\/._-]|$)/i.test(value);
+}
+function isPrdContextSource(sourcePath) {
+    const normalized = sourcePath.toLowerCase();
+    return normalized.startsWith("ingest://prd/")
+        || normalized.includes("/prd/")
+        || normalized.includes("\\prd\\")
+        || normalized.endsWith("prd.md")
+        || normalized.includes("requirement");
+}
+function renderPrompt(task, inputs, workflowKind, workflowSummary, stageKinds, cards, ingestSources, projectFiles, sourceHints, limits) {
+    const sourceHintCount = sourceHints.endpoints.length
+        + sourceHints.prdCoverage.length
+        + sourceHints.uiArtifacts.length
+        + sourceHints.apiImplementations.length;
+    return [
+        `Task: ${promptField(task)}`,
+        ...(inputs.prd ? [`PRD: ${promptField(inputs.prd)}`] : []),
+        ...(inputs.apiSource ? [`API source: ${promptField(inputs.apiSource)}`] : []),
+        ...(inputs.uiSource ? [`UI source: ${inputs.uiSource.kind} ${promptField(inputs.uiSource.value)}`] : []),
+        `Workflow: ${workflowKind}`,
+        `Workflow summary: ${workflowSummary}`,
+        `Stages: ${stageKinds.join(" -> ")}`,
+        "",
+        "Relevant knowledge:",
+        ...(cards.length
+            ? cards.map((card) => `- ${promptField(card.id)}: ${promptField(card.summary)} (${promptField(card.path)})`)
+            : ["- none selected"]),
+        "",
+        "Relevant temporary-source provenance:",
+        ...(ingestSources.length
+            ? ingestSources.map((source) => `- ${promptField(source.ingestRef)}: ${promptField(source.summary)} (${promptField(source.artifactPath)})`)
+            : ["- none selected"]),
+        "",
+        "Candidate project files:",
+        ...(projectFiles.length
+            ? projectFiles.map((file) => `- ${promptField(file.path)}: ${promptField(file.reason)}`)
+            : ["- none selected"]),
+        "",
+        "Selected source hints:",
+        ...(sourceHints.endpoints.length
+            ? sourceHints.endpoints.map((hint) => `- endpoint ${hint.method} ${promptField(hint.path)} from ${promptField(hint.cardId ?? hint.source)}`)
+            : []),
+        ...(sourceHints.prdCoverage.length
+            ? sourceHints.prdCoverage.map((hint) => `- PRD coverage ${promptField(hint.coverage.join("; "))} from ${promptField(hint.cardId ?? hint.sourcePaths[0] ?? "explicit PRD input")}`)
+            : []),
+        ...(sourceHints.uiArtifacts.length
+            ? sourceHints.uiArtifacts.map(renderUiArtifactPromptLine)
+            : []),
+        ...(sourceHints.apiImplementations.length
+            ? sourceHints.apiImplementations.map((hint) => `- API implementation ${promptField(hint.path)} for ${promptField(hint.apiSource)}: ${promptField(hint.reason)}`)
+            : []),
+        ...(sourceHints.endpoints.length || sourceHints.prdCoverage.length || sourceHints.uiArtifacts.length || sourceHints.apiImplementations.length
+            ? []
+            : ["- none selected"]),
+        "",
+        "Context budget:",
+        `- knowledge ${cards.length}/${limits.selectedKnowledge}; omitted ${limits.omittedSelectedKnowledge}; omitted fields sourcePaths=${limits.omittedSelectedKnowledgeSourcePaths}, coverage=${limits.omittedSelectedKnowledgeCoverage}, verification=${limits.omittedSelectedKnowledgeVerification}`,
+        `- ingest ${ingestSources.length}/${limits.selectedIngestSources}; omitted ${limits.omittedSelectedIngestSources}; omitted producedCardIds=${limits.omittedSelectedIngestProducedKnowledgeCardIds}`,
+        `- project files ${projectFiles.length}/${limits.selectedProjectFiles}; omitted ${limits.omittedSelectedProjectFiles}; scanned ${limits.totalScannedProjectFiles}/${limits.scannedProjectFiles}; scanLimitReached=${limits.projectFileScanLimitReached}`,
+        `- source hints ${sourceHintCount}/${limits.sourceHints}; omitted ${limits.omittedSourceHints}; omittedPrdCoverage coverage=${limits.omittedPrdCoverageHintCoverage}, anchors=${limits.omittedPrdCoverageHintAnchors}, sourcePaths=${limits.omittedPrdCoverageHintSourcePaths}; skippedPrdSources=${limits.skippedPrdSourceHintSources}; skippedApiSources=${limits.skippedApiSourceHintSources}`,
+        "",
+        "Use the selected knowledge as durable project context. Treat ingest records as provenance for already-distilled temporary inputs, not as instructions to re-fetch or paste full source material."
+    ].join("\n");
+}
+function renderUiArtifactPromptLine(hint) {
+    const prefix = `- UI ${hint.kind} ${promptField(hint.source)}`;
+    return hint.ingestRef
+        ? prefix
+        : `${prefix}: ${promptField(hint.reason)}`;
+}
+function promptField(value) {
+    const normalized = value.replace(/\s+/g, " ").trim();
+    return normalized.length > MAX_PROMPT_FIELD_CHARS
+        ? `${normalized.slice(0, MAX_PROMPT_FIELD_CHARS - 3)}...`
+        : normalized;
+}
+function scoreKnowledgeCard(card, tokens, sourceReferences) {
+    const text = [
+        card.id,
+        card.title,
+        card.summary,
+        card.subject ?? "",
+        card.kind ?? "",
+        card.rule ?? "",
+        card.workflow ?? "",
+        card.permission ?? "",
+        card.term ?? "",
+        card.note ?? "",
+        ...card.scope,
+        ...card.tags,
+        ...card.sourcePaths
+    ].join(" ");
+    const baseScore = scoreText(text, tokens);
+    const sourcePaths = card.sourcePaths.map(normalizeSourcePath);
+    const prdBoost = sourcePathBoost(sourcePaths, sourceReferences.prd);
+    const apiBoost = sourcePathBoost(sourcePaths, sourceReferences.api);
+    const uiBoost = sourcePathBoost(sourcePaths, sourceReferences.ui);
+    return baseScore + prdBoost + apiBoost + uiBoost;
+}
+function sourcePathBoost(sourcePaths, references) {
+    return sourcePaths.some((sourcePath) => sourceReferencesInclude(references, sourcePath)) ? 3 : 0;
+}
+function scoreText(text, tokens) {
+    const normalized = text.toLowerCase();
+    const compact = normalized.replace(/[\\/._-]+/g, "");
+    return tokens.reduce((score, token) => score + (normalized.includes(token) || compact.includes(token) ? 1 : 0), 0);
+}
+function taskTokens(task) {
+    const normalized = task.toLowerCase();
+    const latin = (normalized.match(/[a-z0-9][a-z0-9_-]{1,}/g) ?? [])
+        .flatMap((token) => {
+        const rawParts = token.split(/[-_]+/).filter((part) => part.length > 1);
+        const parts = rawParts.filter((part) => !SEPARATED_TOKEN_STOP_WORDS.has(part));
+        const compact = rawParts.length > 1 ? rawParts.join("") : "";
+        return [token, compact, ...parts].filter(Boolean);
+    });
+    const chinese = normalized.match(/[\u4e00-\u9fff]{2,}/g) ?? [];
+    return [...new Set([...latin, ...chinese])].slice(0, 40);
+}
+function normalizeLimit(value) {
+    if (value === undefined) {
+        return DEFAULT_CONTEXT_CARD_LIMIT;
+    }
+    if (!Number.isInteger(value) || value < 1 || value > MAX_CONTEXT_CARD_LIMIT) {
+        throw new Error(`context task --limit must be an integer from 1 to ${MAX_CONTEXT_CARD_LIMIT}`);
+    }
+    return value;
+}
+function normalizeTaskPrdReference(projectRoot, source) {
+    return normalizeTaskProjectFileReference(projectRoot, source, "PRD");
+}
+function normalizeTaskApiSourceReference(projectRoot, source) {
+    const value = source.trim();
+    if (!value) {
+        throw new Error("context task --api-source cannot be empty");
+    }
+    if (/^https?:\/\//i.test(value)) {
+        return value;
+    }
+    return normalizeTaskProjectFileReference(projectRoot, value, "API source");
+}
+function normalizeTaskUiSourceReference(projectRoot, source) {
+    const value = source.trim();
+    if (!value) {
+        throw new Error("context task --ui-source cannot be empty");
+    }
+    if (/^https?:\/\//i.test(value)) {
+        const designUrl = externalDesignReference(value);
+        if (designUrl) {
+            return designUrl;
+        }
+        throw new Error(unsupportedDesignSourceUrlMessage("UI source"));
+    }
+    const normalized = normalizeTaskProjectFileReference(projectRoot, value, "UI source");
+    return {
+        kind: inferLocalUiSourceKind(normalized),
+        value: normalized
+    };
+}
+function normalizeTaskProjectFileReference(projectRoot, source, label) {
+    const { relativePath, fullPath } = resolveProjectRelativePath(projectRoot, source, `${label} file`);
+    if (!isRegularFileWithoutSymlink(fullPath)) {
+        throw new Error(`${label} file cannot be read: ${source}`);
+    }
+    return relativePath;
+}
+function normalizeSourcePath(value) {
+    return value.replace(/\\/g, "/");
+}
+function ingestRefKey(value) {
+    const normalized = normalizeSourcePath(value);
+    return normalized.toLowerCase().startsWith("ingest://") ? normalized.toLowerCase() : null;
+}
+//# sourceMappingURL=task-context.js.map