frontend-harness 0.1.0

package/dist/runtime/context.js

@@ -0,0 +1,153 @@
+import fs from "node:fs";
+import path from "node:path";
+import { createHash } from "node:crypto";
+import { harnessPath, relativeHarnessPath } from "../storage/paths.js";
+import { writeJson } from "../storage/json.js";
+import { discoverVerificationCommands } from "./verification-commands.js";
+import { detectProjectStack, discoverProjectSurface } from "./project-discovery.js";
+import { discoverSkills } from "./skills.js";
+import { discoverKnowledgeCards } from "./knowledge.js";
+import { checkComponentGraph } from "./graph.js";
+import { checkExecutionUnits } from "./units.js";
+import { loadState } from "./state.js";
+import { readAcceptedRepairDecision } from "./repair-decision.js";
+import { checkProtocol } from "./protocol-init.js";
+import { publicRecommendedCommands } from "./command-taxonomy.js";
+import { buildPolicyProvenance } from "./policy-provenance.js";
+export function buildContext(projectRoot) {
+    const projectSurface = discoverProjectSurface(projectRoot);
+    const knownArtifacts = {
+        latestContext: relativeHarnessPath("context", "latest.json"),
+        latestPlan: relativeHarnessPath("plans", "latest.json"),
+        latestExecutionUnits: relativeHarnessPath("execution-units", "latest.json"),
+        latestComponentGraph: relativeHarnessPath("component-graph", "latest.json"),
+        latestConfig: relativeHarnessPath("config.json"),
+        latestVerification: relativeHarnessPath("verification", "latest.json"),
+        latestStateExplain: relativeHarnessPath("state-explain", "latest.json"),
+        latestRepairPacket: relativeHarnessPath("repair", "latest.json"),
+        latestRepairDecision: relativeHarnessPath("repair-decision", "latest.json"),
+        latestProtocol: relativeHarnessPath("protocol", "latest.json")
+    };
+    const state = loadState(projectRoot);
+    const context = {
+        projectRoot,
+        detectedStack: detectProjectStack(projectRoot),
+        constraints: collectConstraints(projectRoot),
+        knownArtifacts,
+        projectSurface,
+        projectStatus: buildProjectStatus(projectRoot, knownArtifacts, projectSurface, state),
+        lastPlannedPolicyProvenance: buildPolicyProvenance(projectRoot, state.task?.scope ?? ""),
+        recommendedNextCommands: publicRecommendedCommands()
+    };
+    writeJson(harnessPath(projectRoot, "context", "latest.json"), context);
+    return context;
+}
+function collectConstraints(projectRoot) {
+    const constraints = [];
+    for (const file of ["AGENTS.md", "CLAUDE.md", "docs/DIRECTION.md"]) {
+        if (fs.existsSync(path.join(projectRoot, file))) {
+            constraints.push(file);
+        }
+    }
+    return constraints;
+}
+function buildProjectStatus(projectRoot, knownArtifacts, surface, state) {
+    const verificationCommands = discoverVerificationCommands(projectRoot);
+    const knowledge = discoverKnowledge(projectRoot);
+    const skills = discoverSkills(projectRoot);
+    const executionUnits = checkExecutionUnits(projectRoot);
+    const componentGraph = checkComponentGraph(projectRoot);
+    const protocol = checkProtocol(projectRoot);
+    return {
+        artifacts: Object.fromEntries(Object.entries(knownArtifacts).map(([name, relativePath]) => [
+            name,
+            describeArtifact(projectRoot, relativePath)
+        ])),
+        surface,
+        verificationCommands,
+        knowledge,
+        skills,
+        executionUnits,
+        componentGraph,
+        protocol,
+        stateSummary: summarizeState(state),
+        planReadiness: buildPlanReadiness({
+            protocol,
+            skills,
+            knowledge,
+            verificationCommands,
+            surface
+        }),
+        planningDecision: summarizePlanningDecision(state.task),
+        repairDecision: readAcceptedRepairDecision(projectRoot)
+    };
+}
+function summarizeState(state) {
+    return {
+        status: state.status,
+        verificationStatus: state.verification.status,
+        hasTask: Boolean(state.task),
+        taskScope: state.task?.scope ?? null,
+        changedFilesCount: state.changedFiles.length,
+        retryCount: state.retryCount,
+        blockerCount: state.blockers.length
+    };
+}
+function buildPlanReadiness(input) {
+    const protocolReady = input.protocol.status === "passed";
+    const skillsAvailable = input.skills.length > 0;
+    const knowledgeAvailable = input.knowledge.length > 0;
+    const verificationConfigured = input.verificationCommands.some((command) => command.command);
+    const surfaceDetected = input.surface.sourceRoots.length > 0 || input.surface.entryFiles.length > 0;
+    const warnings = [
+        ...(!protocolReady ? ["Protocol is not current; run frontend-harness init --json before relying on injected instructions."] : []),
+        ...(!skillsAvailable ? ["No project-local skills were discovered under .frontend-harness/skills."] : []),
+        ...(!knowledgeAvailable ? ["No project knowledge artifacts were discovered under .frontend-harness/knowledge."] : []),
+        ...(!verificationConfigured ? ["No verification commands are configured from flags, harness config, or package scripts."] : []),
+        ...(!surfaceDetected ? ["No source roots or entry files were detected from the standard frontend project surface."] : [])
+    ];
+    return {
+        status: protocolReady && verificationConfigured ? warnings.length > 0 ? "warning" : "ready" : "blocked",
+        protocolReady,
+        skillsAvailable,
+        knowledgeAvailable,
+        verificationConfigured,
+        surfaceDetected,
+        warnings
+    };
+}
+function summarizePlanningDecision(task) {
+    const decision = task?.agentDecision;
+    if (!decision?.artifactPath) {
+        return null;
+    }
+    return {
+        artifactPath: decision.artifactPath,
+        contractVersion: decision.contractVersion ?? null,
+        intentSuggestion: decision.intentSuggestion ?? null,
+        constraintHints: decision.constraintHints ?? [],
+        componentHints: decision.componentHints ?? []
+    };
+}
+function describeArtifact(projectRoot, relativePath) {
+    const fullPath = path.join(projectRoot, relativePath);
+    if (!fs.existsSync(fullPath)) {
+        return {
+            path: relativePath,
+            exists: false,
+            updatedAt: null,
+            sha256: null
+        };
+    }
+    const stat = fs.statSync(fullPath);
+    return {
+        path: relativePath,
+        exists: true,
+        updatedAt: stat.mtime.toISOString(),
+        sha256: createHash("sha256").update(fs.readFileSync(fullPath)).digest("hex")
+    };
+}
+function discoverKnowledge(projectRoot) {
+    return discoverKnowledgeCards(projectRoot).map(({ searchable, ...card }) => card);
+}
+//# sourceMappingURL=context.js.map

