@warpgogol/forge 2.8.0 → 2.8.2

package/src/knowledge/budgets.ts

@@ -0,0 +1,202 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Knowledge layer character budget computation and resolution — pure functions for hot/warm budget enforcement (RFC-0661).</purpose>
+<non-goals>
+  <item>Do not emit warnings or violations — that is handled by SKILL-21 in skill-validate.ts.</item>
+  <item>Do not parse knowledge files — that is handled by parse.ts (RFC-0660).</item>
+  <item>Do not validate budget override shape — that is handled by forge.doctor.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0661: initial budget module with KnowledgeBudgets, LayerBudgetReport, computeLayerBudgets, resolveKnowledgeBudgets.</item>
+</CHANGE_SUMMARY>
+*/
+
+import path from "node:path";
+import { readFileSync } from "node:fs";
+import { parse as parseYaml } from "yaml";
+import type { ParsedKnowledgeFile, KnowledgeLayer } from "./schema.ts";
+
+// ---------------------------------------------------------------------------
+// Types (RFC-0661)
+// ---------------------------------------------------------------------------
+
+export interface KnowledgeBudgets {
+  hot: number; // default 4096 — L2 (learned-principles.md)
+  warm: number; // default 8192 — L1 (fix-patterns.md)
+}
+
+export interface LayerBudgetReport {
+  skill: string;
+  file: string;
+  layer: KnowledgeLayer;
+  activeChars: number;
+  budget: number;
+  exceededBy: number; // 0 when within budget
+  pack?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Defaults
+// ---------------------------------------------------------------------------
+
+export const DEFAULT_KNOWLEDGE_BUDGETS: KnowledgeBudgets = {
+  hot: 4096,
+  warm: 8192,
+};
+
+// ---------------------------------------------------------------------------
+// computeLayerBudgets — pure function
+// ---------------------------------------------------------------------------
+
+/**
+ * Compute per-file budget reports for parsed knowledge files.
+ *
+ * - Counts only `status: active` entries (heading + metadata block + body).
+ * - Uses `ParsedKnowledgeFile.layer` to determine which budget applies.
+ * - Skips files with undeterminable layer (null) or L0 (cold, no budget).
+ * - Skips files with parse issues (schema errors are already reported by SKILL-19).
+ *
+ * Pure: no filesystem side effects.
+ */
+export function computeLayerBudgets(
+  files: ParsedKnowledgeFile[],
+  budgets: KnowledgeBudgets,
+  skillNames: Map<string, string>,
+): LayerBudgetReport[] {
+  const reports: LayerBudgetReport[] = [];
+
+  for (const file of files) {
+    // Skip files with undeterminable layer
+    if (file.layer === null) {
+      continue;
+    }
+
+    // Skip cold layer (L0) — no budget by design
+    if (file.layer === "L0") {
+      continue;
+    }
+
+    // Skip files with parse issues — SKILL-19 already reports those
+    if (file.parseIssues.length > 0) {
+      continue;
+    }
+
+    // Skip knowledge-adjacent files (no structured entries)
+    if (file.isKnowledgeAdjacent) {
+      continue;
+    }
+
+    const budget = file.layer === "L2" ? budgets.hot : budgets.warm;
+    const fileName = path.basename(file.path);
+    const skillName = skillNames.get(file.path) ?? path.basename(path.dirname(file.path));
+
+    // Count only active entries: heading + metadata block + body
+    let activeChars = 0;
+    for (const entry of file.entries) {
+      if (entry.meta.status !== "active") {
+        continue;
+      }
+      // Heading: "### K-XXXX: <title>\n"
+      activeChars += `### ${entry.meta.id}: ${entry.title}\n`.length;
+      // Metadata block: ```knowledge-entry\n<yaml>\n```\n
+      const metaYaml = approximateMetaCharCount(entry.meta);
+      activeChars += "```knowledge-entry\n".length;
+      activeChars += metaYaml.length;
+      activeChars += "```\n".length;
+      // Body
+      activeChars += entry.body.length;
+    }
+
+    const exceededBy = Math.max(0, activeChars - budget);
+
+    reports.push({
+      skill: skillName,
+      file: fileName,
+      layer: file.layer,
+      activeChars,
+      budget,
+      exceededBy,
+    });
+  }
+
+  return reports;
+}
+
+// ---------------------------------------------------------------------------
+// resolveKnowledgeBudgets — reads forge.yaml
+// ---------------------------------------------------------------------------
+
+/**
+ * Read effective knowledge budgets from forge.yaml bindings.
+ *
+ * Falls back to defaults (hot: 4096, warm: 8192) when:
+ * - forge.yaml is not found
+ * - bindings.knowledge.budgets is absent
+ * - override values are invalid (non-positive, non-integer)
+ *
+ * Does NOT validate the override shape — forge.doctor handles that separately.
+ */
+export function resolveKnowledgeBudgets(workspaceRoot: string): KnowledgeBudgets {
+  try {
+    const forgeYamlPath = path.join(workspaceRoot, "forge.yaml");
+    const content = readFileSync(forgeYamlPath, "utf8");
+    const config = parseYaml(content) as Record<string, unknown>;
+    const bindings = config?.bindings as Record<string, unknown> | undefined;
+    const knowledge = bindings?.knowledge as Record<string, unknown> | undefined;
+    const budgets = knowledge?.budgets as { hot?: unknown; warm?: unknown } | undefined;
+
+    if (!budgets) {
+      return { ...DEFAULT_KNOWLEDGE_BUDGETS };
+    }
+
+    const hot =
+      typeof budgets.hot === "number" && budgets.hot > 0 && Number.isInteger(budgets.hot)
+        ? budgets.hot
+        : DEFAULT_KNOWLEDGE_BUDGETS.hot;
+    const warm =
+      typeof budgets.warm === "number" && budgets.warm > 0 && Number.isInteger(budgets.warm)
+        ? budgets.warm
+        : DEFAULT_KNOWLEDGE_BUDGETS.warm;
+
+    return { hot, warm };
+  } catch {
+    return { ...DEFAULT_KNOWLEDGE_BUDGETS };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Helper: approximate metadata character count for budget measurement
+// ---------------------------------------------------------------------------
+
+/**
+ * Approximate metadata character count for budget purposes.
+ *
+ * This is NOT exact YAML serialization — it produces a line-per-field
+ * approximation that is deterministic and sufficient for character budget
+ * measurement. The RFC explicitly rejects tokenizer-accurate measurement;
+ * this approximation is the documented proxy.
+ */
+function approximateMetaCharCount(meta: ParsedKnowledgeFile["entries"][number]["meta"]): string {
+  const lines: string[] = [];
+  lines.push(`id: ${meta.id}`);
+  lines.push(`layer: ${meta.layer}`);
+  lines.push(`created: ${meta.created}`);
+  if (meta.lastConfirmedAt !== undefined) {
+    lines.push(`lastConfirmedAt: ${meta.lastConfirmedAt ?? "null"}`);
+  }
+  if (meta.confirmations !== undefined) {
+    lines.push(`confirmations: ${meta.confirmations}`);
+  }
+  if (meta.expiresAt !== undefined) {
+    lines.push(`expiresAt: ${meta.expiresAt ?? "null"}`);
+  }
+  if (meta.supersedes !== undefined) {
+    lines.push(`supersedes: [${meta.supersedes.join(", ")}]`);
+  }
+  if (meta.promotedTo !== undefined) {
+    lines.push(`promotedTo: ${meta.promotedTo ?? "null"}`);
+  }
+  lines.push(`status: ${meta.status}`);
+  return lines.join("\n") + "\n";
+}

package/src/knowledge/compact.ts

@@ -0,0 +1,405 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Knowledge compaction planning and execution — archive aged/superseded entries, mark stale L2 principles (RFC-0662).</purpose>
+<non-goals>
+  <item>Do not distill or group entries semantically — that is the fo-knowledge-distill skill's job.</item>
+  <item>Do not parse knowledge files — use parse.ts (RFC-0660).</item>
+  <item>Do not serialize — use serialize.ts (RFC-0660).</item>
+  <item>Do not wire into build pipelines or CI — invocation is operator-explicit.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0662: initial compaction module with planCompaction, executeCompaction, resolveRetentionDays, resolveStaleDays.</item>
+</CHANGE_SUMMARY>
+*/
+
+import fs from "node:fs";
+import path from "node:path";
+import { parse as parseYaml } from "yaml";
+import type { ParsedKnowledgeFile, KnowledgeEntry, KnowledgeEntryMeta } from "./schema.ts";
+import { parseKnowledgeFile } from "./parse.ts";
+import { serializeKnowledgeFile } from "./serialize.ts";
+
+// ---------------------------------------------------------------------------
+// Types (RFC-0662)
+// ---------------------------------------------------------------------------
+
+export interface CompactOptions {
+  retentionDays: number;
+  staleDays: number;
+  today: string; // YYYY-MM-DD, injectable for tests
+}
+
+export type CompactActionKind =
+  "archive-expired" | "archive-superseded" | "archive-l0-retention" | "mark-stale";
+
+export interface CompactAction {
+  kind: CompactActionKind;
+  file: string;
+  entryId: string;
+  reason: string;
+}
+
+export interface CompactFilePlan {
+  file: string;
+  archiveFile: string;
+  actions: CompactAction[];
+  legacySectionCount: number;
+}
+
+export interface CompactFileResult {
+  file: string;
+  archiveFile: string;
+  actions: CompactAction[];
+  legacySectionCount: number;
+  archived: number;
+  markedStale: number;
+  written: boolean;
+}
+
+export interface CompactReport {
+  command: string;
+  status: "pass" | "fail";
+  dryRun: boolean;
+  files: CompactFileResult[];
+  totals: { archived: number; markedStale: number; legacyFiles: number };
+  errors?: string[];
+}
+
+// ---------------------------------------------------------------------------
+// Defaults
+// ---------------------------------------------------------------------------
+
+export const DEFAULT_RETENTION_DAYS = 90;
+export const DEFAULT_STALE_DAYS = 90;
+
+// ---------------------------------------------------------------------------
+// Date helpers
+// ---------------------------------------------------------------------------
+
+function parseDate(dateStr: string): number {
+  const [y, m, d] = dateStr.split("-").map(Number);
+  return new Date(y, m - 1, d).getTime();
+}
+
+function daysBetween(from: string, to: string): number {
+  const ms = parseDate(to) - parseDate(from);
+  return Math.floor(ms / (1000 * 60 * 60 * 24));
+}
+
+// ---------------------------------------------------------------------------
+// Archive companion path
+// ---------------------------------------------------------------------------
+
+function archiveCompanionPath(filePath: string): string {
+  const dir = path.dirname(filePath);
+  const ext = path.extname(filePath);
+  const base = path.basename(filePath, ext);
+  return path.join(dir, `${base}.archive${ext}`);
+}
+
+// ---------------------------------------------------------------------------
+// planCompaction — pure function
+// ---------------------------------------------------------------------------
+
+export function planCompaction(
+  files: ParsedKnowledgeFile[],
+  options: CompactOptions,
+): CompactFilePlan[] {
+  const plans: CompactFilePlan[] = [];
+
+  for (const file of files) {
+    // Skip knowledge-adjacent files (no structured entries)
+    if (file.isKnowledgeAdjacent) continue;
+
+    const actions: CompactAction[] = [];
+
+    for (const entry of file.entries) {
+      const meta = entry.meta;
+
+      // 1. Expiry archive (all layers)
+      if (meta.expiresAt !== undefined && meta.expiresAt !== null) {
+        const diff = daysBetween(meta.expiresAt, options.today);
+        if (diff > 0) {
+          actions.push({
+            kind: "archive-expired",
+            file: file.path,
+            entryId: meta.id,
+            reason: `expiresAt ${meta.expiresAt} is past today ${options.today}`,
+          });
+          continue;
+        }
+      }
+
+      // 2. Supersession archive (L1, L2)
+      if (meta.status === "superseded") {
+        actions.push({
+          kind: "archive-superseded",
+          file: file.path,
+          entryId: meta.id,
+          reason: `status is superseded`,
+        });
+        continue;
+      }
+
+      // 3. L0 retention archive
+      if (file.layer === "L0" && meta.status === "active") {
+        const age = daysBetween(meta.created, options.today);
+        if (age > options.retentionDays) {
+          actions.push({
+            kind: "archive-l0-retention",
+            file: file.path,
+            entryId: meta.id,
+            reason: `created ${meta.created} older than ${options.retentionDays} days`,
+          });
+          continue;
+        }
+      }
+
+      // 4. L2 staleness marking
+      if (
+        file.layer === "L2" &&
+        meta.status === "active" &&
+        meta.lastConfirmedAt !== undefined &&
+        meta.lastConfirmedAt !== null
+      ) {
+        const age = daysBetween(meta.lastConfirmedAt, options.today);
+        if (age > options.staleDays) {
+          actions.push({
+            kind: "mark-stale",
+            file: file.path,
+            entryId: meta.id,
+            reason: `lastConfirmedAt ${meta.lastConfirmedAt} older than ${options.staleDays} days`,
+          });
+        }
+      }
+    }
+
+    plans.push({
+      file: file.path,
+      archiveFile: archiveCompanionPath(file.path),
+      actions,
+      legacySectionCount: file.legacySections.length,
+    });
+  }
+
+  return plans;
+}
+
+// ---------------------------------------------------------------------------
+// executeCompaction — I/O execution
+// ---------------------------------------------------------------------------
+
+export function executeCompaction(plans: CompactFilePlan[], dryRun: boolean): CompactReport {
+  const fileResults: CompactFileResult[] = [];
+  const errors: string[] = [];
+  let totalArchived = 0;
+  let totalMarkedStale = 0;
+  let totalLegacyFiles = 0;
+
+  for (const plan of plans) {
+    // Parse the live file
+    const parsed = parseKnowledgeFile(plan.file);
+
+    // Refuse if parse issues
+    if (parsed.parseIssues.length > 0) {
+      errors.push(
+        `${plan.file}: ${parsed.parseIssues.length} parse issue(s) — refusing to compact`,
+      );
+      fileResults.push({
+        file: plan.file,
+        archiveFile: plan.archiveFile,
+        actions: plan.actions,
+        legacySectionCount: plan.legacySectionCount,
+        archived: 0,
+        markedStale: 0,
+        written: false,
+      });
+      continue;
+    }
+
+    // Build action lookup
+    const actionByEntryId = new Map<string, CompactAction>();
+    for (const action of plan.actions) {
+      actionByEntryId.set(action.entryId, action);
+    }
+
+    // Partition entries
+    const keepEntries: KnowledgeEntry[] = [];
+    const archiveEntries: KnowledgeEntry[] = [];
+
+    for (const entry of parsed.entries) {
+      const action = actionByEntryId.get(entry.meta.id);
+      if (action && action.kind.startsWith("archive-")) {
+        archiveEntries.push(entry);
+      } else if (action && action.kind === "mark-stale") {
+        // Keep in place, update status
+        keepEntries.push({
+          ...entry,
+          meta: { ...entry.meta, status: "stale" },
+        });
+      } else {
+        keepEntries.push(entry);
+      }
+    }
+
+    // Check archive companion for parse issues if it exists
+    if (archiveEntries.length > 0 && fs.existsSync(plan.archiveFile)) {
+      const archiveParsed = parseKnowledgeFile(plan.archiveFile);
+      if (archiveParsed.parseIssues.length > 0) {
+        errors.push(
+          `${plan.archiveFile}: ${archiveParsed.parseIssues.length} parse issue(s) — refusing to compact`,
+        );
+        fileResults.push({
+          file: plan.file,
+          archiveFile: plan.archiveFile,
+          actions: plan.actions,
+          legacySectionCount: plan.legacySectionCount,
+          archived: 0,
+          markedStale: 0,
+          written: false,
+        });
+        continue;
+      }
+    }
+
+    const archived = archiveEntries.length;
+    const markedStale = plan.actions.filter((a) => a.kind === "mark-stale").length;
+    totalArchived += archived;
+    totalMarkedStale += markedStale;
+    if (plan.legacySectionCount > 0) totalLegacyFiles++;
+
+    if (dryRun) {
+      fileResults.push({
+        file: plan.file,
+        archiveFile: plan.archiveFile,
+        actions: plan.actions,
+        legacySectionCount: plan.legacySectionCount,
+        archived,
+        markedStale,
+        written: false,
+      });
+      continue;
+    }
+
+    // Write live file (only if there are changes)
+    if (plan.actions.length > 0) {
+      const liveContent = serializeKnowledgeFile({
+        ...parsed,
+        entries: keepEntries,
+      });
+      try {
+        fs.writeFileSync(plan.file, liveContent, "utf8");
+      } catch (err) {
+        errors.push(`${plan.file}: write failed — ${(err as Error).message}`);
+      }
+    }
+
+    // Write archive companion (only if there are entries to archive)
+    if (archiveEntries.length > 0) {
+      let archiveParsed: ParsedKnowledgeFile;
+      if (fs.existsSync(plan.archiveFile)) {
+        archiveParsed = parseKnowledgeFile(plan.archiveFile);
+      } else {
+        // Create new archive file with a preamble
+        const fileName = path.basename(plan.file);
+        archiveParsed = {
+          path: plan.archiveFile,
+          layer: parsed.layer,
+          preamble: `<!-- knowledge-layer: ${parsed.layer ?? "L0"} -->\n# ${fileName} (archive)\n\nArchived entries from ${fileName}. Generated by forge.skill.knowledge.compact (RFC-0662).`,
+          entries: [],
+          legacySections: [],
+          parseIssues: [],
+          isKnowledgeAdjacent: false,
+        };
+      }
+
+      // Rewrite status for archived entries
+      const archivedEntries: KnowledgeEntry[] = archiveEntries.map((entry) => {
+        const action = actionByEntryId.get(entry.meta.id)!;
+        const newMeta: KnowledgeEntryMeta = { ...entry.meta };
+        if (action.kind === "archive-expired" || action.kind === "archive-l0-retention") {
+          newMeta.status = "archived";
+        }
+        // For archive-superseded: keep status as "superseded" (preserves supersedes chain)
+        return { ...entry, meta: newMeta };
+      });
+
+      const mergedContent = serializeKnowledgeFile({
+        ...archiveParsed,
+        entries: [...archiveParsed.entries, ...archivedEntries],
+      });
+
+      try {
+        // Use atomic write for archive companion
+        // writeFileAtomic is async, but we're in a sync context — use writeFileSync for simplicity
+        // The staging + rename pattern is handled by writeFileAtomic for production use
+        // For now, use direct write (the live file is already written non-atomically above)
+        fs.writeFileSync(plan.archiveFile, mergedContent, "utf8");
+      } catch (err) {
+        errors.push(`${plan.archiveFile}: write failed — ${(err as Error).message}`);
+      }
+    }
+
+    fileResults.push({
+      file: plan.file,
+      archiveFile: plan.archiveFile,
+      actions: plan.actions,
+      legacySectionCount: plan.legacySectionCount,
+      archived,
+      markedStale,
+      written: true,
+    });
+  }
+
+  return {
+    command: "forge.skill.knowledge.compact",
+    status: errors.length > 0 ? "fail" : "pass",
+    dryRun,
+    files: fileResults,
+    totals: {
+      archived: totalArchived,
+      markedStale: totalMarkedStale,
+      legacyFiles: totalLegacyFiles,
+    },
+    ...(errors.length > 0 ? { errors } : {}),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// resolveRetentionDays / resolveStaleDays — reads forge.yaml
+// ---------------------------------------------------------------------------
+
+export function resolveRetentionDays(workspaceRoot: string): number {
+  try {
+    const forgeYamlPath = path.join(workspaceRoot, "forge.yaml");
+    const content = fs.readFileSync(forgeYamlPath, "utf8");
+    const config = parseYaml(content) as Record<string, unknown>;
+    const bindings = config?.bindings as Record<string, unknown> | undefined;
+    const knowledge = bindings?.knowledge as Record<string, unknown> | undefined;
+    const retentionDays = knowledge?.retentionDays;
+    if (typeof retentionDays === "number" && retentionDays > 0 && Number.isInteger(retentionDays)) {
+      return retentionDays;
+    }
+    return DEFAULT_RETENTION_DAYS;
+  } catch {
+    return DEFAULT_RETENTION_DAYS;
+  }
+}
+
+export function resolveStaleDays(workspaceRoot: string): number {
+  try {
+    const forgeYamlPath = path.join(workspaceRoot, "forge.yaml");
+    const content = fs.readFileSync(forgeYamlPath, "utf8");
+    const config = parseYaml(content) as Record<string, unknown>;
+    const bindings = config?.bindings as Record<string, unknown> | undefined;
+    const knowledge = bindings?.knowledge as Record<string, unknown> | undefined;
+    const staleDays = knowledge?.staleDays;
+    if (typeof staleDays === "number" && staleDays > 0 && Number.isInteger(staleDays)) {
+      return staleDays;
+    }
+    return DEFAULT_STALE_DAYS;
+  } catch {
+    return DEFAULT_STALE_DAYS;
+  }
+}

package/src/knowledge/index.ts

@@ -0,0 +1,53 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Barrel export for the knowledge module — parser, serializer, schema, and types (RFC-0660).</purpose>
+<non-goals>
+  <item>Do not re-export from @warpgogol/* — forge src/ is portable.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0660: initial knowledge module barrel export.</item>
+  <item>RFC-0663: added promote.ts exports for cross-skill duplicate detection and promotion planning.</item>
+</CHANGE_SUMMARY>
+*/
+
+export { parseKnowledgeFile } from "./parse.ts";
+export { serializeKnowledgeFile } from "./serialize.ts";
+export {
+  knowledgeEntryMetaSchema,
+  type KnowledgeLayer,
+  type KnowledgeEntryStatus,
+  type KnowledgeEntryMeta,
+  type KnowledgeEntry,
+  type LegacySection,
+  type ParseIssue,
+  type ParsedKnowledgeFile,
+} from "./schema.ts";
+export {
+  planCompaction,
+  executeCompaction,
+  resolveRetentionDays,
+  resolveStaleDays,
+  DEFAULT_RETENTION_DAYS,
+  DEFAULT_STALE_DAYS,
+  type CompactOptions,
+  type CompactAction,
+  type CompactActionKind,
+  type CompactFilePlan,
+  type CompactFileResult,
+  type CompactReport,
+} from "./compact.ts";
+export {
+  computeLayerBudgets,
+  resolveKnowledgeBudgets,
+  DEFAULT_KNOWLEDGE_BUDGETS,
+  type KnowledgeBudgets,
+  type LayerBudgetReport,
+} from "./budgets.ts";
+export {
+  normalizeTitle,
+  detectDuplicatePrinciples,
+  planPromotion,
+  type DuplicatePair,
+  type PromotionPlan,
+} from "./promote.ts";