@lebronj/pi-suite 0.1.0

package/vendor/pi-memory/src/learning/candidates.ts

@@ -0,0 +1,205 @@
+import { createHash } from "node:crypto";
+import { parseEntry, renderEntry, type ParsedEntry } from "../curator-core/metadata.ts";
+import type { MemoryStore } from "../curator-store/types.ts";
+
+export const REVIEW_CANDIDATE_KINDS = ["bug_fix", "skill_candidate", "preference", "project_fact"] as const;
+export const REVIEW_PROMOTION_KINDS = ["memory_promotion", "memory_merge", "skill_promotion"] as const;
+export const REVIEW_STATUSES = [
+	"candidate",
+	"merged",
+	"proposed",
+	"approved",
+	"rejected",
+	"archived",
+	"stale",
+	"needs_review",
+] as const;
+export const REVIEW_CONFIDENCES = ["low", "medium", "high"] as const;
+export const REVIEW_TARGET_HINTS = ["memory", "skill"] as const;
+
+export type ReviewCandidateKind = (typeof REVIEW_CANDIDATE_KINDS)[number];
+export type ReviewStatus = (typeof REVIEW_STATUSES)[number];
+export type ReviewConfidence = (typeof REVIEW_CONFIDENCES)[number];
+export type ReviewTargetHint = (typeof REVIEW_TARGET_HINTS)[number];
+
+export type ReviewCandidateInput = {
+	kind: ReviewCandidateKind;
+	confidence: ReviewConfidence;
+	signature: string;
+	summary?: string;
+	source?: string;
+	targetHints?: ReviewTargetHint[];
+	evidence?: string;
+	date?: string;
+};
+
+export type ParsedReviewCandidate = {
+	entry: ParsedEntry;
+	id: string;
+	kind: ReviewCandidateKind;
+	status: ReviewStatus;
+	confidence: ReviewConfidence;
+	seen: number;
+	firstSeen: string;
+	lastSeen: string;
+	signature: string;
+	summary?: string;
+	evidence: string[];
+	targetHints: ReviewTargetHint[];
+	normalizedSignature: string;
+};
+
+export type UpsertReviewCandidateResult = {
+	changed: boolean;
+	merged: boolean;
+	id: string;
+	entry: string;
+};
+
+const CONFIDENCE_RANK: Record<ReviewConfidence, number> = {
+	low: 0,
+	medium: 1,
+	high: 2,
+};
+
+export function todayUtc(now: Date): string {
+	return now.toISOString().slice(0, 10);
+}
+
+export function normalizeCandidateSignature(kind: string, signature: string): string {
+	return `${kind}:${signature.toLowerCase().replace(/[^a-z0-9]+/g, " ").trim().replace(/\s+/g, " ")}`;
+}
+
+export function createReviewCandidateId(kind: string, signature: string): string {
+	const digest = createHash("sha256").update(normalizeCandidateSignature(kind, signature)).digest("hex").slice(0, 12);
+	return `rev_${digest}`;
+}
+
+export function validateReviewCandidateInput(input: ReviewCandidateInput): string[] {
+	const errors: string[] = [];
+	if (!REVIEW_CANDIDATE_KINDS.includes(input.kind)) errors.push(`invalid kind '${input.kind}'`);
+	if (!REVIEW_CONFIDENCES.includes(input.confidence)) errors.push(`invalid confidence '${input.confidence}'`);
+	if (!input.signature.trim()) errors.push("signature is required");
+	for (const hint of input.targetHints ?? []) {
+		if (!REVIEW_TARGET_HINTS.includes(hint)) errors.push(`invalid target hint '${hint}'`);
+	}
+	return errors;
+}
+
+export function renderReviewCandidate(input: ReviewCandidateInput, now = new Date()): string {
+	const errors = validateReviewCandidateInput(input);
+	if (errors.length) throw new Error(`Invalid review candidate: ${errors.join("; ")}`);
+
+	const signature = input.signature.trim();
+	const date = input.date || todayUtc(now);
+	const metadata: Record<string, string> = {
+		type: "review",
+		status: "candidate",
+		id: createReviewCandidateId(input.kind, signature),
+		kind: input.kind,
+		confidence: input.confidence,
+		seen: "1",
+		first_seen: date,
+		last_seen: date,
+	};
+	if (input.source?.trim()) metadata.source = input.source.trim().replace(/[\s\]]+/g, "-");
+	if (input.targetHints?.length) metadata.target_hints = [...new Set(input.targetHints)].join(",");
+
+	const body = [`Signature: ${signature}`];
+	if (input.summary?.trim()) body.push(`Summary: ${input.summary.trim()}`);
+	if (input.evidence?.trim()) body.push(`Evidence: ${input.evidence.trim()}`);
+	return renderEntry({ metadata, body: body.join("\n"), raw: "", hasMetadata: true });
+}
+
+export function parseReviewCandidate(raw: string): ParsedReviewCandidate | null {
+	const entry = parseEntry(raw);
+	const metadata = entry.metadata;
+	if (metadata.type !== "review" || metadata.status !== "candidate") return null;
+	if (!metadata.id || !REVIEW_CANDIDATE_KINDS.includes(metadata.kind as ReviewCandidateKind)) return null;
+	if (!REVIEW_STATUSES.includes(metadata.status as ReviewStatus)) return null;
+	if (!REVIEW_CONFIDENCES.includes(metadata.confidence as ReviewConfidence)) return null;
+	const signature = extractBodyField(entry.body, "Signature");
+	if (!signature) return null;
+	const seen = Number.parseInt(metadata.seen || "1", 10);
+	const targetHints = (metadata.target_hints || "")
+		.split(",")
+		.map((hint) => hint.trim())
+		.filter((hint): hint is ReviewTargetHint => REVIEW_TARGET_HINTS.includes(hint as ReviewTargetHint));
+	return {
+		entry,
+		id: metadata.id,
+		kind: metadata.kind as ReviewCandidateKind,
+		status: metadata.status as ReviewStatus,
+		confidence: metadata.confidence as ReviewConfidence,
+		seen: Number.isFinite(seen) && seen > 0 ? seen : 1,
+		firstSeen: metadata.first_seen || metadata.last_seen || todayUtc(new Date()),
+		lastSeen: metadata.last_seen || metadata.first_seen || todayUtc(new Date()),
+		signature,
+		summary: extractBodyField(entry.body, "Summary") || undefined,
+		evidence: extractBodyFields(entry.body, "Evidence"),
+		targetHints,
+		normalizedSignature: normalizeCandidateSignature(metadata.kind, signature),
+	};
+}
+
+export async function upsertReviewCandidate(
+	memoryStore: MemoryStore,
+	input: ReviewCandidateInput,
+	now = new Date(),
+): Promise<UpsertReviewCandidateResult> {
+	const newEntry = renderReviewCandidate(input, now);
+	const newCandidate = parseReviewCandidate(newEntry);
+	if (!newCandidate) throw new Error("Rendered review candidate could not be parsed.");
+
+	const entries = await memoryStore.readEntries("review");
+	const existingIndex = entries.findIndex((entry) => {
+		const candidate = parseReviewCandidate(entry);
+		return candidate?.normalizedSignature === newCandidate.normalizedSignature;
+	});
+
+	if (existingIndex < 0) {
+		await memoryStore.writeEntries("review", [...entries, newEntry]);
+		return { changed: true, merged: false, id: newCandidate.id, entry: newEntry };
+	}
+
+	const existing = parseReviewCandidate(entries[existingIndex]);
+	if (!existing) throw new Error("Matched review candidate could not be parsed.");
+	const updatedEntry = mergeReviewCandidate(existing, input, now);
+	if (updatedEntry === entries[existingIndex]) return { changed: false, merged: true, id: existing.id, entry: updatedEntry };
+	const updatedEntries = [...entries];
+	updatedEntries[existingIndex] = updatedEntry;
+	await memoryStore.writeEntries("review", updatedEntries);
+	return { changed: true, merged: true, id: existing.id, entry: updatedEntry };
+}
+
+function mergeReviewCandidate(existing: ParsedReviewCandidate, input: ReviewCandidateInput, now: Date): string {
+	const metadata = { ...existing.entry.metadata };
+	metadata.seen = String(existing.seen + 1);
+	metadata.last_seen = input.date || todayUtc(now);
+	if (CONFIDENCE_RANK[input.confidence] > CONFIDENCE_RANK[existing.confidence]) metadata.confidence = input.confidence;
+	if (input.targetHints?.length) {
+		const current = (metadata.target_hints || "").split(",").map((hint) => hint.trim()).filter(Boolean);
+		metadata.target_hints = [...new Set([...current, ...input.targetHints])].join(",");
+	}
+
+	let body = existing.entry.body;
+	if (input.evidence?.trim() && !body.includes(input.evidence.trim())) {
+		body = `${body.trim()}\nEvidence: ${input.evidence.trim()}`;
+	}
+	return renderEntry({ ...existing.entry, metadata, body });
+}
+
+export function extractBodyField(body: string, field: string): string | null {
+	const prefix = `${field}:`;
+	const line = body.split("\n").find((candidate) => candidate.startsWith(prefix));
+	return line?.slice(prefix.length).trim() || null;
+}
+
+export function extractBodyFields(body: string, field: string): string[] {
+	const prefix = `${field}:`;
+	return body
+		.split("\n")
+		.filter((candidate) => candidate.startsWith(prefix))
+		.map((candidate) => candidate.slice(prefix.length).trim())
+		.filter(Boolean);
+}