package/dist/runtime/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../../src/runtime/context.ts"],"names":[],"mappings":"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"}

package/dist/runtime/graph.d.ts

@@ -0,0 +1,12 @@
+import type { ComponentGraphArtifact, ComponentItem, ExecutionUnit } from "../schemas/types.js";
+export type GraphCheckStatus = "passed" | "failed" | "not_configured";
+export interface GraphCheckResult {
+    status: GraphCheckStatus;
+    artifactPath: string;
+    nodeCount: number;
+    edgeCount: number;
+    errors: string[];
+    warnings: string[];
+}
+export declare function buildComponentGraph(components: ComponentItem[], units: ExecutionUnit[]): ComponentGraphArtifact;
+export declare function checkComponentGraph(projectRoot: string): GraphCheckResult;

package/dist/runtime/graph.js

@@ -0,0 +1,211 @@
+import fs from "node:fs";
+import path from "node:path";
+import { relativeHarnessPath } from "../storage/paths.js";
+const allowedEdgeTypes = new Set(["depends_on"]);
+const allowedEdgeSources = new Set(["execution_unit_depends_on"]);
+export function buildComponentGraph(components, units) {
+    const nodes = components.map((component, index) => {
+        const unit = units[index];
+        if (!unit) {
+            throw new Error(`Cannot build component graph: missing execution unit for component ${component.name}.`);
+        }
+        return {
+            id: graphNodeIdFromComponent(component.name),
+            component: component.name,
+            file: component.file,
+            executionUnitId: unit.id
+        };
+    });
+    const nodeByUnitId = new Map(nodes.map((node) => [node.executionUnitId, node]));
+    const edges = [];
+    for (const unit of units) {
+        const fromNode = nodeByUnitId.get(unit.id);
+        if (!fromNode) {
+            continue;
+        }
+        for (const dependency of unit.dependsOn) {
+            const toNode = nodeByUnitId.get(dependency);
+            if (!toNode) {
+                continue;
+            }
+            edges.push({
+                from: fromNode.id,
+                to: toNode.id,
+                type: "depends_on",
+                source: "execution_unit_depends_on"
+            });
+        }
+    }
+    return {
+        nodes,
+        edges
+    };
+}
+export function checkComponentGraph(projectRoot) {
+    const artifactPath = relativeHarnessPath("component-graph", "latest.json");
+    const fullPath = path.join(projectRoot, artifactPath);
+    if (!fs.existsSync(fullPath)) {
+        return {
+            status: "not_configured",
+            artifactPath,
+            nodeCount: 0,
+            edgeCount: 0,
+            errors: [],
+            warnings: ["Run frontend-harness plan before checking the component graph."]
+        };
+    }
+    const errors = [];
+    const warnings = [];
+    const artifact = readArtifact(fullPath, errors);
+    const nodes = getArray(artifact, "nodes", errors);
+    const edges = getArray(artifact, "edges", errors);
+    const nodeIds = new Set();
+    const duplicateNodeIds = new Set();
+    for (const [index, node] of nodes.entries()) {
+        if (!isRecord(node)) {
+            errors.push(`nodes[${index}] must be an object.`);
+            continue;
+        }
+        const id = validateNodeId(node, index, errors);
+        if (id) {
+            if (nodeIds.has(id)) {
+                duplicateNodeIds.add(id);
+            }
+            nodeIds.add(id);
+        }
+    }
+    for (const duplicateId of duplicateNodeIds) {
+        errors.push(`Duplicate component graph node id: ${duplicateId}.`);
+    }
+    for (const [index, node] of nodes.entries()) {
+        if (isRecord(node)) {
+            validateNode(node, index, errors);
+        }
+    }
+    validateEdges(edges, nodeIds, errors);
+    return {
+        status: errors.length > 0 ? "failed" : "passed",
+        artifactPath,
+        nodeCount: nodes.length,
+        edgeCount: edges.length,
+        errors,
+        warnings
+    };
+}
+function graphNodeIdFromComponent(name) {
+    return `component-${name.replace(/([a-z])([A-Z])/g, "$1-$2").toLowerCase()}`;
+}
+function readArtifact(fullPath, errors) {
+    try {
+        return JSON.parse(fs.readFileSync(fullPath, "utf8"));
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        errors.push(`Component graph artifact is not valid JSON: ${message}`);
+        return null;
+    }
+}
+function getArray(artifact, key, errors) {
+    if (!isRecord(artifact)) {
+        errors.push("Component graph artifact root must be an object.");
+        return [];
+    }
+    if (!Array.isArray(artifact[key])) {
+        errors.push(`Component graph artifact must contain a ${key} array.`);
+        return [];
+    }
+    return artifact[key];
+}
+function validateNodeId(node, index, errors) {
+    if (typeof node.id !== "string" || !node.id.trim()) {
+        errors.push(`nodes[${index}].id must be a non-empty string.`);
+        return null;
+    }
+    return node.id;
+}
+function validateNode(node, index, errors) {
+    if (typeof node.component !== "string" || !node.component.trim()) {
+        errors.push(`nodes[${index}].component must be a non-empty string.`);
+    }
+    if (typeof node.executionUnitId !== "string" || !node.executionUnitId.trim()) {
+        errors.push(`nodes[${index}].executionUnitId must be a non-empty string.`);
+    }
+    if (typeof node.file !== "string" || !node.file.trim()) {
+        errors.push(`nodes[${index}].file must be a non-empty project-relative path.`);
+        return;
+    }
+    if (!isProjectRelativeSourcePath(node.file)) {
+        errors.push(`nodes[${index}].file must be project-relative and outside generated harness directories.`);
+    }
+}
+function validateEdges(edges, nodeIds, errors) {
+    const edgeKeys = new Set();
+    const duplicateEdgeKeys = new Set();
+    for (const [index, edge] of edges.entries()) {
+        if (!isRecord(edge)) {
+            errors.push(`edges[${index}] must be an object.`);
+            continue;
+        }
+        validateEdge(edge, index, nodeIds, errors);
+        const edgeKey = edgeKeyFromUnknown(edge);
+        if (edgeKey) {
+            if (edgeKeys.has(edgeKey)) {
+                duplicateEdgeKeys.add(edgeKey);
+            }
+            edgeKeys.add(edgeKey);
+        }
+    }
+    for (const duplicateEdgeKey of duplicateEdgeKeys) {
+        errors.push(`Duplicate component graph edge: ${duplicateEdgeKey}.`);
+    }
+}
+function validateEdge(edge, index, nodeIds, errors) {
+    const from = validateEndpoint(edge.from, `edges[${index}].from`, nodeIds, errors);
+    const to = validateEndpoint(edge.to, `edges[${index}].to`, nodeIds, errors);
+    if (from && to && from === to) {
+        errors.push(`edges[${index}] cannot reference the same node.`);
+    }
+    if (typeof edge.type !== "string" || !allowedEdgeTypes.has(edge.type)) {
+        errors.push(`edges[${index}].type must be one of: ${Array.from(allowedEdgeTypes).join(", ")}.`);
+    }
+    if (typeof edge.source !== "string" || !allowedEdgeSources.has(edge.source)) {
+        errors.push(`edges[${index}].source must be one of: ${Array.from(allowedEdgeSources).join(", ")}.`);
+    }
+}
+function validateEndpoint(value, label, nodeIds, errors) {
+    if (typeof value !== "string" || !value.trim()) {
+        errors.push(`${label} must be a non-empty node id.`);
+        return null;
+    }
+    if (!nodeIds.has(value)) {
+        errors.push(`${label} references unknown node id: ${value}.`);
+    }
+    return value;
+}
+function edgeKeyFromUnknown(edge) {
+    if (typeof edge.from !== "string" ||
+        typeof edge.to !== "string" ||
+        typeof edge.type !== "string" ||
+        typeof edge.source !== "string") {
+        return null;
+    }
+    return `${edge.from}->${edge.to}:${edge.type}:${edge.source}`;
+}
+function isProjectRelativeSourcePath(file) {
+    if (path.isAbsolute(file) || file.startsWith("/")) {
+        return false;
+    }
+    const normalized = path.posix.normalize(file.replace(/\\/g, "/"));
+    if (!normalized || normalized === "." || normalized === ".." || normalized.startsWith("../")) {
+        return false;
+    }
+    if (normalized.startsWith("/") || /^[a-zA-Z]:\//.test(normalized)) {
+        return false;
+    }
+    const firstSegment = normalized.split("/")[0];
+    return firstSegment !== ".frontend-harness" && firstSegment !== ".omx";
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}
+//# sourceMappingURL=graph.js.map

