@warpgogol/forge 4.0.0 → 4.1.2

package/os/session/session.module.ts

@@ -7,123 +7,149 @@
 </MODULE_CONTRACT>
 <CHANGE_SUMMARY>
   <item>RFC-0537: initial forgeSessionModule registering session.save, session.archive, session.validate, session.list commands.</item>
+  <item>RFC-1053: register metrics.aggregate command for skill effectiveness metrics aggregation.</item>
 </CHANGE_SUMMARY>
 */
 
 import type { ForgeModule } from "../../src/forge-module.ts";
 
-export const forgeSessionModule: ForgeModule = {
-  name: "forge-session",
-  version: "0.1.0",
-  runtime: "autonomous",
-  async register(registry) {
-    const { runSessionSave } = await import("./handlers/save.ts");
-    const { runSessionArchive } = await import("./handlers/archive.ts");
-    const { runSessionValidate } = await import("./handlers/validate.ts");
-    const { runSessionList } = await import("./handlers/list.ts");
-
-    registry.registerCommand({
-      name: "session.save",
-      description:
-        "Convert raw ATIF files from docs/sessions/.raw/ to structured markdown " +
-        "in docs/sessions/ with auto-extracted metadata. Idempotent — same raw " +
-        "file always produces the same output filename. Deletes raw file after " +
-        "conversion unless --keep-raw. Use --raw-file to process a specific file.",
-      scope: "workspace",
-      mutatesState: true,
-      writes: ["docs/sessions/*.md"],
-      reads: ["docs/sessions/.raw/*"],
-      cacheable: false,
-      flags: {
-        "raw-file": {
-          kind: "string",
-          description: "Process a specific raw file instead of scanning .raw/.",
-        },
-        "keep-raw": {
-          kind: "boolean",
-          description: "Do not delete raw file after conversion.",
-        },
-        "dry-run": {
-          kind: "boolean",
-          description: "Preview without writing files.",
+export async function createForgeSessionModule(): Promise<ForgeModule> {
+  const { runSessionSave } = await import("./handlers/save.ts");
+  const { runSessionArchive } = await import("./handlers/archive.ts");
+  const { runSessionValidate } = await import("./handlers/validate.ts");
+  const { runSessionList } = await import("./handlers/list.ts");
+  const { runMetricsAggregate } = await import("./handlers/metrics-aggregate.ts");
+  return {
+    name: "forge-session",
+    version: "0.1.0",
+    runtime: "autonomous",
+    declarations: [],
+    commands: [
+      {
+        name: "session.save",
+        description:
+          "Convert raw ATIF files from docs/sessions/.raw/ to structured markdown " +
+          "in docs/sessions/ with auto-extracted metadata. Idempotent — same raw " +
+          "file always produces the same output filename. Deletes raw file after " +
+          "conversion unless --keep-raw. Use --raw-file to process a specific file.",
+        scope: "workspace",
+        mutatesState: true,
+        writes: ["docs/sessions/*.md"],
+        reads: ["docs/sessions/.raw/*"],
+        cacheable: false,
+        flags: {
+          "raw-file": {
+            kind: "string",
+            description: "Process a specific raw file instead of scanning .raw/.",
+          },
+          "keep-raw": {
+            kind: "boolean",
+            description: "Do not delete raw file after conversion.",
+          },
+          "dry-run": {
+            kind: "boolean",
+            description: "Preview without writing files.",
+          },
         },
+        execute: runSessionSave,
       },
-      execute: runSessionSave,
-    });
-
-    registry.registerCommand({
-      name: "session.archive",
-      description:
-        "Move session files older than --max-age-days (default 7) from " +
-        "docs/sessions/ to docs/sessions/archive/. Bidirectional: files in " +
-        "archive/ younger than threshold are moved back to docs/sessions/. " +
-        "Use --dry-run to preview. Age is computed from frontmatter date, " +
-        "not filesystem mtime. Prefer the docs.archive umbrella command " +
-        "unless you need to archive only sessions.",
-      scope: "workspace",
-      mutatesState: true,
-      writes: ["docs/sessions/*.md", "docs/sessions/archive/**"],
-      reads: ["docs/sessions/**/*.md"],
-      cacheable: false,
-      flags: {
-        "max-age-days": {
-          kind: "string",
-          description: "Age threshold in days (default 7).",
-        },
-        "dry-run": {
-          kind: "boolean",
-          description: "Preview what would be moved without touching the filesystem.",
+      {
+        name: "session.archive",
+        description:
+          "Move session files older than --max-age-days (default 7) from " +
+          "docs/sessions/ to docs/sessions/archive/. Bidirectional: files in " +
+          "archive/ younger than threshold are moved back to docs/sessions/. " +
+          "Use --dry-run to preview. Age is computed from frontmatter date, " +
+          "not filesystem mtime. Prefer the docs.archive umbrella command " +
+          "unless you need to archive only sessions.",
+        scope: "workspace",
+        mutatesState: true,
+        writes: ["docs/sessions/*.md", "docs/sessions/archive/**"],
+        reads: ["docs/sessions/**/*.md"],
+        cacheable: false,
+        flags: {
+          "max-age-days": {
+            kind: "string",
+            description: "Age threshold in days (default 7).",
+          },
+          "dry-run": {
+            kind: "boolean",
+            description: "Preview what would be moved without touching the filesystem.",
+          },
         },
+        execute: runSessionArchive,
       },
-      execute: runSessionArchive,
-    });
-
-    registry.registerCommand({
-      name: "session.validate",
-      contract: "session",
-      rules: [],
-      description:
-        "Validate session frontmatter schema (SES-01), id-filename match (SES-02), " +
-        "RFC-id existence (SES-03), raw file hygiene (SES-04), and non-markdown " +
-        "file detection (SES-05). Pass --id to validate a single file, " +
-        "or run without arguments for all. On-demand only — not integrated into " +
-        "build.check.",
-      scope: "workspace",
-      flags: {
-        id: { kind: "string", description: "Target a single session by id." },
-      },
-      reads: ["docs/sessions/**/*.md", "docs/rfcs/**/*.md"],
-      execute: runSessionValidate,
-    });
-
-    registry.registerCommand({
-      name: "session.list",
-      description:
-        "List all sessions. Filter with --date-from, --date-to, --rfc, --type flags. " +
-        "Use --json for machine-readable output. Parses frontmatter on the fly. " +
-        "Includes archived sessions (marked with archived: true).",
-      scope: "workspace",
-      flags: {
-        "date-from": {
-          kind: "string",
-          description: "Filter sessions from this date (YYYY-MM-DD, inclusive).",
-        },
-        "date-to": {
-          kind: "string",
-          description: "Filter sessions up to this date (YYYY-MM-DD, inclusive).",
+      {
+        name: "session.validate",
+        contract: "session",
+        rules: [],
+        description:
+          "Validate session frontmatter schema (SES-01), id-filename match (SES-02), " +
+          "RFC-id existence (SES-03), raw file hygiene (SES-04), and non-markdown " +
+          "file detection (SES-05). Pass --id to validate a single file, " +
+          "or run without arguments for all. On-demand only — not integrated into " +
+          "build.check.",
+        scope: "workspace",
+        flags: {
+          id: { kind: "string", description: "Target a single session by id." },
         },
-        rfc: {
-          kind: "string",
-          description: "Filter by related RFC id (e.g. RFC-0537).",
+        reads: ["docs/sessions/**/*.md", "docs/rfcs/**/*.md"],
+        execute: runSessionValidate,
+      },
+      {
+        name: "session.list",
+        description:
+          "List all sessions. Filter with --date-from, --date-to, --rfc, --type flags. " +
+          "Use --json for machine-readable output. Parses frontmatter on the fly. " +
+          "Includes archived sessions (marked with archived: true).",
+        scope: "workspace",
+        flags: {
+          "date-from": {
+            kind: "string",
+            description: "Filter sessions from this date (YYYY-MM-DD, inclusive).",
+          },
+          "date-to": {
+            kind: "string",
+            description: "Filter sessions up to this date (YYYY-MM-DD, inclusive).",
+          },
+          rfc: {
+            kind: "string",
+            description: "Filter by related RFC id (e.g. RFC-0537).",
+          },
+          type: {
+            kind: "string",
+            description:
+              "Filter by session type (mission, grilling, implementation, review, fix, freeform).",
+          },
         },
-        type: {
-          kind: "string",
-          description:
-            "Filter by session type (mission, grilling, implementation, review, fix, freeform).",
+        reads: ["docs/sessions/**/*.md"],
+        execute: runSessionList,
+      },
+      {
+        name: "metrics.aggregate",
+        description:
+          "Query and aggregate skill effectiveness metrics from docs/metrics/ files. " +
+          "Returns per-skill statistics (invocations, avgFindings, avgFixIterations, avgDurationMs). " +
+          "Use --skill to filter by skill name, --since/--until for date range.",
+        scope: "workspace",
+        flags: {
+          skill: {
+            kind: "string",
+            description: "Filter by skill name (e.g. fo-review).",
+          },
+          since: {
+            kind: "string",
+            description: "Only include metrics generated since this date (YYYY-MM-DD).",
+          },
+          until: {
+            kind: "string",
+            description: "Only include metrics generated until this date (YYYY-MM-DD).",
+          },
         },
+        reads: ["docs/metrics/**/*.yaml"],
+        execute: runMetricsAggregate,
       },
-      reads: ["docs/sessions/**/*.md"],
-      execute: runSessionList,
-    });
-  },
-};
+    ],
+    pipelines: [],
+  };
+}

package/os/session/types.ts

@@ -12,12 +12,14 @@ validation rule identifiers.
 <CHANGE_SUMMARY>
   <item>RFC-0537: initial session domain types, constants, and SES rule identifiers.</item>
   <item>RFC-0884: add checkpoint interfaces, extend SessionFrontmatter with optional checkpoint fields, add SES-06 rule.</item>
+  <item>RFC-1053: add metrics type interfaces (RfcMetrics, SessionMetrics, MetricsAggregateResult) and METRICS_DIR constant.</item>
 </CHANGE_SUMMARY>
 */
 
 export const SESSION_DIR = "docs/sessions";
 export const SESSION_RAW_SUBDIR = ".raw";
 export const SESSION_ARCHIVE_SUBDIR = "archive";
+export const METRICS_DIR = "docs/metrics";
 export const SESSION_ID_PATTERN = /^\d{4}-\d{2}-\d{2}-\d{2}-\d{2}-\d{2}-[0-9a-f]{6}$/;
 export const SESSION_FILE_PATTERN = /^\d{4}-\d{2}-\d{2}-\d{2}-\d{2}-\d{2}-[0-9a-f]{6}\.md$/;
 
@@ -133,6 +135,7 @@ export interface SessionSaveResult {
     files: string[];
     commands: string[];
   };
+  metricsPath?: string;
   dryRun: boolean;
 }
 
@@ -201,3 +204,99 @@ export interface SessionListResult {
   sessions: SessionListEntry[];
   count: number;
 }
+
+// ── RFC-1053: Skill effectiveness metrics ──
+
+export interface RfcPipelineStep {
+  step: string;
+  skill: string | null;
+  commitSha: string | null;
+  timestamp: string | null;
+}
+
+export interface ReviewMetrics {
+  findingsCount: number;
+  findingsByAxis: Record<string, number>;
+  verdict: string | null;
+}
+
+export interface FixMetrics {
+  fixesApplied: number;
+  commitSha: string | null;
+  iterations: number;
+}
+
+export interface VerificationMetrics {
+  probesTotal: number;
+  probesPassed: number;
+  evidencePath: string | null;
+}
+
+export interface ResultMetrics {
+  acceptanceCriteriaTotal: number;
+  acceptanceCriteriaMet: number;
+}
+
+export interface RfcTimings {
+  firstCommitAt: string | null;
+  lastCommitAt: string | null;
+  totalDurationMs: number | null;
+}
+
+export interface RfcMetrics {
+  rfcId: string;
+  generatedAt: string;
+  pipeline: RfcPipelineStep[];
+  review: ReviewMetrics | null;
+  fix: FixMetrics | null;
+  verification: VerificationMetrics | null;
+  result: ResultMetrics;
+  timings: RfcTimings;
+}
+
+export interface SessionDocumentRef {
+  rfcId: string;
+  status: string;
+  metricsFile: string | null;
+}
+
+export interface SessionSkillInvocation {
+  skill: string;
+  approximateDurationMs: number | null;
+}
+
+export interface InsightSummary {
+  total: number;
+  byCategory: Record<string, number>;
+}
+
+export interface SessionMetrics {
+  sessionId: string;
+  generatedAt: string;
+  date: string;
+  durationMs: number;
+  approximateDurations: true;
+  documents: SessionDocumentRef[];
+  skills: SessionSkillInvocation[];
+  insights: InsightSummary | null;
+  commits: string[];
+}
+
+export interface SkillAggregate {
+  skill: string;
+  invocations: number;
+  avgFindings: number | null;
+  avgFixIterations: number | null;
+  avgDurationMs: number | null;
+}
+
+export interface MetricsAggregateResult {
+  command: "metrics.aggregate";
+  status: "ok";
+  skill: string | "all";
+  since: string | null;
+  until: string | null;
+  perSkill: SkillAggregate[];
+  totalRfcs: number;
+  totalSessions: number;
+}

package/os/spec/spec.module.ts

@@ -14,20 +14,21 @@
 
 import type { ForgeModule } from "../../src/forge-module.ts";
 
-export const forgeSpecModule: ForgeModule = {
-  name: "forge-spec",
-  version: "0.2.0",
-  runtime: "autonomous",
-  async register(registry) {
-    const { runSpecValidate } = await import("./spec-validate.ts");
+export async function createForgeSpecModule(): Promise<ForgeModule> {
+const { runSpecValidate } = await import("./spec-validate.ts");
     const { runSpecStatus } = await import("./spec-status.ts");
     const { runSpecMaterialize } = await import("./spec-materialize.ts");
     const { runSpecLiveMerge } = await import("./live-spec-merge.ts");
     const { runSpecLiveList } = await import("./live-spec-list.ts");
     const { runSpecLiveShow } = await import("./live-spec-show.ts");
     const { runSpecLiveValidate } = await import("./live-spec-validate.ts");
-
-    registry.registerCommand({
+  return {
+  name: "forge-spec",
+  version: "0.2.0",
+  runtime: "autonomous",
+    declarations: [],
+  commands: [
+    {
       name: "spec.validate",
       contract: "spec",
       rules: [],
@@ -45,9 +46,8 @@ export const forgeSpecModule: ForgeModule = {
       },
       reads: ["docs/specs/**/*"],
       execute: runSpecValidate,
-    });
-
-    registry.registerCommand({
+    },
+    {
       name: "spec.status",
       description:
         "Show roadmap progress for vendored specs. " +
@@ -61,9 +61,8 @@ export const forgeSpecModule: ForgeModule = {
       },
       reads: ["docs/specs/**/*", "docs/rfcs/**/*.md"],
       execute: runSpecStatus,
-    });
-
-    registry.registerCommand({
+    },
+    {
       name: "spec.materialize",
       description:
         "Scaffold RFC files for the next N front nodes of a spec roadmap. " +
@@ -78,9 +77,8 @@ export const forgeSpecModule: ForgeModule = {
         nodes: { kind: "string", description: "Comma-separated explicit node ids to materialize." },
       },
       execute: runSpecMaterialize,
-    });
-
-    registry.registerCommand({
+    },
+    {
       name: "spec.live.merge",
       description:
         "Merge deltas from an implemented RFC's ## Design section into a living feature spec " +
@@ -98,9 +96,8 @@ export const forgeSpecModule: ForgeModule = {
         "dry-run": { kind: "boolean", description: "Preview deltas without writing files." },
       },
       execute: runSpecLiveMerge,
-    });
-
-    registry.registerCommand({
+    },
+    {
       name: "spec.live.list",
       description:
         "List all living feature specs in docs/specs/live/. " +
@@ -108,9 +105,8 @@ export const forgeSpecModule: ForgeModule = {
       scope: "workspace",
       reads: ["docs/specs/live/*.md"],
       execute: runSpecLiveList,
-    });
-
-    registry.registerCommand({
+    },
+    {
       name: "spec.live.show",
       description:
         "Show a single living feature spec by domain. " +
@@ -121,9 +117,8 @@ export const forgeSpecModule: ForgeModule = {
         domain: { kind: "string", required: true, description: "Domain name (filename without .md)." },
       },
       execute: runSpecLiveShow,
-    });
-
-    registry.registerCommand({
+    },
+    {
       name: "spec.live.validate",
       contract: "spec",
       rules: [],
@@ -135,6 +130,10 @@ export const forgeSpecModule: ForgeModule = {
       scope: "workspace",
       reads: ["docs/specs/live/*.md", "docs/rfcs/**/*.md"],
       execute: runSpecLiveValidate,
-    });
-  },
-};
+    }
+  ],
+  pipelines: [
+
+  ]};
+}
+;

package/os/werkstatt/werkstatt.module.ts

@@ -20,8 +20,9 @@ export const forgeWerkstattModule: ForgeModule = {
   name: "forge-werkstatt",
   version: "0.1.0",
   runtime: "werkstatt-adapter",
-  async register(registry) {
-    registry.registerCommand({
+    declarations: [],
+  commands: [
+    {
       name: "werkstatt.lock.status",
       description: "Report all Werkstatt locks, their age, owner, and staleness (RFC-0362).",
       scope: "workspace",
@@ -29,8 +30,8 @@ export const forgeWerkstattModule: ForgeModule = {
       flags: {},
       reads: [".werkstatt/locks/**"],
       execute: runWerkstattLockStatus,
-    });
-    registry.registerCommand({
+    },
+    {
       name: "werkstatt.lock.recover",
       description:
         "Classify and clean stale locks and staging artifacts (RFC-0362). Flags: --scope, --purge.",
@@ -48,8 +49,8 @@ export const forgeWerkstattModule: ForgeModule = {
       reads: [".werkstatt/locks/**"],
       cacheable: false,
       execute: runWerkstattLockRecover,
-    });
-    registry.registerCommand({
+    },
+    {
       name: "werkstatt.operation.validate",
       contract: "werkstatt",
       rules: [],
@@ -60,6 +61,8 @@ export const forgeWerkstattModule: ForgeModule = {
       flags: {},
       reads: ["packages/os/site-kernel-handoff/src/**/*.ts"],
       execute: runWerkstattOperationValidate,
-    });
-  },
-};
+    }
+  ],
+  pipelines: [
+
+  ]};

package/os/workflow/index.ts

@@ -14,7 +14,7 @@
 </CHANGE_SUMMARY> 
 */
 
-export { forgeWorkflowModule } from "./workflow.module.ts";
+export { createForgeWorkflowModule } from "./workflow.module.ts";
 export { runWorkflowLint, runWorkflowList, runWorkflowAmendList } from "./handlers.ts";
 export type {
   WorkflowPhase,

package/os/workflow/workflow.module.ts

@@ -13,14 +13,16 @@
 
 import type { ForgeModule } from "../../src/forge-module.ts";
 
-export const forgeWorkflowModule: ForgeModule = {
+export async function createForgeWorkflowModule(): Promise<ForgeModule> {
+const { runWorkflowLint, runWorkflowList, runWorkflowAmendList } =
+      await import("./handlers.ts");
+  return {
   name: "workflow",
   version: "0.1.0",
   runtime: "autonomous",
-  async register(registry) {
-    const { runWorkflowLint, runWorkflowList, runWorkflowAmendList } =
-      await import("./handlers.ts");
-    registry.registerCommand({
+    declarations: [],
+  commands: [
+    {
       name: "workflow.lint",
       contract: "workflow",
       rules: [],
@@ -32,8 +34,8 @@ export const forgeWorkflowModule: ForgeModule = {
       supportsAllSites: true,
       reads: [".agents/workflows/**/*.md", ".windsurf/workflows/**/*.md"],
       execute: runWorkflowLint,
-    });
-    registry.registerCommand({
+    },
+    {
       name: "workflow.list",
       description:
         "List .agents/workflows entries with phase, IO summary, and next workflow (RFC-0075).",
@@ -42,8 +44,8 @@ export const forgeWorkflowModule: ForgeModule = {
       supportsAllSites: true,
       reads: [".agents/workflows/**/*.md", ".windsurf/workflows/**/*.md"],
       execute: runWorkflowList,
-    });
-    registry.registerCommand({
+    },
+    {
       name: "workflow-amend.list",
       description:
         "List .agents/workflows-amend entries with phase, IO summary, and next workflow (RFC-0136).",
@@ -52,6 +54,10 @@ export const forgeWorkflowModule: ForgeModule = {
       supportsAllSites: true,
       reads: [".agents/workflows-amend/**/*.md"],
       execute: runWorkflowAmendList,
-    });
-  },
-};
+    }
+  ],
+  pipelines: [
+
+  ]};
+}
+;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@warpgogol/forge",
-  "version": "4.0.0",
+  "version": "4.1.2",
   "private": false,
   "type": "module",
   "license": "Apache-2.0",
@@ -164,6 +164,7 @@
     "lint": "pnpm exec eslint \"src/**/*.ts\" \"os/**/*.ts\"",
     "typecheck": "pnpm exec tsc -p tsconfig.json --noEmit",
     "test": "vitest run --passWithNoTests",
+    "test:coverage": "vitest run --coverage --passWithNoTests",
     "test:watch": "vitest",
     "test:tarball:node24": "node test-fixtures/node24-consumer/smoke.mjs"
   },
@@ -182,6 +183,7 @@
     "fast-check": "^4.9.0",
     "typescript": "^6.0.3",
     "typescript-eslint": "8.68.0",
+    "@vitest/coverage-v8": "^4.1.11",
     "vitest": "^4.1.11"
   },
   "engines": {