@warpgogol/forge 4.0.0 → 4.1.2

package/os/rfc/rfc.module.ts

@@ -15,13 +15,8 @@
 
 import type { ForgeModule } from "../../src/forge-module.ts";
 
-export const forgeRfcModule: ForgeModule = {
-  name: "rfc",
-  version: "0.1.0",
-  runtime: "autonomous",
-
-  async register(registry) {
-    const {
+export async function createForgeRfcModule(): Promise<ForgeModule> {
+const {
       runRfcList,
       runRfcCreate,
       runRfcNextId,
@@ -41,8 +36,15 @@ export const forgeRfcModule: ForgeModule = {
     const { runRfcArchive } = await import("./handlers/archive.ts");
     const { runRfcPipelineStatus } = await import("./handlers/pipeline-status.ts");
     const { runRfcImplementStamp } = await import("./handlers/implement-stamp.ts");
-    // ── rfc.list ─────────────────────────────────────────────────────────────
-    registry.registerCommand({
+    // ── rfc.list ─────────────────────────────────────────────────────────────;
+  return {
+  name: "rfc",
+  version: "0.1.0",
+  runtime: "autonomous",
+
+    declarations: [],
+  commands: [
+    {
       name: "rfc.list",
       description:
         "List all RFCs. Filter with --status, --kind, --owner flags. " +
@@ -67,10 +69,8 @@ export const forgeRfcModule: ForgeModule = {
       },
       reads: ["docs/rfcs/**/*.md"],
       execute: runRfcList,
-    });
-
-    // ── rfc.create ───────────────────────────────────────────────────────────
-    registry.registerCommand({
+    },
+    {
       name: "rfc.create",
       description:
         "Create a new RFC draft from the template. " +
@@ -99,10 +99,8 @@ export const forgeRfcModule: ForgeModule = {
         },
       },
       execute: runRfcCreate,
-    });
-
-    // ── rfc.next-id ───────────────────────────────────────────────────────────
-    registry.registerCommand({
+    },
+    {
       name: "rfc.next-id",
       description:
         "Return the next free RFC number (max existing + 1) by scanning docs/rfcs/ recursively including archive/.",
@@ -110,10 +108,8 @@ export const forgeRfcModule: ForgeModule = {
       flags: {},
       reads: ["docs/rfcs/**/*.md"],
       execute: runRfcNextId,
-    });
-
-    // ── rfc.validate ─────────────────────────────────────────────────────────
-    registry.registerCommand({
+    },
+    {
       name: "rfc.validate",
       contract: "rfc",
       rules: [],
@@ -128,10 +124,8 @@ export const forgeRfcModule: ForgeModule = {
       },
       reads: ["docs/rfcs/**/*.md"],
       execute: runRfcValidate,
-    });
-
-    // ── rfc.command-lifecycle.validate ───────────────────────────────────────
-    registry.registerCommand({
+    },
+    {
       name: "rfc.command-lifecycle.validate",
       contract: "rfc",
       rules: [],
@@ -145,10 +139,8 @@ export const forgeRfcModule: ForgeModule = {
       reads: ["docs/rfcs/**/*.md"],
       cacheable: false,
       execute: runRfcCommandLifecycleValidate,
-    });
-
-    // ── rfc.check ────────────────────────────────────────────────────────────
-    registry.registerCommand({
+    },
+    {
       name: "rfc.check",
       contract: "rfc",
       rules: [],
@@ -166,10 +158,8 @@ export const forgeRfcModule: ForgeModule = {
       },
       reads: ["docs/rfcs/**/*.md"],
       execute: runRfcCheck,
-    });
-
-    // ── rfc.index.generate ───────────────────────────────────────────────────
-    registry.registerCommand({
+    },
+    {
       name: "rfc.index.generate",
       description:
         "Emit a machine-readable relationship index of all RFCs (id, status, dates, " +
@@ -186,10 +176,8 @@ export const forgeRfcModule: ForgeModule = {
       reads: ["docs/rfcs/**/*.md"],
       cacheable: false,
       execute: runRfcIndexGenerate,
-    });
-
-    // ── rfc.index.validate ───────────────────────────────────────────────────
-    registry.registerCommand({
+    },
+    {
       name: "rfc.index.validate",
       contract: "rfc",
       rules: [],
@@ -201,10 +189,8 @@ export const forgeRfcModule: ForgeModule = {
       flags: {},
       reads: ["docs/rfcs/**/*.md", "docs/rfcs/index.yaml"],
       execute: runRfcIndexValidate,
-    });
-
-    // ── rfc.graph ────────────────────────────────────────────────────────────
-    registry.registerCommand({
+    },
+    {
       name: "rfc.graph",
       description:
         "Print one RFC's relationship neighbours (supersedes/supersededBy/amends/" +
@@ -215,10 +201,8 @@ export const forgeRfcModule: ForgeModule = {
       },
       reads: ["docs/rfcs/**/*.md"],
       execute: runRfcGraph,
-    });
-
-    // ── rfc.acceptance.run ───────────────────────────────────────────────────
-    registry.registerCommand({
+    },
+    {
       name: "rfc.acceptance.run",
       description:
         "RFC-0268: execute the acceptance: probes declared in an RFC's frontmatter and report " +
@@ -236,10 +220,8 @@ export const forgeRfcModule: ForgeModule = {
       reads: ["docs/rfcs/**/*.md"],
       cacheable: false,
       execute: runRfcAcceptanceRun,
-    });
-
-    // ── rfc.verification.emit ────────────────────────────────────────────────
-    registry.registerCommand({
+    },
+    {
       name: "rfc.verification.emit",
       description:
         "RFC-0330: execute acceptance probes for target RFC(s) and write per-RFC verification " +
@@ -258,10 +240,8 @@ export const forgeRfcModule: ForgeModule = {
         },
       },
       execute: runRfcVerificationEmit,
-    });
-
-    // ── rfc.verification.refresh ────────────────────────────────────────────
-    registry.registerCommand({
+    },
+    {
       name: "rfc.verification.refresh",
       description:
         "RFC-0999: re-run acceptance probes for implemented RFC(s) and update verification " +
@@ -285,10 +265,8 @@ export const forgeRfcModule: ForgeModule = {
         },
       },
       execute: runRfcVerificationRefresh,
-    });
-
-    // ── rfc.dna.trace.validate ───────────────────────────────────────────────
-    registry.registerCommand({
+    },
+    {
       name: "rfc.dna.trace.validate",
       contract: "rfc",
       rules: [],
@@ -305,10 +283,8 @@ export const forgeRfcModule: ForgeModule = {
       },
       reads: ["docs/rfcs/**/*.md", "docs/architecture-dna.md"],
       execute: runRfcDnaTraceValidate,
-    });
-
-    // ── rfc.dna.trace.generate ───────────────────────────────────────────────
-    registry.registerCommand({
+    },
+    {
       name: "rfc.dna.trace.generate",
       description:
         "RFC-0331: generate docs/rfcs/dna-trace.generated.yaml — the machine-readable " +
@@ -320,10 +296,8 @@ export const forgeRfcModule: ForgeModule = {
       cacheable: false,
       flags: {},
       execute: runRfcDnaTraceGenerate,
-    });
-
-    // ── rfc.decision-log.generate ────────────────────────────────────────────
-    registry.registerCommand({
+    },
+    {
       name: "rfc.decision-log.generate",
       description:
         "RFC-0329: generate docs/rfcs/decision-log.generated.yaml and .md aggregating every " +
@@ -341,10 +315,8 @@ export const forgeRfcModule: ForgeModule = {
         },
       },
       execute: runRfcDecisionLogGenerate,
-    });
-
-    // ── rfc.supersede.propose ─────────────────────────────────────────────────
-    registry.registerCommand({
+    },
+    {
       name: "rfc.supersede.propose",
       description:
         "RFC-0334: escalate a blocked implementation by creating a draft superseding RFC " +
@@ -373,10 +345,8 @@ export const forgeRfcModule: ForgeModule = {
         },
       },
       execute: runRfcSupersedePropose,
-    });
-
-    // ── rfc.archive ───────────────────────────────────────────────────────────
-    registry.registerCommand({
+    },
+    {
       name: "rfc.archive",
       description:
         "Move terminal-status RFC files (implemented, rejected, superseded) into " +
@@ -400,10 +370,8 @@ export const forgeRfcModule: ForgeModule = {
         },
       },
       execute: runRfcArchive,
-    });
-
-    // ── rfc.pipeline.status ──────────────────────────────────────────────────
-    registry.registerCommand({
+    },
+    {
       name: "rfc.pipeline.status",
       description:
         "Report the pipeline status of RFCs — which steps (audit, enhance, plan, implement) " +
@@ -416,10 +384,8 @@ export const forgeRfcModule: ForgeModule = {
       },
       reads: ["docs/rfcs/**/*.md"],
       execute: runRfcPipelineStatus,
-    });
-
-    // ── rfc.implement.stamp ──────────────────────────────────────────────────
-    registry.registerCommand({
+    },
+    {
       name: "rfc.implement.stamp",
       description:
         "RFC-0476: the exclusive atomic path for accepted → implemented transitions. " +
@@ -450,6 +416,10 @@ export const forgeRfcModule: ForgeModule = {
         },
       },
       execute: runRfcImplementStamp,
-    });
-  },
-};
+    }
+  ],
+  pipelines: [
+
+  ]};
+}
+;

package/os/rfc/types.ts

@@ -541,6 +541,7 @@ export interface RfcImplementStampData {
   stampedAt: string;
   criteriaChecked: number;
   evidencePath?: string;
+  metricsPath?: string;
 }
 
 export type RfcImplementStampRule =

package/os/session/handlers/metrics-aggregate.ts

@@ -0,0 +1,208 @@
+/*
+<MODULE_CONTRACT>
+<purpose>
+RFC-1053: metrics.aggregate command handler — scans docs/metrics/ files and
+produces per-skill statistics (invocations, avgFindings, avgFixIterations,
+avgDurationMs). Supports --skill, --since, --until filters. Returns empty
+result when no metrics files exist.
+</purpose>
+<non-goals>
+  <item>Does not write files — read-only aggregation.</item>
+  <item>Does not index metrics files — scans on each invocation.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-1053: initial metrics.aggregate command handler.</item>
+</CHANGE_SUMMARY>
+*/
+
+import { readdir, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { parse as yamlParse } from "yaml";
+
+import { METRICS_DIR, type MetricsAggregateResult, type SkillAggregate, type RfcMetrics, type SessionMetrics } from "../types.ts";
+import type { ForgeCommandInput, ForgeCommandResult, ForgeRuntimeContext } from "../../../src/types.ts";
+
+async function readYamlFile<T>(filePath: string): Promise<T | null> {
+  try {
+    const content = await readFile(filePath, "utf-8");
+    return yamlParse(content) as T;
+  } catch {
+    return null;
+  }
+}
+
+export async function runMetricsAggregate(
+  input: ForgeCommandInput,
+  context: ForgeRuntimeContext,
+): Promise<ForgeCommandResult<MetricsAggregateResult>> {
+  const { workspaceRoot, outputFormat } = context;
+  const skillFilter = input.flags["skill"] as string | undefined;
+  const since = input.flags["since"] as string | undefined;
+  const until = input.flags["until"] as string | undefined;
+
+  const rfcMetricsDir = join(workspaceRoot, METRICS_DIR, "rfcs");
+  const sessionMetricsDir = join(workspaceRoot, METRICS_DIR, "sessions");
+
+  let rfcFiles: string[] = [];
+  let sessionFiles: string[] = [];
+
+  try {
+    rfcFiles = await readdir(rfcMetricsDir);
+  } catch {
+    // No RFC metrics directory yet
+  }
+
+  try {
+    sessionFiles = await readdir(sessionMetricsDir);
+  } catch {
+    // No session metrics directory yet
+  }
+
+  const rfcMetricsList: RfcMetrics[] = [];
+  for (const file of rfcFiles) {
+    if (!file.endsWith(".metrics.yaml")) continue;
+    const metrics = await readYamlFile<RfcMetrics>(join(rfcMetricsDir, file));
+    if (metrics) rfcMetricsList.push(metrics);
+  }
+
+  const sessionMetricsList: SessionMetrics[] = [];
+  for (const file of sessionFiles) {
+    if (!file.endsWith(".metrics.yaml")) continue;
+    const metrics = await readYamlFile<SessionMetrics>(join(sessionMetricsDir, file));
+    if (metrics) sessionMetricsList.push(metrics);
+  }
+
+  // Apply date filters
+  const sinceDate = since ? new Date(since) : null;
+  const untilDate = until ? new Date(until) : null;
+
+  const filteredRfcs = rfcMetricsList.filter((m) => {
+    if (!m.generatedAt) return true;
+    const d = new Date(m.generatedAt);
+    if (isNaN(d.getTime())) return true;
+    if (sinceDate && d < sinceDate) return false;
+    if (untilDate && d > untilDate) return false;
+    return true;
+  });
+
+  const filteredSessions = sessionMetricsList.filter((m) => {
+    if (!m.generatedAt) return true;
+    const d = new Date(m.generatedAt);
+    if (isNaN(d.getTime())) return true;
+    if (sinceDate && d < sinceDate) return false;
+    if (untilDate && d > untilDate) return false;
+    return true;
+  });
+
+  // Aggregate per-skill
+  const skillData = new Map<
+    string,
+    {
+      invocations: number;
+      findingsSum: number;
+      findingsCount: number;
+      fixIterationsSum: number;
+      fixIterationsCount: number;
+      durationSum: number;
+      durationCount: number;
+    }
+  >();
+
+  function recordSkill(skill: string, data: Partial<{
+    findings: number;
+    fixIterations: number;
+    durationMs: number;
+  }>) {
+    let entry = skillData.get(skill);
+    if (!entry) {
+      entry = {
+        invocations: 0,
+        findingsSum: 0,
+        findingsCount: 0,
+        fixIterationsSum: 0,
+        fixIterationsCount: 0,
+        durationSum: 0,
+        durationCount: 0,
+      };
+      skillData.set(skill, entry);
+    }
+    entry.invocations++;
+    if (data.findings !== undefined) {
+      entry.findingsSum += data.findings;
+      entry.findingsCount++;
+    }
+    if (data.fixIterations !== undefined) {
+      entry.fixIterationsSum += data.fixIterations;
+      entry.fixIterationsCount++;
+    }
+    if (data.durationMs !== undefined) {
+      entry.durationSum += data.durationMs;
+      entry.durationCount++;
+    }
+  }
+
+  // From RFC metrics: pipeline steps (skill invocations), review findings, fix iterations
+  for (const rfc of filteredRfcs) {
+    for (const step of rfc.pipeline) {
+      if (step.skill) {
+        recordSkill(step.skill, {});
+      }
+    }
+    if (rfc.review && rfc.review.findingsCount !== undefined) {
+      recordSkill("fo-review", { findings: rfc.review.findingsCount });
+    }
+    if (rfc.fix) {
+      recordSkill("fo-fix", { fixIterations: rfc.fix.iterations });
+    }
+  }
+
+  // From session metrics: skill invocations with durations
+  for (const session of filteredSessions) {
+    for (const inv of session.skills) {
+      recordSkill(inv.skill, {
+        durationMs: inv.approximateDurationMs ?? undefined,
+      });
+    }
+  }
+
+  let perSkill: SkillAggregate[] = [];
+  for (const [skill, data] of skillData) {
+    if (skillFilter && skill !== skillFilter) continue;
+    perSkill.push({
+      skill,
+      invocations: data.invocations,
+      avgFindings: data.findingsCount > 0 ? data.findingsSum / data.findingsCount : null,
+      avgFixIterations: data.fixIterationsCount > 0 ? data.fixIterationsSum / data.fixIterationsCount : null,
+      avgDurationMs: data.durationCount > 0 ? data.durationSum / data.durationCount : null,
+    });
+  }
+
+  // Sort by invocations descending
+  perSkill.sort((a, b) => b.invocations - a.invocations);
+
+  if (skillFilter && perSkill.length === 0) {
+    perSkill = [];
+  }
+
+  const result: MetricsAggregateResult = {
+    command: "metrics.aggregate",
+    status: "ok",
+    skill: (skillFilter as string) ?? "all",
+    since: since ?? null,
+    until: until ?? null,
+    perSkill,
+    totalRfcs: filteredRfcs.length,
+    totalSessions: filteredSessions.length,
+  };
+
+  if (outputFormat === "pretty") {
+    context.logger.info(`[metrics.aggregate] ${perSkill.length} skill(s), ${filteredRfcs.length} RFC(s), ${filteredSessions.length} session(s)`);
+  }
+
+  return {
+    data: result,
+    exitCode: 0,
+    summary: `[metrics.aggregate] ${perSkill.length} skill(s) across ${filteredRfcs.length} RFC(s) and ${filteredSessions.length} session(s)`,
+  };
+}