package/dist/runtime/graph.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph.js","sourceRoot":"","sources":["../../src/runtime/graph.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAQ7B,OAAO,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AA2B1D,MAAM,gBAAgB,GAAG,IAAI,GAAG,CAA6B,CAAC,YAAY,CAAC,CAAC,CAAC;AAC7E,MAAM,kBAAkB,GAAG,IAAI,GAAG,CAA+B,CAAC,2BAA2B,CAAC,CAAC,CAAC;AAEhG,MAAM,UAAU,mBAAmB,CAAC,UAA2B,EAAE,KAAsB;IACrF,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,CAAC,CAAC,SAAS,EAAE,KAAK,EAAsB,EAAE;QACpE,MAAM,IAAI,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC;QAC1B,IAAI,CAAC,IAAI,EAAE,CAAC;YACV,MAAM,IAAI,KAAK,CAAC,sEAAsE,SAAS,CAAC,IAAI,GAAG,CAAC,CAAC;QAC3G,CAAC;QACD,OAAO;YACL,EAAE,EAAE,wBAAwB,CAAC,SAAS,CAAC,IAAI,CAAC;YAC5C,SAAS,EAAE,SAAS,CAAC,IAAI;YACzB,IAAI,EAAE,SAAS,CAAC,IAAI;YACpB,eAAe,EAAE,IAAI,CAAC,EAAE;SACzB,CAAC;IACJ,CAAC,CAAC,CAAC;IACH,MAAM,YAAY,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,eAAe,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC;IAChF,MAAM,KAAK,GAAyB,EAAE,CAAC;IAEvC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,QAAQ,GAAG,YAAY,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QAC3C,IAAI,CAAC,QAAQ,EAAE,CAAC;YACd,SAAS;QACX,CAAC;QACD,KAAK,MAAM,UAAU,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;YACxC,MAAM,MAAM,GAAG,YAAY,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;YAC5C,IAAI,CAAC,MAAM,EAAE,CAAC;gBACZ,SAAS;YACX,CAAC;YACD,KAAK,CAAC,IAAI,CAAC;gBACT,IAAI,EAAE,QAAQ,CAAC,EAAE;gBACjB,EAAE,EAAE,MAAM,CAAC,EAAE;gBACb,IAAI,EAAE,YAAY;gBAClB,MAAM,EAAE,2BAA2B;aACpC,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAED,OAAO;QACL,KAAK;QACL,KAAK;KACN,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,mBAAmB,CAAC,WAAmB;IACrD,MAAM,YAAY,GAAG,mBAAmB,CAAC,iBAAiB,EAAE,aAAa,CAAC,CAAC;IAC3E,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,YAAY,CAAC,CAAC;IACtD,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC7B,OAAO;YACL,MAAM,EAAE,gBAAgB;YACxB,YAAY;YACZ,SAAS,EAAE,CAAC;YACZ,SAAS,EAAE,CAAC;YACZ,MAAM,EAAE,EAAE;YACV,QAAQ,EAAE,CAAC,gEAAgE,CAAC;SAC7E,CAAC;IACJ,CAAC;IAED,MAAM,MAAM,GAAa,EAAE,CAAC;IAC5B,MAAM,QAAQ,GAAa,EAAE,CAAC;IAC9B,MAAM,QAAQ,GAAG,YAAY,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;IAChD,MAAM,KAAK,GAAG,QAAQ,CAAC,QAAQ,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;IAClD,MAAM,KAAK,GAAG,QAAQ,CAAC,QAAQ,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;IAClD,MAAM,OAAO,GAAG,IAAI,GAAG,EAAU,CAAC;IAClC,MAAM,gBAAgB,GAAG,IAAI,GAAG,EAAU,CAAC;IAE3C,KAAK,MAAM,CAAC,KAAK,EAAE,IAAI,CAAC,IAAI,KAAK,CAAC,OAAO,EAAE,EAAE,CAAC;QAC5C,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;YACpB,MAAM,CAAC,IAAI,CAAC,SAAS,KAAK,sBAAsB,CAAC,CAAC;YAClD,SAAS;QACX,CAAC;QACD,MAAM,EAAE,GAAG,cAAc,CAAC,IAAI,EAAE,KAAK,EAAE,MAAM,CAAC,CAAC;QAC/C,IAAI,EAAE,EAAE,CAAC;YACP,IAAI,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,CAAC;gBACpB,gBAAgB,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;YAC3B,CAAC;YACD,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAClB,CAAC;IACH,CAAC;IAED,KAAK,MAAM,WAAW,IAAI,gBAAgB,EAAE,CAAC;QAC3C,MAAM,CAAC,IAAI,CAAC,sCAAsC,WAAW,GAAG,CAAC,CAAC;IACpE,CAAC;IAED,KAAK,MAAM,CAAC,KAAK,EAAE,IAAI,CAAC,IAAI,KAAK,CAAC,OAAO,EAAE,EAAE,CAAC;QAC5C,IAAI,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;YACnB,YAAY,CAAC,IAAI,EAAE,KAAK,EAAE,MAAM,CAAC,CAAC;QACpC,CAAC;IACH,CAAC;IAED,aAAa,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;IAEtC,OAAO;QACL,MAAM,EAAE,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,QAAQ;QAC/C,YAAY;QACZ,SAAS,EAAE,KAAK,CAAC,MAAM;QACvB,SAAS,EAAE,KAAK,CAAC,MAAM;QACvB,MAAM;QACN,QAAQ;KACT,CAAC;AACJ,CAAC;AAED,SAAS,wBAAwB,CAAC,IAAY;IAC5C,OAAO,aAAa,IAAI,CAAC,OAAO,CAAC,iBAAiB,EAAE,OAAO,CAAC,CAAC,WAAW,EAAE,EAAE,CAAC;AAC/E,CAAC;AAED,SAAS,YAAY,CAAC,QAAgB,EAAE,MAAgB;IACtD,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,YAAY,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAY,CAAC;IAClE,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACvE,MAAM,CAAC,IAAI,CAAC,+CAA+C,OAAO,EAAE,CAAC,CAAC;QACtE,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,SAAS,QAAQ,CAAC,QAAiB,EAAE,GAAsB,EAAE,MAAgB;IAC3E,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC;QACxB,MAAM,CAAC,IAAI,CAAC,kDAAkD,CAAC,CAAC;QAChE,OAAO,EAAE,CAAC;IACZ,CAAC;IACD,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC;QAClC,MAAM,CAAC,IAAI,CAAC,2CAA2C,GAAG,SAAS,CAAC,CAAC;QACrE,OAAO,EAAE,CAAC;IACZ,CAAC;IACD,OAAO,QAAQ,CAAC,GAAG,CAAC,CAAC;AACvB,CAAC;AAED,SAAS,cAAc,CAAC,IAAiB,EAAE,KAAa,EAAE,MAAgB;IACxE,IAAI,OAAO,IAAI,CAAC,EAAE,KAAK,QAAQ,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC;QACnD,MAAM,CAAC,IAAI,CAAC,SAAS,KAAK,kCAAkC,CAAC,CAAC;QAC9D,OAAO,IAAI,CAAC;IACd,CAAC;IACD,OAAO,IAAI,CAAC,EAAE,CAAC;AACjB,CAAC;AAED,SAAS,YAAY,CAAC,IAAiB,EAAE,KAAa,EAAE,MAAgB;IACtE,IAAI,OAAO,IAAI,CAAC,SAAS,KAAK,QAAQ,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,EAAE,CAAC;QACjE,MAAM,CAAC,IAAI,CAAC,SAAS,KAAK,yCAAyC,CAAC,CAAC;IACvE,CAAC;IACD,IAAI,OAAO,IAAI,CAAC,eAAe,KAAK,QAAQ,IAAI,CAAC,IAAI,CAAC,eAAe,CAAC,IAAI,EAAE,EAAE,CAAC;QAC7E,MAAM,CAAC,IAAI,CAAC,SAAS,KAAK,+CAA+C,CAAC,CAAC;IAC7E,CAAC;IACD,IAAI,OAAO,IAAI,CAAC,IAAI,KAAK,QAAQ,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,EAAE,CAAC;QACvD,MAAM,CAAC,IAAI,CAAC,SAAS,KAAK,mDAAmD,CAAC,CAAC;QAC/E,OAAO;IACT,CAAC;IACD,IAAI,CAAC,2BAA2B,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QAC5C,MAAM,CAAC,IAAI,CAAC,SAAS,KAAK,4EAA4E,CAAC,CAAC;IAC1G,CAAC;AACH,CAAC;AAED,SAAS,aAAa,CAAC,KAAgB,EAAE,OAAoB,EAAE,MAAgB;IAC7E,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAU,CAAC;IACnC,MAAM,iBAAiB,GAAG,IAAI,GAAG,EAAU,CAAC;IAE5C,KAAK,MAAM,CAAC,KAAK,EAAE,IAAI,CAAC,IAAI,KAAK,CAAC,OAAO,EAAE,EAAE,CAAC;QAC5C,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;YACpB,MAAM,CAAC,IAAI,CAAC,SAAS,KAAK,sBAAsB,CAAC,CAAC;YAClD,SAAS;QACX,CAAC;QACD,YAAY,CAAC,IAAI,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;QAC3C,MAAM,OAAO,GAAG,kBAAkB,CAAC,IAAI,CAAC,CAAC;QACzC,IAAI,OAAO,EAAE,CAAC;YACZ,IAAI,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC;gBAC1B,iBAAiB,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;YACjC,CAAC;YACD,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QACxB,CAAC;IACH,CAAC;IAED,KAAK,MAAM,gBAAgB,IAAI,iBAAiB,EAAE,CAAC;QACjD,MAAM,CAAC,IAAI,CAAC,mCAAmC,gBAAgB,GAAG,CAAC,CAAC;IACtE,CAAC;AACH,CAAC;AAED,SAAS,YAAY,CAAC,IAAiB,EAAE,KAAa,EAAE,OAAoB,EAAE,MAAgB;IAC5F,MAAM,IAAI,GAAG,gBAAgB,CAAC,IAAI,CAAC,IAAI,EAAE,SAAS,KAAK,QAAQ,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;IAClF,MAAM,EAAE,GAAG,gBAAgB,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,KAAK,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;IAC5E,IAAI,IAAI,IAAI,EAAE,IAAI,IAAI,KAAK,EAAE,EAAE,CAAC;QAC9B,MAAM,CAAC,IAAI,CAAC,SAAS,KAAK,mCAAmC,CAAC,CAAC;IACjE,CAAC;IACD,IAAI,OAAO,IAAI,CAAC,IAAI,KAAK,QAAQ,IAAI,CAAC,gBAAgB,CAAC,GAAG,CAAC,IAAI,CAAC,IAAkC,CAAC,EAAE,CAAC;QACpG,MAAM,CAAC,IAAI,CAAC,SAAS,KAAK,0BAA0B,KAAK,CAAC,IAAI,CAAC,gBAAgB,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAClG,CAAC;IACD,IAAI,OAAO,IAAI,CAAC,MAAM,KAAK,QAAQ,IAAI,CAAC,kBAAkB,CAAC,GAAG,CAAC,IAAI,CAAC,MAAsC,CAAC,EAAE,CAAC;QAC5G,MAAM,CAAC,IAAI,CAAC,SAAS,KAAK,4BAA4B,KAAK,CAAC,IAAI,CAAC,kBAAkB,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACtG,CAAC;AACH,CAAC;AAED,SAAS,gBAAgB,CAAC,KAAc,EAAE,KAAa,EAAE,OAAoB,EAAE,MAAgB;IAC7F,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,EAAE,CAAC;QAC/C,MAAM,CAAC,IAAI,CAAC,GAAG,KAAK,+BAA+B,CAAC,CAAC;QACrD,OAAO,IAAI,CAAC;IACd,CAAC;IACD,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC;QACxB,MAAM,CAAC,IAAI,CAAC,GAAG,KAAK,gCAAgC,KAAK,GAAG,CAAC,CAAC;IAChE,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,SAAS,kBAAkB,CAAC,IAAiB;IAC3C,IACE,OAAO,IAAI,CAAC,IAAI,KAAK,QAAQ;QAC7B,OAAO,IAAI,CAAC,EAAE,KAAK,QAAQ;QAC3B,OAAO,IAAI,CAAC,IAAI,KAAK,QAAQ;QAC7B,OAAO,IAAI,CAAC,MAAM,KAAK,QAAQ,EAC/B,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IACD,OAAO,GAAG,IAAI,CAAC,IAAI,KAAK,IAAI,CAAC,EAAE,IAAI,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;AAChE,CAAC;AAED,SAAS,2BAA2B,CAAC,IAAY;IAC/C,IAAI,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;QAClD,OAAO,KAAK,CAAC;IACf,CAAC;IACD,MAAM,UAAU,GAAG,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,CAAC;IAClE,IAAI,CAAC,UAAU,IAAI,UAAU,KAAK,GAAG,IAAI,UAAU,KAAK,IAAI,IAAI,UAAU,CAAC,UAAU,CAAC,KAAK,CAAC,EAAE,CAAC;QAC7F,OAAO,KAAK,CAAC;IACf,CAAC;IACD,IAAI,UAAU,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,cAAc,CAAC,IAAI,CAAC,UAAU,CAAC,EAAE,CAAC;QAClE,OAAO,KAAK,CAAC;IACf,CAAC;IACD,MAAM,YAAY,GAAG,UAAU,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;IAC9C,OAAO,YAAY,KAAK,mBAAmB,IAAI,YAAY,KAAK,MAAM,CAAC;AACzE,CAAC;AAED,SAAS,QAAQ,CAAC,KAAc;IAC9B,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,CAAC;AACrD,CAAC"}