package/vendor/pi-memory/src/learning/memory.ts

@@ -0,0 +1,144 @@
+import { parseEntry, renderEntry } from "../curator-core/metadata.ts";
+import type { MemoryStore, MemoryTarget } from "../curator-store/types.ts";
+import { parseReviewCandidate, type ParsedReviewCandidate } from "./candidates.ts";
+
+export type MemoryPromotionResult = {
+	created: number;
+	proposalIds: string[];
+};
+
+export type MemoryApprovalResult = {
+	proposalId: string;
+	target: MemoryTarget;
+	content: string;
+};
+
+export type ReviewLifecycleResult = {
+	changed: number;
+};
+
+export async function proposeMemoryPromotions(memoryStore: MemoryStore, seenThreshold = 2): Promise<MemoryPromotionResult> {
+	const entries = await memoryStore.readEntries("review");
+	const existingProposalSources = new Set(
+		entries
+			.map((entry) => parseEntry(entry).metadata)
+			.filter((metadata) => metadata.type === "review" && (metadata.kind === "memory_promotion" || metadata.kind === "memory_merge"))
+			.flatMap((metadata) => (metadata.source_candidate_ids || "").split(",").map((id) => id.trim()).filter(Boolean)),
+	);
+	const proposals = entries
+		.map(parseReviewCandidate)
+		.filter((candidate): candidate is ParsedReviewCandidate => candidate !== null)
+		.filter((candidate) => isMemoryCandidateReady(candidate, seenThreshold) && !existingProposalSources.has(candidate.id))
+		.map(renderMemoryProposalEntry);
+	if (proposals.length === 0) return { created: 0, proposalIds: [] };
+	await memoryStore.writeEntries("review", [...entries, ...proposals]);
+	return { created: proposals.length, proposalIds: proposals.map((entry) => parseEntry(entry).metadata.id || "").filter(Boolean) };
+}
+
+export async function approveMemoryPromotion(memoryStore: MemoryStore, proposalId: string): Promise<MemoryApprovalResult> {
+	const entries = await memoryStore.readEntries("review");
+	const index = entries.findIndex((entry) => parseEntry(entry).metadata.id === proposalId);
+	if (index < 0) throw new Error(`No review proposal found for id '${proposalId}'.`);
+	const parsed = parseEntry(entries[index]);
+	if (parsed.metadata.type !== "review" || parsed.metadata.kind !== "memory_promotion" || parsed.metadata.status !== "proposed") {
+		throw new Error(`Review entry '${proposalId}' is not a proposed memory promotion.`);
+	}
+	const target = normalizePromotionTarget(parsed.metadata.promotes_to);
+	const content = bodyBlock(parsed.body, "Memory") || bodyField(parsed.body, "Proposal");
+	if (!content) throw new Error(`Memory proposal '${proposalId}' has no memory content.`);
+	const targetEntries = await memoryStore.readEntries(target);
+	if (!targetEntries.includes(content)) await memoryStore.writeEntries(target, [...targetEntries, content]);
+	const approved = renderEntry({
+		...parsed,
+		metadata: { ...parsed.metadata, status: "approved", approved_at: new Date().toISOString() },
+		body: `${parsed.body.trim()}\nApplied: ${target}`,
+	});
+	const updated = [...entries];
+	updated[index] = approved;
+	await memoryStore.writeEntries("review", updated);
+	return { proposalId, target, content };
+}
+
+export async function rejectReviewItem(memoryStore: MemoryStore, id: string, status: "rejected" | "archived" = "rejected"): Promise<void> {
+	const entries = await memoryStore.readEntries("review");
+	const index = entries.findIndex((entry) => parseEntry(entry).metadata.id === id);
+	if (index < 0) throw new Error(`No review entry found for id '${id}'.`);
+	const parsed = parseEntry(entries[index]);
+	if (parsed.metadata.type !== "review") throw new Error(`Entry '${id}' is not a review entry.`);
+	const updated = [...entries];
+	updated[index] = renderEntry({ ...parsed, metadata: { ...parsed.metadata, status, reviewed_at: new Date().toISOString() } });
+	await memoryStore.writeEntries("review", updated);
+}
+
+export async function applyReviewLifecycle(memoryStore: MemoryStore, now = new Date(), staleDays = 30, archiveDays = 90): Promise<ReviewLifecycleResult> {
+	const entries = await memoryStore.readEntries("review");
+	let changed = 0;
+	const updated = entries.map((entry) => {
+		const parsed = parseEntry(entry);
+		if (parsed.metadata.type !== "review" || parsed.metadata.status !== "candidate") return entry;
+		const lastSeen = parsed.metadata.last_seen || parsed.metadata.first_seen;
+		if (!lastSeen) return entry;
+		const ageDays = Math.floor((now.getTime() - Date.parse(`${lastSeen}T00:00:00.000Z`)) / 86_400_000);
+		if (!Number.isFinite(ageDays) || ageDays < staleDays) return entry;
+		const nextStatus = ageDays >= archiveDays && parsed.metadata.confidence === "low" ? "archived" : "needs_review";
+		changed += 1;
+		return renderEntry({ ...parsed, metadata: { ...parsed.metadata, status: nextStatus, reviewed_at: now.toISOString() } });
+	});
+	if (changed > 0) await memoryStore.writeEntries("review", updated);
+	return { changed };
+}
+
+function isMemoryCandidateReady(candidate: ParsedReviewCandidate, threshold: number): boolean {
+	if (!["preference", "project_fact", "bug_fix"].includes(candidate.kind) && !candidate.targetHints.includes("memory")) return false;
+	return candidate.seen >= threshold || candidate.confidence === "high";
+}
+
+function renderMemoryProposalEntry(candidate: ParsedReviewCandidate): string {
+	const target = candidate.kind === "preference" ? "user" : "memory";
+	const content = formatMemoryContent(candidate);
+	return renderEntry({
+		metadata: {
+			type: "review",
+			status: "proposed",
+			id: `mem_${candidate.id.slice(4)}`,
+			kind: "memory_promotion",
+			confidence: candidate.confidence,
+			source_candidate_ids: candidate.id,
+			promotes_to: target,
+		},
+		body: [`Proposal: Promote reviewed candidate to ${target}.`, `Memory: ${content}`].join("\n"),
+		raw: "",
+		hasMetadata: true,
+	});
+}
+
+function formatMemoryContent(candidate: ParsedReviewCandidate): string {
+	const type = candidate.kind === "preference" ? "preference" : "fact";
+	const summary = candidate.summary || candidate.signature;
+	return `[type:${type}]\n${summary}`;
+}
+
+function normalizePromotionTarget(value: string | undefined): MemoryTarget {
+	if (value === "user" || value === "state" || value === "review") return value;
+	return "memory";
+}
+
+function bodyField(body: string, field: string): string | null {
+	const prefix = `${field}:`;
+	const line = body.split("\n").find((candidate) => candidate.startsWith(prefix));
+	return line?.slice(prefix.length).trim() || null;
+}
+
+function bodyBlock(body: string, field: string): string | null {
+	const prefix = `${field}:`;
+	const lines = body.split("\n");
+	const start = lines.findIndex((line) => line.startsWith(prefix));
+	if (start < 0) return null;
+	const first = lines[start].slice(prefix.length).trim();
+	const rest: string[] = [];
+	for (const line of lines.slice(start + 1)) {
+		if (/^[A-Z][A-Za-z ]+:/.test(line)) break;
+		rest.push(line);
+	}
+	return [first, ...rest].join("\n").trim() || null;
+}

package/vendor/pi-memory/src/learning/skills.ts

@@ -0,0 +1,200 @@
+import { mkdirSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { parseEntry, renderEntry } from "../curator-core/metadata.ts";
+import type { MemoryStore } from "../curator-store/types.ts";
+import { parseReviewCandidate, type ParsedReviewCandidate } from "./candidates.ts";
+
+export type SkillProposal = {
+	id: string;
+	sourceCandidateIds: string[];
+	slug: string;
+	description: string;
+	title: string;
+	body: string;
+	promotesTo: string;
+};
+
+export type SkillProposalOptions = {
+	draftsDir: string;
+	seenThreshold?: number;
+	now?: Date;
+};
+
+export type SkillProposalResult = {
+	created: number;
+	proposals: SkillProposal[];
+};
+
+export type SkillApprovalResult = {
+	proposalId: string;
+	path: string;
+	content: string;
+};
+
+export async function proposeSkillDrafts(
+	memoryStore: MemoryStore,
+	options: SkillProposalOptions,
+): Promise<SkillProposalResult> {
+	const entries = await memoryStore.readEntries("review");
+	const candidates = entries.map(parseReviewCandidate).filter((candidate): candidate is ParsedReviewCandidate => candidate !== null);
+	const threshold = options.seenThreshold ?? 3;
+	const proposals: SkillProposal[] = [];
+	const existingProposalSources = new Set(
+		entries
+			.map((entry) => parseEntry(entry).metadata)
+			.filter((metadata) => metadata.type === "review" && metadata.kind === "skill_promotion")
+			.flatMap((metadata) => (metadata.source_candidate_ids || "").split(",").map((id) => id.trim()).filter(Boolean)),
+	);
+
+	for (const candidate of candidates) {
+		if (!isSkillCandidateReady(candidate, threshold) || existingProposalSources.has(candidate.id)) continue;
+		proposals.push(createSkillProposal(candidate, options.draftsDir));
+	}
+
+	if (proposals.length === 0) return { created: 0, proposals: [] };
+	await memoryStore.writeEntries("review", [...entries, ...proposals.map(renderSkillProposalEntry)]);
+	return { created: proposals.length, proposals };
+}
+
+export async function approveSkillDraft(memoryStore: MemoryStore, proposalId: string): Promise<SkillApprovalResult> {
+	const entries = await memoryStore.readEntries("review");
+	const index = entries.findIndex((entry) => parseEntry(entry).metadata.id === proposalId);
+	if (index < 0) throw new Error(`No review proposal found for id '${proposalId}'.`);
+	const parsed = parseEntry(entries[index]);
+	if (parsed.metadata.type !== "review" || parsed.metadata.kind !== "skill_promotion" || parsed.metadata.status !== "proposed") {
+		throw new Error(`Review entry '${proposalId}' is not a proposed skill promotion.`);
+	}
+	const path = parsed.metadata.promotes_to;
+	if (!path) throw new Error(`Skill proposal '${proposalId}' has no promotes_to path.`);
+	const content = buildSkillDraftFromProposal(parsed.body);
+	mkdirSync(dirname(path), { recursive: true });
+	writeFileSync(path, content, { encoding: "utf-8", flag: "wx" });
+	const approved = renderEntry({
+		...parsed,
+		metadata: { ...parsed.metadata, status: "approved", approved_at: new Date().toISOString() },
+		body: `${parsed.body.trim()}\nApplied: ${path}`,
+	});
+	const updated = [...entries];
+	updated[index] = approved;
+	await memoryStore.writeEntries("review", updated);
+	return { proposalId, path, content };
+}
+
+export async function listSkillDraftProposals(memoryStore: MemoryStore): Promise<SkillProposal[]> {
+	const entries = await memoryStore.readEntries("review");
+	return entries
+		.map((entry) => parseEntry(entry))
+		.filter((entry) => entry.metadata.type === "review" && entry.metadata.kind === "skill_promotion")
+		.map((entry) => ({
+			id: entry.metadata.id || "",
+			sourceCandidateIds: (entry.metadata.source_candidate_ids || "").split(",").map((id) => id.trim()).filter(Boolean),
+			slug: slugFromPath(entry.metadata.promotes_to || ""),
+			description: bodyField(entry.body, "Description") || "",
+			title: bodyField(entry.body, "Title") || "Skill Draft",
+			body: entry.body,
+			promotesTo: entry.metadata.promotes_to || "",
+		}));
+}
+
+function isSkillCandidateReady(candidate: ParsedReviewCandidate, threshold: number): boolean {
+	if (candidate.kind !== "skill_candidate" && !candidate.targetHints.includes("skill")) return false;
+	if (candidate.confidence !== "high" && candidate.seen < threshold) return false;
+	return candidate.seen >= threshold || candidate.confidence === "high";
+}
+
+function createSkillProposal(candidate: ParsedReviewCandidate, draftsDir: string): SkillProposal {
+	const slug = slugify(candidate.signature);
+	const title = titleFromSignature(candidate.signature);
+	const description = `Use when ${candidate.signature.toLowerCase()}.`;
+	const promotesTo = join(draftsDir, slug, "SKILL.md");
+	const evidence = candidate.evidence.length ? candidate.evidence.map((item) => `- ${item}`).join("\n") : "- Source candidate evidence is in REVIEW.md.";
+	const body = [
+		`Title: ${title}`,
+		`Description: ${description}`,
+		`Source candidates: ${candidate.id}`,
+		"Proposal: Draft a reusable skill from repeated reviewed evidence.",
+		"",
+		"Draft content:",
+		"```md",
+		"---",
+		`name: ${slug}`,
+		`description: ${description}`,
+		"---",
+		"",
+		`# ${title}`,
+		"",
+		"## When to use",
+		description,
+		"",
+		"## Method",
+		candidate.summary || candidate.signature,
+		"",
+		"## Evidence",
+		evidence,
+		"",
+		"## Stop condition",
+		"Stop after the validation signal from the source evidence passes, or report the remaining blocker.",
+		"```",
+	].join("\n");
+	return {
+		id: `skill_${candidate.id.slice(4)}`,
+		sourceCandidateIds: [candidate.id],
+		slug,
+		description,
+		title,
+		body,
+		promotesTo,
+	};
+}
+
+function renderSkillProposalEntry(proposal: SkillProposal): string {
+	return renderEntry({
+		metadata: {
+			type: "review",
+			status: "proposed",
+			id: proposal.id,
+			kind: "skill_promotion",
+			confidence: "high",
+			source_candidate_ids: proposal.sourceCandidateIds.join(","),
+			promotes_to: proposal.promotesTo,
+		},
+		body: proposal.body,
+		raw: "",
+		hasMetadata: true,
+	});
+}
+
+function buildSkillDraftFromProposal(body: string): string {
+	const marker = "Draft content:";
+	const markerIndex = body.indexOf(marker);
+	if (markerIndex < 0) throw new Error("Skill proposal does not include draft content.");
+	const fenced = body.slice(markerIndex + marker.length).trim();
+	if (!fenced.startsWith("```md") || !fenced.endsWith("```")) throw new Error("Skill proposal draft content must be a markdown fence.");
+	return `${fenced.slice(5, -3).trim()}\n`;
+}
+
+function bodyField(body: string, field: string): string | null {
+	const prefix = `${field}:`;
+	const line = body.split("\n").find((candidate) => candidate.startsWith(prefix));
+	return line?.slice(prefix.length).trim() || null;
+}
+
+function slugify(value: string): string {
+	const slug = value.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 48);
+	return slug || "reviewed-skill";
+}
+
+function titleFromSignature(signature: string): string {
+	return signature
+		.replace(/[^a-zA-Z0-9]+/g, " ")
+		.trim()
+		.split(/\s+/)
+		.slice(0, 8)
+		.map((word) => word[0]?.toUpperCase() + word.slice(1).toLowerCase())
+		.join(" ") || "Reviewed Skill";
+}
+
+function slugFromPath(value: string): string {
+	const parts = value.split(/[\\/]+/).filter(Boolean);
+	return parts.length > 1 ? parts[parts.length - 2] : "";
+}