package/dist/runtime/knowledge.d.ts

@@ -0,0 +1,48 @@
+export type KnowledgeType = "prd_semantics" | "project_convention" | "decision_record" | "pitfall" | "glossary";
+export type KnowledgeStatus = "active" | "deprecated";
+export type KnowledgeStability = "stable" | "evolving";
+export interface PromoteKnowledgeInput {
+    title?: string;
+    body?: string;
+    type?: string;
+    scope?: string;
+    status?: string;
+    stability?: string;
+    source?: string;
+}
+export interface KnowledgeCard {
+    id: string;
+    path: string;
+    title: string;
+    summary: string;
+    type: KnowledgeType;
+    status: KnowledgeStatus;
+    stability: KnowledgeStability;
+    scope: string[];
+    tags: string[];
+    sourcePaths: string[];
+    related: string[];
+    updatedAt: string;
+    searchable: string;
+}
+export interface PromotedKnowledge {
+    path: string;
+    id: string;
+    title: string;
+    type: KnowledgeType;
+    status: KnowledgeStatus;
+    stability: KnowledgeStability;
+    createdAt: string;
+}
+export interface KnowledgeCheckResult {
+    status: "passed" | "failed" | "not_configured";
+    knowledgeRoot: string;
+    cardCount: number;
+    activeCardCount: number;
+    deprecatedCardCount: number;
+    errors: string[];
+    warnings: string[];
+}
+export declare function promoteKnowledge(projectRoot: string, input: PromoteKnowledgeInput): PromotedKnowledge;
+export declare function discoverKnowledgeCards(projectRoot: string): KnowledgeCard[];
+export declare function checkKnowledge(projectRoot: string): KnowledgeCheckResult;